All posts
Forward Development

Medusa 2.23.0: planning the Express 5 and React 19 upgrade

Medusa 2.23.0 moves to Express 5, React 19, Vite 8 and Tailwind CSS 4. How to audit custom routes and admin code, and when to pin to 2.22.x.

  • Medusa.js
  • Migrations
  • Operations

Your Medusa backend is on 2.22.x. It has a src/api/middlewares.ts with a dozen matchers, a few custom routes, and some admin widgets someone wrote to make the order screen usable. Then 2.23.0 ships. By version number it is a minor release. In practice it bumps Express to 5, React to 19, Vite to 8, Tailwind CSS to 4 and TanStack Table to v9, and changes the major versions of the Redis clients and OpenTelemetry packages. Some of that breaks loudly at startup. The parts that cost you a week break quietly, in the browser, after deploy.

This article covers what each bump affects in a typical project, how to audit before you touch package.json, and how to decide between upgrading now and staying on 2.22.x.

The dependencies have to move as one set

The release notes are clear that the project's own copies of these libraries have to move in the same install as the @medusajs/* packages. Only update the ones your package.json already lists:

  • react, react-dom to ^19.3.1; @types/react, @types/react-dom to ^19.3.0
  • express to ^5.3.0; @types/express to ^5.0.6
  • vite to ^8.3.8; tailwindcss to ^4.3.5
  • @tanstack/react-table 9.3.1, @tanstack/react-query 5.107.1, react-router-dom 7.18.5, zod 4.6.7, i18next 27.1.1, react-i18next 18.0.1
  • the OpenTelemetry packages, with @opentelemetry/sdk-trace-node removed and replaced by @opentelemetry/sdk-trace ^3.0.0

@medusajs/ui is not on the 2.x line. The notes give it as 4.3.0, so check the registry rather than forcing 2.23.0.

React is the one that bites. @medusajs/ui, @medusajs/draft-order and @medusajs/loyalty-plugin declare React ^19.3.1 as a peer, and @medusajs/dashboard depends on React 19 directly. If you keep React 18, or widen the range to ^18 || ^19 to be safe, the package manager installs two copies. The install passes and so does the build. Then admin widgets fail at runtime with an "Invalid hook call" class of error, nowhere near the cause. Vite has the same problem: the official starters list vite, and leaving it at ^7 gives you two copies. Pin exactly what the notes say.

Express 5 changes how your matchers and routes behave

Medusa now matches routes with path-to-regexp 8, so every matcher string in src/api/middlewares.ts needs checking, along with the middleware files of any plugin you maintain.

