Use this “nuxeo-2025-upgrade” Claude skill to take the pain out of Nuxeo 2025 migration

Remember the old days when upgrading your code to the latest Nuxeo release used to take days, if not weeks :D?

If you have done one of these upgrades before, you know the work: You bump versions. You chase the javax to jakarta rename across the codebase. You figure out which APIs were removed, moved, or renamed. Then you keep fixing build errors until everything finally compiles. It is not always hard work, but it is scattered work. It touches a lot of files, and a few small traps can easily cost you an afternoon. :)

Those days should be mostly behind us now.

We packaged what we learned doing a real Nuxeo 2023 to 2025 migration into a small Claude Code skill that you can run against your own project.

Here is the repo: https://github.com/maretha-io/nuxeo-lts-2025-upgrade

And here are the official Nuxeo upgrade notes from LTS 2023 to LTS 2025: https://doc.nuxeo.com/nxdoc/upgrade-from-lts-2023-to-lts-2025/

What it is

A Claude Code skill is just a set of instructions Claude Code follows.

This one lives in a plain GitHub repo. No install. No marketplace. You clone it, open Claude Code inside it, run one command, and point it at your Nuxeo project.

The important part is that it does the upgrade in your project, not inside the skill repo.

How to use it

git clone https://github.com/maretha-io/nuxeo-lts-2025-upgrade
cd nuxeo-lts-2025-upgrade
claude

Then, in Claude Code:

/nuxeo-2025-upgrade

It asks for the absolute path to your project and then starts the upgrade work.

You will need JDK 21 and access to the Nuxeo 2025 artifacts on the machine. The LTS releases are subscription-only, so Nuxeo 2025 will not build without access to the right artifacts.

What it handles

The skill handles the repetitive parts of the upgrade:

• Versions: nuxeo-parent, platform properties, Java 21, marketplace target platform, and CI.
• Jakarta EE 10: the javax.{inject,ws.rs,servlet,mail} to jakarta.* changes, plus the servlet API dependency.
• Removed and relocated APIs: Elasticsearch core to nuxeo-core-search, WebEngine FormData/getForm() to MultivaluedMap/getRequest(), the comment-core merge, and more.
• Dropped libraries: Joda-Time, old Lombok, commons-lang, PDFBox 2.
• Test infrastructure: mail mock, search feature, bulk scrollers, and directory test setup changes in 2025.
• Build-and-fix loop: it compiles on JDK 21, reads the errors, and fixes them against a before and after reference.

The traps it already knows about

A few of these are very easy to lose hours on:

• An old commons-io pin under 2.17 can compile fine but fail at runtime inside Nuxeo's SQLDirectory.
• A stale Lombok version can throw a cryptic JCImport.qualid error as soon as you compile on JDK 21.

These are already encoded, so Claude can fix them instead of discovering them the hard way.

And the Web UI? Mostly leave it alone

This is the part that is easy to get wrong.

The Nuxeo Web UI upgrade is mostly transparent. Nuxeo Web UI 2025 is still Polymer 3. The legacy Polymer({}) and <dom-module> elements are intentional. Do not convert them to Lit just because they look old.

For Studio UI projects, the skill verifies 2025-readiness instead of rewriting hundreds of elements. It checks the target platform, dependency versions, and the actual Web UI changes between branches.

Knowing what not to touch is part of the upgrade.

Limitations

This targets server-side Java/Maven projects and Studio Web UI verification.

It will not migrate your Studio model, doctypes, or workflows. That work is done in Studio.

The exact patch version and your Studio GAV are environment-specific, so the skill asks for those instead of guessing.

Treat the output as a first pass that you review, not a black box.

Once you get to this point, start testing and fixing bugs :) .

One deployment gotcha

One important deployment gotcha: Nuxeo 2025's search backend is now modular.

The distribution no longer bundles a search client by default, so check the official upgrade notes and the search setup documentation for the packages your setup needs.

If you are on OpenSearch 1.x, make sure you explicitly add:

nuxeo-search-client-opensearch1
nuxeo-audit-opensearch1

Otherwise search and audit can come up unconfigured, which is not the surprise you want after the upgrade.

Try it and let us know how it goes!

Clone the repo, run it against a branch of your project, and review the changes. If you hit a weird edge case, send it our way at https://maretha.io/ . Every one of those makes the next upgrade easier.

← All insights