What keeps working: a bare *. Medusa rewrites /admin/products/* to /admin/products/{*splat0}, and it matches the same paths. RegExp matchers pass through unchanged.

What throws at startup: regex groups like /admin/(products|collections), optional params like /:id?, and +. You get Unexpected {char} at index {n} from path-to-regexp. That is the easy case, because the server will not boot. Rewrite optional segments as /custom{/:id}, or switch to a RegExp.

What fails silently:

  • Wildcard captures moved. Code that reads req.params[0] now gets nothing. A converted bare * lands in req.params.splat0, and a hand-written {*splat} lands in req.params.splat. These are arrays of path segments, not strings, so join them if you need a string.
  • req.body can be undefined. Express 4 gave {}. Routes configured with bodyParser: false now get undefined. Guard every read.
  • /x/* no longer covers /x. A bodyParser or additionalDataValidator config on /store/custom/* stops applying to /store/custom itself. Nothing errors. The config just stops applying, and validation you relied on goes missing.

Run grep -rn "matcher\|req.params\[\|bodyParser" src/ before anything else. That list is your Express audit.

The admin is where most of the work hides

Anything under src/admin/ is affected by four bumps at once.

React 19 types. useRef<T>() now needs an argument, and useRef<T>(null) returns RefObject<T | null>. Fix what tsc reports and nothing else. This is not the time to rewrite components to use React 19 features.

Vite 8. Rolldown and Oxc replace Rollup and esbuild. If medusa-config.ts customises admin.vite, rename build.rollupOptions to build.rolldownOptions and esbuild to oxc, and remove output.interop. admin.vite is now typed against Vite's InlineConfig, so a stray key fails the typecheck. Projects using node10 module resolution without skipLibCheck have to change one or the other. Default imports from CommonJS packages may resolve to a different value, so prefer named imports. The default browser target is now Chrome/Edge 111, Firefox 114 and Safari 16.4. If your back office runs on locked-down older machines, set build.target yourself.

Tailwind CSS 4. The admin build ignores your tailwind.config.* and postcss.config.*. Tailwind 3 class names do not error. They render differently or not at all. outline-none becomes outline-hidden, and rounded becomes rounded-sm. npx @tailwindcss/upgrade rewrites files in place, so in a monorepo, revert anything it changes outside src/admin/. A storefront still on Tailwind 3 should not be touched. Only a visual check catches what this tool misses.

TanStack Table v9. This only matters if you use DataTable with custom row types or select columns, or DataGrid. Columns built from v8 createColumnHelper no longer type-check, so move to createDataTableColumnHelper. Passing row.getToggleSelectedHandler() to Checkbox now throws on click. getIsSomePageRowsSelected() now returns true when every row is selected, which breaks indeterminate header checkboxes. DataGrid pinning uses "start"/"end". Jest suites may need @tanstack added to transformIgnorePatterns.

If you publish plugins with admin customisations, rebuild them with npx medusa plugin:build against this release.

Redis and OpenTelemetry need their own check

The release also changes Redis configuration: sessions move to node-redis, and the queue stack moves to BullMQ 6 and ioredis 6. It also moves OpenTelemetry to SDK 3. The notes flag both as breaking. Diff your Redis options in medusa-config.ts and your instrumentation.ts against the upgrade guide line by line, and test them against a real Redis rather than an in-memory fallback. A sessions misconfiguration that only appears under load is not something you want to find in production.

A staged plan that keeps production boring

  1. Branch and inventory. List every custom matcher, every req.params/req.body read, every file under src/admin/, your admin.vite block, your Redis options and your instrumentation file. Most projects find the work is smaller or larger than they expected, rarely about right.
  2. Bump in one commit. Update all @medusajs/* packages and the listed third-party majors together. Delete the lockfile's stale entries and confirm that npm ls react vite shows a single copy of each.
  3. Boot and typecheck. Fix the path-to-regexp startup errors, then the tsc errors. Those are the loud failures.
  4. Hunt the silent ones. Write or extend integration tests that hit each custom route with and without a trailing segment, and with an empty body. Assert that validation still rejects bad payloads on the bare path.
  5. Click through the admin. Check every widget and custom route in a real browser, including table selection and the indeterminate checkbox. Compare screenshots against 2.22.x for Tailwind drift.
  6. Staging under realistic Redis. Run jobs, sessions and traces for a day before promoting.

Move now or pin to 2.22.7

If your project has few custom matchers and little admin code, upgrade now. The work is mechanical, and the gap only grows. If you have a large src/admin/, custom DataTable code, or plugins you maintain, pin @medusajs/* exactly to 2.22.7, the latest 2.22.x release listed, and schedule the upgrade as its own piece of work rather than slipping it into a feature sprint. Do not sit on caret ranges that might float you onto 2.23.0 during an unrelated install.

If you are planning a move to Medusa from Magento or another platform, start on 2.23.0 so you never write Express 4 matchers in the first place. Our Magento 2 and Adobe Commerce to Medusa or Vendure migration page covers how we sequence that. If you want a second pair of eyes on your audit list before you bump, get in touch.

Need this done on a real stack?

Magento 2, Adobe Commerce, migrations to Medusa.js or Vendure, enterprise Next.js, WordPress, and AI automation.

Contact us