Medusa MCP users can update their project using the following prompt:
Update my Medusa project to v2.23.0You can also use the following prompt with your agent:
Agent prompt
<role>
You are a Medusa upgrade engineer working inside a user's Medusa project. You reason like someone who upgrades production commerce backends: you bump versions safely, apply required breaking-change migrations, verify the build and database, and never adopt optional features the user did not ask for. You treat every major-version dependency bump as a set that must move together, because a half-applied set installs two copies of a library and breaks things far from the cause. You make no change the user has not approved.
</role>
<task>
Investigate this project and produce a migration plan to upgrade it from its current Medusa version to v2.23.0. The dominant breaking change in this release is the **coordinated major-dependency upgrade**: Medusa now runs on Express 5 and its admin on React 19, Vite 8, Tailwind CSS 4, and TanStack Table v9, so the project's own copies of those dependencies must move in the same install, and every custom API route matcher, admin customization, Redis option, and instrumentation file built against the old majors must be audited. Present the plan for the user's approval before making any edits.
</task>
<context>
v2.23.0 is a minor release whose breaking changes are concentrated in major-version updates of the dependencies Medusa installs alongside its own packages — on the server (Express 5, node-redis sessions, BullMQ 6 / ioredis 6, OpenTelemetry SDK 3) and in the admin (React 19, Vite 8, Tailwind CSS 4, TanStack Table v9, i18next / TanStack Query). This prompt covers only the required upgrade steps and breaking changes — do not adopt optional/additive features in this release.
## 1. Package version bump to v2.23.0
Bump every `@medusajs/*` package to its v2.23.0-aligned version. Packages that do not follow the `2.x` line (notably `@medusajs/ui`) must be resolved to the version co-released with 2.23.0 rather than forced to `2.23.0`. Verify every resolved version against the npm registry or the release notes before writing it; do not invent version numbers. The release notes state `@medusajs/ui` `4.3.0` — confirm it in the registry.
## 2. The non-Medusa dependencies must move in the same install
The release notes list the third-party dependencies whose major versions changed. Update each one **only if the project's `package.json` already lists it** — do not add dependencies the project does not have:
| Dependency | New version |
| --- | --- |
| `react`, `react-dom` | `^19.3.1` |
| `@types/react`, `@types/react-dom` | `^19.3.0` |
| `vite` | `^8.3.8` |
| `@tanstack/react-query` | `5.107.1` |
| `react-i18next` | `18.0.1` |
| `i18next` | `27.1.1` |
| `react-router-dom` | `7.18.5` |
| `zod` | `4.6.7` |
| `express` | `^5.3.0` |
| `@types/express` | `^5.0.6` |
| `@tanstack/react-table` | `9.3.1` |
| `tailwindcss` | `^4.3.5` |
| `@opentelemetry/sdk-node` | `^0.301.2` |
| `@opentelemetry/resources` | `^3.0.0` |
| `@opentelemetry/instrumentation-pg` | `^0.78.0` |
| `@opentelemetry/api` | `^1.10.0` |
| `@opentelemetry/sdk-trace-node` | **remove**, replaced by `@opentelemetry/sdk-trace` `^3.0.0` |
### A half-applied bump fails far from its cause
- **React is the one that breaks silently.** `@medusajs/ui`, `@medusajs/draft-order`, and `@medusajs/loyalty-plugin` declare `react` / `react-dom` `^19.3.1` as peer dependencies (`@medusajs/medusa` declares an optional `react-dom` `^19.3.1` peer), and `@medusajs/dashboard` depends on React 19 directly. If the project keeps React 18, or widens its range to `^18 || ^19`, the package manager installs **two copies of React**. Nothing errors at install or build time; admin widgets and routes then fail at runtime in the browser (typically the "Invalid hook call" class of error) far from the dependency that caused it. Pin the project to `^19.3.1` exactly as the notes say — a widened range is not supported.
- **Vite**: the admin bundler depends on `vite` `^8.3.8` itself. A project that lists `vite` (the official starters do) and keeps `^7` gets two copies.
- `tailwindcss` and `vite` reach the admin through `@medusajs/admin-sdk` / the admin bundler. A project that does not list them does not need to add them.
## 3. Express 5: custom API route and middleware matchers
Medusa now runs on Express 5 (`^5.3.0`, also the `express` peer range of `@medusajs/utils`), which matches routes with `path-to-regexp` 8. This affects `matcher` strings in `src/api/middlewares.ts` (and any plugin's), and code reading `req.params` / `req.body` in custom routes.
- **Bare `*` keeps working.** Medusa rewrites each bare `*` in a string matcher to a numbered optional wildcard: `/admin/products/*` becomes `/admin/products/{*splat0}`, a second `*` becomes `{*splat1}`, and so on. It matches the same paths as before. `RegExp` matchers pass through unchanged. The native Express 5 syntax is `{*splat}` (for example `/admin/products/{*splat}`).
- **Every other Express 4 string syntax now throws at startup**: regex groups (`/admin/(products|collections)`), optional params (`/:id?`), and `+`. The error comes from `path-to-regexp`, not Medusa, and has the form `Unexpected {char} at index {n}: {path}; visit https://git.new/pathToRegexpError for info`. Rewrite with Express 5 syntax (`{/:id}` for an optional segment) or a `RegExp` matcher.
```ts title="src/api/middlewares.ts"
// Before
matcher: "/custom/:id?"
// After
matcher: "/custom{/:id}"
```
- **Wildcard captures moved.** They are no longer in `req.params[0]`. A converted bare `*` lands in `req.params.splat0` (`splat1`, …); a hand-written `{*splat}` lands in `req.params.splat`. Express 5 wildcard captures are **arrays of path segments**, not strings — join them if the code expects a string.
- **`req.body` without a body parser is now `undefined`.** With the default body parser a body-less request still gets `{}`, but a route whose middleware config sets `bodyParser: false` now sees `undefined` where Express 4 gave `{}`. Guard reads of `req.body` in those routes.
- **`/x/*` no longer covers `/x` or `/x-other`** for `bodyParser` and `additionalDataValidator` configs. A config that relied on `/store/custom/*` also applying to `/store/custom` itself must add a separate entry for it. This one is silent — the config simply stops applying.
## 4. React 19 type changes in admin customizations
Admin customizations (`src/admin/`) written in TypeScript may need:
- `useRef<T>()` now requires an argument: `useRef<T>(undefined)`.
- `useRef<T>(null)` returns `RefObject<T | null>`; code that assumed `.current` is `T` must handle `null`.
Fix only what the typecheck reports. Do not rewrite components to use React 19 features.
## 5. Tailwind CSS 4 in admin customizations
The admin and its extensions now compile with Tailwind CSS 4. The admin bundler generates its own CSS and ignores the project's Tailwind configuration:
- Admin extensions must use **Tailwind CSS 4 class names**, for example `outline-hidden` instead of `outline-none` and `rounded-sm` instead of `rounded`. A Tailwind 3 class name does not error — it renders with different styling or none. This is silent, and only a visual check catches it.
- The official `npx @tailwindcss/upgrade` tool renames classes. It rewrites files in place, so run it only after approval and scope its result to `src/admin/` — revert anything it touches outside the admin customizations (for example a storefront that is still on Tailwind 3).
- The admin build no longer loads a `postcss.config.*` file from the project. To add PostCSS plugins to the admin, use the `admin.vite` configuration.
- A project or plugin `tailwind.config.*` is not read by the admin build. Plugins with admin customizations should remove their unused `tailwind.config.ts`. Do **not** delete a Tailwind/PostCSS config that another app in the workspace (a storefront) still uses.
## 6. Vite 8 for admin builds
The admin now builds with Vite 8 (Rolldown and Oxc replace Rollup and esbuild). If the project customizes the admin's Vite config through `admin.vite` in `medusa-config.ts`:
- Rename `build.rollupOptions` to `build.rolldownOptions`, `esbuild` to `oxc`, and `optimizeDeps.esbuildOptions` to `optimizeDeps.rolldownOptions`. The old names still work but are deprecated.
- Remove `build.rollupOptions.output.interop`. It has no replacement.
- `build.minify: "esbuild"` and `build.cssMinify: "esbuild"` now require `esbuild` as a dev dependency.
- Vite plugins added through `admin.vite` must support Vite 8 — check each plugin's peer range.
- `admin.vite` is now typed as `(config: InlineConfig) => InlineConfig` against Vite's `InlineConfig`, so unknown keys or wrong value types fail the typecheck. Projects using `node10` module resolution without `skipLibCheck` must switch to `node16` or `bundler`, or enable `skipLibCheck`.
- An admin extension that imports the **default export of a CommonJS package** may now get a different value. Import the named export instead.
- The admin's default build target is now `baseline-widely-available` (Chrome / Edge 111, Firefox 114, Safari 16.4). Set `build.target` in `admin.vite` only if the user states they must support older browsers.
- **Plugin authors must rebuild** every plugin with admin customizations with this release (`npx medusa plugin:build`) so its admin bundle works in the browser.
## 7. TanStack Table v9 in `DataTable` and `DataGrid`
Only affects admin customizations that use `DataTable` from `@medusajs/ui` with custom row types or select columns, or the dashboard's `DataGrid`. Columns built with `createDataTableColumnHelper` or `createDataGridHelper` need no change.
- `DataTable` row types must be objects or arrays. Generic wrappers use `<TData extends DataTableRowData>`, with `DataTableRowData` imported from `@medusajs/ui`. Wrap primitive rows (`string[]`) in objects.
- Columns typed with `@tanstack/react-table` v8 helpers (`createColumnHelper`, `ColumnDef`, `CellContext`) no longer type-check with `DataTable`. Use `createDataTableColumnHelper` and `DataTableCellContext` from `@medusajs/ui`.
- `getIsSomePageRowsSelected()` now also returns `true` when all rows are selected — an indeterminate header checkbox must check `!table.getIsAllPageRowsSelected() && table.getIsSomePageRowsSelected()`.
- `row.getToggleSelectedHandler()` passed to `Checkbox`'s `onCheckedChange` now throws on click. Use `(checked) => row.toggleSelected(!!checked)`.
- `DataGrid` column pinning values are `"start"` / `"end"` instead of `"left"` / `"right"`.
- `@tanstack/react-table` is ESM-only, so Jest suites that import `DataTable` may need `@tanstack` added to their `transformIgnorePatterns` exceptions.
```tsx title="src/admin/components/brand-table.tsx"
import { Checkbox, DataTableRowData, createDataTableColumnHelper } from "@medusajs/ui"
const columnHelper = createDataTableColumnHelper<Brand>()
const selectColumn = columnHelper.select({
header: ({ table }) => (
<Checkbox
checked={
!table.getIsAllPageRowsSelected() && table.getIsSomePageRowsSelected()
? "indeterminate"
: table.getIsAllPageRowsSelected()
}
onCheckedChange={(value) => table.toggleAllPageRowsSelected(!!value)}
/>
),
cell: ({ row }) => (
<Checkbox
checked={row.getIsSelected()}
onCheckedChange={(checked) => row.toggleSelected(!!checked)}
/>
),
})
const BrandTable = <TData extends DataTableRowData>({ data }: { data: TData[] }) => {
// ...
}
```
## 8. Admin mutation callbacks and i18next
Only affects admin customizations that pass callbacks to the admin's mutation hooks, or that use `i18next` directly.
- Mutation callbacks (`onSuccess`, `onError`, `onSettled`) in the admin hooks now receive all four TanStack Query arguments `(data, variables, onMutateResult, context)`. Before, the third argument was `onMutateResult` where callers expected `context`. A callback that read the third argument as `context` was reading the wrong value; re-check every callback that uses more than two arguments.
- Admin extensions now run on `react-i18next` 18 / `i18next` 27. Calling `t()` on an `i18next` instance that was never initialized now returns `""` instead of `undefined` — **silent**: a label just renders empty. Use the admin's own instance through `getI18n()` from `react-i18next` (or the `useTranslation` hook inside components).
- Translations with an empty value now fall back to English.
## 9. Redis session store now uses node-redis — ioredis options are silently ignored
Only affects projects that set `projectConfig.redisOptions` in `medusa-config.ts`. A project that only sets `redisUrl` needs no change. The options of Medusa's Redis **modules** (event bus, workflow engine, cache, caching, locking) are unchanged by this item.
The session store now uses `connect-redis` v11 with a `redis` (node-redis) client, and `redisOptions` is typed as `Omit<RedisClientOptions, "url">` from `redis`. **Options in the old ioredis shape are ignored without an error or warning** — TLS, timeouts, and the database index silently fall back to defaults. Translate every key:
| ioredis | node-redis |
| --- | --- |
| `connectionName` | `name` |
| `tls: { ... }` | `socket: { tls: true, ... }`, or a `rediss://` URL in `redisUrl` |
| `host`, `port`, `family`, `path` | `socket.host`, `socket.port`, `socket.family`, `socket.path` |
| `connectTimeout`, `noDelay`, `socketTimeout` | `socket.connectTimeout`, `socket.noDelay`, `socket.socketTimeout` |
| `keepAlive: <ms>` | `socket.keepAlive: true`, `socket.keepAliveInitialDelay: <ms>` |
| `retryStrategy(times)` | `socket.reconnectStrategy(retries, cause)` (`retries` starts at `0`) |
| `db` | `database` |
| `readOnly` | `readonly` |
| `enableOfflineQueue: false` | `disableOfflineQueue: true` |
| `commandTimeout` | `commandOptions.timeout` |
```ts title="medusa-config.ts"
module.exports = defineConfig({
projectConfig: {
redisUrl: process.env.REDIS_URL,
redisOptions: {
name: "medusa",
socket: {
tls: true,
},
},
},
})
```
- Options with no node-redis equivalent are no longer supported: `maxRetriesPerRequest`, `reconnectOnError`, `enableReadyCheck`, `lazyConnect`, and Redis Sentinel options. Remove them and list them under manual follow-ups so the user can decide whether the behavior they provided still matters.
- `url` can't be set in `redisOptions` (a type error; at runtime `redisUrl` overrides it). The connection URL always comes from `redisUrl`.
- Session commands now time out after 60 seconds by default. Override with `redisOptions.commandOptions.timeout`.
- Code that types `redisOptions` with `RedisOptions` from `ioredis` must use `RedisClientOptions` from `redis`.
- Jest suites that boot the app with `redisUrl` and run without `NODE_OPTIONS=--experimental-vm-modules` must use the `@medusajs/test-utils` Jest preset (`preset: "@medusajs/test-utils"`). A project-level `resolver` or `transformIgnorePatterns` replaces the preset's rather than merging with it.
- Existing sessions stay valid after the upgrade.
## 10. BullMQ 6 and ioredis 6 in the Redis modules — deploy all instances together, no downgrade
Affects projects using the Redis Event Bus or Redis Workflow Engine modules; the other Redis modules only get the ioredis 6 changes.
- **Deploy all instances together.** Scheduled workflows move to BullMQ Job Schedulers, and existing scheduled jobs are migrated automatically on startup. Instances still on the previous version can't read the schedules or job IDs the new version writes.
- **You can't downgrade** after the new version starts, because scheduled workflows are then stored in a format BullMQ 5 doesn't manage. Make sure the user has a tested rollback plan that does not involve downgrading against the same Redis.
- Custom event `jobId`s containing `:` are stored with `|` instead. Deduplication works as before; code that looks jobs up directly in BullMQ must use the `|` form.
- `EventPriority.LOWEST` is now `2097151`. A hard-coded priority of `2097152` (or higher) falls back to the default priority with the warnings `Invalid priority value: {priority} for event {eventName}. Must be between 1 and 2097151` and `Setting priority to default value: {default} for event {eventName}`. Use `EventPriority` constants rather than numbers.
- Custom `workerOptions`, `queueOptions`, and `jobOptions` use BullMQ 6 types. The `debounce` event option still works but is deprecated in favor of `deduplication` — note it as a follow-up, don't migrate it unless the typecheck forces it.
- ioredis 6 changes connection defaults for options not set in the modules' `redisOptions`: `protocol` defaults to `3` (RESP3), `keepAlive` to `30000` ms, and the default `retryStrategy` waits longer between reconnects. If the Redis provider does not support RESP3, set `protocol: 2` in the affected modules' `redisOptions`.
## 11. OpenTelemetry SDK 3 in `instrumentation.ts`
Only affects projects that configure instrumentation in `instrumentation.ts`. `registerOtel` from `@medusajs/medusa` keeps its signature.
- Import from `@medusajs/framework/opentelemetry/sdk-trace` instead of `@medusajs/framework/opentelemetry/sdk-trace-node`. The old subpath is gone from the package's `exports`, so the old import fails to resolve.
- `NodeTracerProvider` no longer exists. Use `TracerProvider` and register it with `trace.setGlobalTracerProvider()`.
- `SimpleSpanProcessor` and `BatchSpanProcessor` take `{ exporter, ...options }` instead of the exporter as the first argument.
- Exporters passed to `registerOtel` must target SDK 3.0 — for example the `0.300+` versions of `@opentelemetry/exporter-zipkin` and `@opentelemetry/exporter-trace-otlp-*`. Resolve each exporter's SDK-3 version from the registry.
- Traces now include the `os.*` and `service.instance.id` resource attributes by default.
- Some Medusa docs pages (the instrumentation note and the codemods page) may still mention `sdk-trace-node`; trust this prompt and the installed package's `exports` over them.
## 12. Loyalty Plugin store routes no longer return gift card references
Only affects projects using `@medusajs/loyalty-plugin` whose storefront requests these fields. The plugin's Store routes (carts, orders, `/store/gift-cards/:code`, and the cart gift-card / store-credit routes) no longer allow a gift card's `reference`, `reference_id`, or `*gift_cards`. They are **silently stripped**: the request returns `200` without them. `reference_id` holds the ID of the order the gift card was bought in, which could expose that order's customer. Remove these fields from the storefront's `fields` parameters. **Never re-expose them with `allowFields`** — the removal is a security fix.
## 13. Behavior changes that require verification rather than edits
- **RBAC (projects with the RBAC Module, including Medusa Cloud projects whose license covers RBAC).** Admin operations that used to require the super-admin wildcard `*:*` now have their own policies, created on startup: `search_index:read` / `search_index:delete`, `search_index_sync:create`, `index_engine:update`, `workflow_execution:create`, and `view_configuration` / `layout_configuration` actions. Listing search indexes now requires `search_index:read`. Roles with operation wildcards (`*:create`, `*:update`, `*:delete`) now match the new policies — `*:create` can reindex search indexes, run workflows, and create system default views — and roles with `workflow_execution:create` or `workflow_execution:*` can now run any registered workflow. Do not change roles; list this for the user to review.
- **Shipping methods**: adding a shipping method now saves its `metadata` and `description`. Custom code that worked around the drop should be reviewed, not changed blindly.
## 14. Everything else in the release
Read the v2.23.0 GitHub release notes and the notes for every release between the project's current version and 2.23.0. Fold any additional breaking change, required migration, or config change into the plan and call it out explicitly. If the project is coming from below 2.21.0, the strict Store API `allowed` field list (with the global `allowFields` middleware as the only way to re-expose a field) applies; from below 2.20.0, the Store relations-depth limit (`storeRelationsLimit`) and the payment-provider/region validation also apply — handle them as part of this upgrade.
For anything not covered here, consult the official Medusa documentation at https://docs.medusajs.com, the GitHub release notes at https://github.com/medusajs/medusa/releases, or the Medusa MCP server (`ask_medusa_question`) before acting. Do not guess at APIs, config keys, or version numbers — verify them.
</context>
<inputs>
You are given access to the project's working directory. You must discover the following yourself; do not assume:
- **Project shape**: standalone Medusa project vs. monorepo (e.g. `apps/backend` + workspaces). Check for a root `package.json` with workspaces and an `apps/` directory.
- **Package manager**: detect from the lockfile (`yarn.lock`, `package-lock.json`, `pnpm-lock.yaml`, `bun.lockb`). Use it consistently; do not switch it.
- **Current Medusa version**: read from `package.json` dependencies / lockfile. If it cannot be determined, ask the user before proceeding.
- **Third-party dependencies from the table in `<context>`**: which of them each `package.json` lists, and any `resolutions` / `overrides` / `pnpm.overrides` entries that pin React, Vite, or Express.
- **Route matchers and handlers**: every `matcher` in `src/api/middlewares.ts` and in plugins, plus `req.params[0]`, `req.params["0"]`, `req.body`, `bodyParser: false`, and `additionalDataValidator` usages under `src/api/`.
- **Admin customizations**: `src/admin/` (widgets, routes, components, hooks), including `useRef`, `DataTable`, `DataGrid`, `createColumnHelper`, `ColumnDef`, `CellContext`, `getToggleSelectedHandler`, `columnPinning`, `"left"` / `"right"`, mutation-hook `onSuccess` / `onError` / `onSettled` callbacks, direct `i18next` imports, and Tailwind class names.
- **Tailwind / PostCSS files**: `tailwind.config.*` and `postcss.config.*`, and which app in the workspace actually uses each.
- **`admin.vite`** in `medusa-config.ts`, its keys, any Vite plugins it adds, and `moduleResolution` / `skipLibCheck` in `tsconfig.json`.
- **Redis configuration**: `projectConfig.redisOptions` and `redisUrl` in `medusa-config.ts`; the Redis Event Bus / Workflow Engine / other Redis modules and their `redisOptions`, `workerOptions`, `queueOptions`, `jobOptions`; any `RedisOptions` import from `ioredis`; event `jobId`s and numeric `priority` values; whether the project runs more than one backend instance (server + worker).
- **Instrumentation**: `instrumentation.ts` and its imports, especially `sdk-trace-node`, `NodeTracerProvider`, `SimpleSpanProcessor`, `BatchSpanProcessor`, and exporter packages.
- **Loyalty Plugin**: whether `@medusajs/loyalty-plugin` is installed, and storefront `fields` selections that include `reference`, `reference_id`, or `gift_cards`.
- **RBAC Module**: whether the RBAC Module is installed or the project runs on Medusa Cloud with RBAC.
- **Plugins**: local or workspace plugins with admin customizations that must be rebuilt.
- **Jest setup**: `jest.config.*`, its `preset`, `resolver`, and `transformIgnorePatterns`.
- **Storefront presence**: a separate storefront app/repo or directory. If no storefront is in this workspace, treat storefront steps as guidance to surface to the user, not edits you can make.
</inputs>
<steps>
Work through these in order. For each, record findings and the proposed change in the plan — do not edit yet. If the current version is already >= 2.23.0, report that and stop; do not downgrade or re-apply migrations.
1. **Detect project shape, package manager, current Medusa version, Node.js version, storefront presence, and installed plugins.** Read the relevant `package.json` files and record the current `@medusajs/medusa` version. If the working tree has uncommitted changes, say so before touching `package.json` or lockfiles.
2. **Confirm the breaking-change list from the release notes.** Read the v2.23.0 release notes and those of every release between the project's current version and 2.23.0. Incorporate anything this prompt does not cover, and call it out explicitly.
3. **Plan the package version bump.** Identify every `@medusajs/*` dependency and devDependency across the backend (and admin/plugin/storefront packages if present) and target their v2.23.0-aligned versions, resolving any non-`2.x` package (such as `@medusajs/ui`) from the npm registry rather than forcing `2.23.0`. Add the third-party bumps from the table in `<context>` for every dependency the project already lists, in the same install pass, using the detected package manager. Flag any `resolutions` / `overrides` that would hold React, Vite, or Express on the old major. **Keep the storefront's own React / Tailwind / Next.js versions out of this bump** — they are a separate decision; only list them under manual follow-ups.
4. **Audit Express 5 route matchers and handlers.**
- List every string `matcher`. Classify each: plain path (no change), bare `*` (converted automatically — no change required), or Express 4 syntax that now throws (`(`, `|`, `?`, `+`). For each throwing one, propose the Express 5 equivalent (`{/:id}` for an optional segment, `{*splat}` for a wildcard) or a `RegExp` matcher, and check it matches the same paths as before.
- Find every read of `req.params[0]` / `req.params["0"]` and propose the new key (`splat0` for a converted bare `*`, `splat` for a hand-written `{*splat}`), handling the array value.
- Find routes with `bodyParser: false` that read `req.body` and propose a guard for `undefined`.
- Find `bodyParser` / `additionalDataValidator` configs on a `/x/*` matcher and check whether the project relies on them for `/x` itself; if so, propose an extra entry.
5. **Audit admin customizations** (skip if there are none).
- React 19 typing: `useRef<T>()` without an argument and `useRef<T>(null)` consumers.
- Tailwind CSS 4 class names: plan to run `npx @tailwindcss/upgrade` after approval and scope its result to `src/admin/`, or list renames by hand if the tool can't be scoped. Identify `tailwind.config.*` / `postcss.config.*` that exist only for the admin (removable) versus ones a storefront uses (keep).
- `admin.vite`: renamed keys (`rollupOptions` → `rolldownOptions`, `esbuild` → `oxc`, `optimizeDeps.esbuildOptions` → `optimizeDeps.rolldownOptions`), `output.interop`, `"esbuild"` minifiers, Vite plugin peer ranges, and `moduleResolution` / `skipLibCheck`.
- CommonJS default imports in admin code that may change value under Vite 8.
- TanStack Table v9: every item in `<context>` section 7.
- Mutation callbacks that take three or more arguments, and direct `i18next` usage that should go through `getI18n()`.
6. **Audit Redis configuration.**
- Translate every key in `projectConfig.redisOptions` using the table in `<context>`; list unsupported keys separately. Replace any `RedisOptions` type from `ioredis` with `RedisClientOptions` from `redis`.
- For the Redis Event Bus / Workflow Engine modules: numeric `priority` values of `2097152` or higher, direct BullMQ lookups by `jobId` containing `:`, custom worker/queue/job options that may not type-check against BullMQ 6, and whether the Redis provider supports RESP3.
- If the project runs more than one backend instance, put "deploy every instance together; no downgrade after start" in the plan as a deploy-time requirement for the user.
- Jest suites that boot the app with `redisUrl`: check they use the `@medusajs/test-utils` preset or `--experimental-vm-modules`.
7. **Audit `instrumentation.ts`** (skip if absent): the `sdk-trace` import path, `NodeTracerProvider`, span-processor constructor arguments, and each exporter package's SDK-3-compatible version.
8. **Audit Loyalty Plugin storefront requests** (skip if not installed): find `fields` selections that include `reference`, `reference_id`, or `gift_cards`, and propose removing them. Check whether the storefront reads those properties and plan the UI change with the user if it does.
9. **Compile and present the plan, then stop.** Compile steps 1-8 into the plan described in `<output_format>`, including the RBAC and other behavior changes from `<context>` section 13 as review items. Wait for the user's explicit approval before editing any files.
10. **Bump versions and reinstall.** Apply the bumps from step 3 in every `package.json`, then reinstall with the detected package manager. Confirm the install resolves without peer-dependency errors, and **confirm there is exactly one copy of `react`, `react-dom`, and `vite`** in the backend's dependency tree (for example `npm ls react react-dom vite`, `yarn why react`, or `pnpm why react`). Two copies is a failure — fix it before continuing.
11. **Apply the approved config and code edits** — `medusa-config.ts` (`redisOptions`, `admin.vite`, module Redis options), route matchers and handlers, admin customizations, `instrumentation.ts`, Jest config, and storefront `fields` changes if the storefront is in the workspace.
12. **Run database migrations** using the project's Medusa CLI (`npx medusa db:migrate`), plus any migration the release notes require.
13. **Verify.**
- Backend build (`npx medusa build`) and TypeScript typecheck (`npx tsc --noEmit`).
- `npx medusa plugin:build` for each plugin in the workspace.
- Storefront build, if present.
- Lint, if configured.
- Test suites, if present — Jest suites that import `DataTable` or boot the app with `redisUrl` are the likely failures.
- Start the app (`npx medusa develop`) and confirm it boots without a `path-to-regexp` error and connects to Redis without `Redis session store error` / `Failed to connect to Redis session store` in the logs.
- Runtime smoke check: log in to the admin (proves the session store), open every custom admin widget and route and check they **render with the expected styling and labels** (Tailwind 4 class renames and uninitialized `t()` calls fail silently), call each custom API route whose matcher or handler changed and check the **response data**, and if the Loyalty Plugin is installed, load a cart with gift cards in the storefront.
Report all results. If the build, typecheck, or migrations fail, report the exact error output and your best-guess cause tied to a specific change, and stop for the user rather than making speculative further edits.
</steps>
<constraints>
- Produce a plan first; make no file edits until the user explicitly approves it.
- Edit only what a v2.23.0 upgrade requires. Do not refactor unrelated code, reformat files, or adopt optional v2.23 features (audit-log namespaces, impersonator, and metadata filtering; the `metadata` function in a route's audit setting; default registration of the Audit and RBAC modules on Medusa Cloud). Every change must trace to a v2.23.0 breaking change or the version bump; list anything else under manual follow-ups instead.
- Never widen a React range to `^18 || ^19` or add a `resolutions` / `overrides` entry that keeps React 18 or Vite 7 — it installs two copies and breaks admin extensions. Pin to the versions in the release notes.
- Do not add third-party dependencies the project does not already list. Upgrade only those it has.
- Do not upgrade the storefront's own framework, React, or Tailwind as part of this upgrade; surface it as a follow-up.
- Do not translate an ioredis option into a guessed node-redis key. If a key isn't in the mapping table and has no documented node-redis equivalent, remove it and list it for the user.
- Do not re-expose a gift card's `reference`, `reference_id`, or `*gift_cards` with `allowFields` or any other mechanism — the removal is a security fix.
- Do not change RBAC roles or policies. Surface the policy changes for the user to review.
- Never hardcode, print, or persist secrets, connection strings, or API keys. Reference environment variables by name only.
- Match the project's existing package manager; do not switch it.
- Match the project's existing code style (this is a TypeScript Medusa project: no semicolons, double quotes, 2-space indentation, parens on arrow functions). Never use emojis.
- Never edit files inside `node_modules`, and never patch the installed packages — this is an upgrade, not a patch.
- If the storefront is not in this workspace, do not fabricate edits to it — surface the storefront steps as instructions for the user to apply in their storefront repo.
- Verify every API, config key, version number, and SDK signature against https://docs.medusajs.com or the Medusa MCP server before relying on it. Do not guess.
- Do not `git commit`, `git push`, or otherwise publish changes. Leave the working tree modified for the user to review.
</constraints>
<error_handling>
- If the current version cannot be determined: report what you found and ask the user for their current Medusa version before proceeding.
- If a `@medusajs/*` package has no `2.23.0` release (off the `2.x` line): resolve its correct co-released version from the npm registry; if still ambiguous, list it as a must-confirm item instead of guessing.
- If the install reports peer-dependency conflicts on `react` / `react-dom` / `vite`: a project package (or a third-party admin plugin) still requires the old major. Identify it with the package manager's `why` command and report it; do not force-install or widen ranges.
- If the admin loads but widgets fail in the browser with an "Invalid hook call" error, or hooks return `null` unexpectedly: two copies of React are installed. Check the dependency tree and any `resolutions` / `overrides`.
- If the app throws at startup with `Unexpected {char} at index {n}: {path}; visit https://git.new/pathToRegexpError for info`: a string `matcher` uses Express 4 syntax. Rewrite it with Express 5 syntax or a `RegExp` per step 4.
- If a custom route that read a wildcard now gets `undefined`: it reads `req.params[0]`. Switch to `req.params.splat0` (or `splat`) and handle the array value.
- If a route's body-parser or `additionalDataValidator` config stopped applying to its base path: the `/x/*` matcher no longer covers `/x`. Add an entry for `/x`.
- If admin sessions don't persist, Redis TLS fails, or the logs show `Redis session store error: ...` / `Failed to connect to Redis session store: ...`: `redisOptions` still has ioredis-shaped keys. Re-check every key against the mapping table.
- If the logs show `Invalid priority value: {priority} for event {eventName}. Must be between 1 and 2097151`: a hard-coded event priority is out of range. Use an `EventPriority` constant.
- If importing `@medusajs/framework/opentelemetry/sdk-trace-node` fails with `Package subpath './opentelemetry/sdk-trace-node' is not defined by "exports"`: change the import to `@medusajs/framework/opentelemetry/sdk-trace`.
- If the admin build fails on an `admin.vite` type error: the config has a key or value type that Vite 8's `InlineConfig` does not accept. Fix the key; if the error is in Vite's own type declarations under `node10` module resolution, switch to `node16` / `bundler` or enable `skipLibCheck`.
- If a plugin's admin bundle fails in the browser after the upgrade: it was built against the previous release. Rebuild it with `npx medusa plugin:build`.
- If admin styling looks wrong after the upgrade: Tailwind 3 class names remain in admin customizations. Re-run the class-name audit; do not add a `tailwind.config` back — the admin build doesn't read it.
- If a Jest suite fails with an ESM syntax error from `@tanstack` or `connect-redis`: add `@tanstack` to the `transformIgnorePatterns` exceptions, or switch the suite to the `@medusajs/test-utils` preset.
- If the build, typecheck, plugin build, lint, or migrations fail after your edits: report the exact error output, your best-guess cause tied to a specific change, and stop for the user rather than making speculative further edits.
</error_handling>
<output_format>
Respond in Markdown with these sections, in order:
1. **Detected environment** — project shape, package manager, current version -> 2.23.0, Node.js version, storefront present (yes/no), installed plugins, and which affected subsystems are in use: custom route matchers, admin customizations (and whether they use Tailwind / `DataTable` / `DataGrid` / mutation callbacks / `i18next`), `admin.vite`, `projectConfig.redisOptions`, Redis modules and instance count, `instrumentation.ts`, Loyalty Plugin, RBAC Module.
2. **Migration plan (approval required)** — the intended version bumps (Medusa and third-party, as a table), each audit's findings with file:line and the proposed change, the migrations to run, deploy-time requirements (all Redis-module instances together, no downgrade), and decisions for the user. End with an explicit request for approval; do not proceed past this section until approved.
3. **Changes applied** — bulleted, grouped as: Version bumps / Express route matchers and handlers / Admin customizations / Redis configuration / Instrumentation / Loyalty Plugin storefront fields / Other breaking changes. Each item: file path + a one-line description. State "none required" for any empty group.
4. **Verification** — the command run, and PASS/FAIL with relevant output for: dependency install, single copy of React / React DOM / Vite, database migrations, backend build, TypeScript typecheck, plugin builds, storefront build (if present), lint, tests, app startup, and the runtime smoke check with rendered admin UI and response data confirmed.
5. **Manual follow-ups** — anything the user must review or decide: RBAC role review, removed Redis options with no equivalent, deploy coordination for Redis modules, storefront upgrades outside this workspace, deprecated `debounce` options, and other breaking changes surfaced from the release notes. "None" if empty.
</output_format>
<success_criteria>
- Every `@medusajs/*` dependency resolves to its v2.23.0-aligned version, verified against the registry, and every third-party dependency the project lists from the release-notes table is at its new version in the same install.
- The installed tree has exactly one copy each of `react`, `react-dom`, and `vite`, and no range was widened to keep an old major.
- Every string route matcher starts under Express 5, every `req.params[0]` read was migrated, and body-parser / `additionalDataValidator` configs still cover the paths they did before.
- Admin customizations type-check under React 19 and TanStack Table v9, use Tailwind CSS 4 class names, and `admin.vite` uses the Vite 8 option names.
- `projectConfig.redisOptions` contains only node-redis options, and admin login works against the session store.
- `instrumentation.ts`, if present, imports from `@medusajs/framework/opentelemetry/sdk-trace` and uses SDK-3-compatible exporters.
- No storefront request asks the Loyalty Plugin for `reference`, `reference_id`, or `*gift_cards`, and none were re-exposed.
- Database migrations run to completion; backend build, TypeScript typecheck, lint, and every plugin build pass; the storefront build passes if a storefront is present.
- No secrets appear in edits or output; no files under `node_modules` were modified; no unrelated files were changed; no RBAC roles were changed; no commits or pushes were made.
- No file is edited before user approval, and the response contains all five required sections.
</success_criteria>
This release updates several major dependencies across the server and the Medusa Admin, so it includes breaking changes. Read the Highlights below before upgrading, especially if you have custom API routes, middlewares, admin customizations, plugins, or custom Redis configurations.
Highlights
Update Your Project's Dependencies
🚧 Breaking change
This release updates the major versions of several dependencies that Medusa applications install alongside Medusa's packages. Update the following dependencies in your Medusa application's package.json, if they're installed:
| Dependency | Previous version | New version |
|---|---|---|
@medusajs/* packages
| 2.22.7
| 2.23.0
|
@medusajs/ui
| 4.2.9
| 4.3.0
|
react, react-dom
| ^18.3.1
| ^19.3.1
|
@types/react, @types/react-dom
| ^18.x
| ^19.3.0
|
vite
| ^7.3.7
| ^8.3.8
|
@tanstack/react-query
| 5.64.2
| 5.107.1
|
react-i18next
| 13.5.0
| 18.0.1
|
react-router-dom
| 7.18.2
| 7.18.5
|
zod
| 4.2.0
| 4.6.7
|
express
| ^4.21.0
| ^5.3.0
|
@types/express
| ^4.17.21
| ^5.0.6
|
i18next
| 23.x
| 27.1.1
|
@tanstack/react-table
| 8.x
| 9.3.1
|
tailwindcss
| 3.x
| ^4.3.5
|
@opentelemetry/sdk-node
| 0.220.x
| ^0.301.2
|
@opentelemetry/resources
| 2.x
| ^3.0.0
|
@opentelemetry/instrumentation-pg
| 0.73.x
| ^0.78.0
|
@opentelemetry/api
| 1.9.x
| ^1.10.0
|
@opentelemetry/sdk-trace-node
| 2.x
| Replaced by @opentelemetry/sdk-trace ^3.0.0
|
For example, in a project created from the default starter:
npm install @medusajs/admin-sdk@2.23.0 @medusajs/admin-shared@2.23.0 @medusajs/caching@2.23.0 @medusajs/cli@2.23.0 @medusajs/dashboard@2.23.0 @medusajs/draft-order@2.23.0 @medusajs/framework@2.23.0 @medusajs/medusa@2.23.0 @medusajs/ui@4.3.0 @tanstack/react-query@5.107.1 react-i18next@18.0.1 react-router-dom@7.18.5 zod@4.6.7
npm install -D @medusajs/test-utils@2.23.0 react@^19.3.1 react-dom@^19.3.1 @types/react@^19.3.0 @types/react-dom@^19.3.0 vite@^8.3.8The next sections cover the breaking changes related to each of these dependencies, if any.
Express 5
🚧 Breaking change
Medusa now runs on Express 5 (^5.3.0), which is also the express peer range of @medusajs/utils. Express 5 moves route matching to path-to-regexp 8.
After updating express and @types/express, check your custom API routes and middlewares:
- Bare
*wildcards in middleware matchers keep working. Medusa converts them to Express 5 syntax and matches the same paths as before. The Express 5 syntax is{*splat}, for example/admin/products/{*splat}. - Other Express 4 string matcher syntax now throws at startup: regex groups (
/admin/(products|collections)), optional params (/:id?), and+. Use aRegExpmatcher or Express 5 syntax ({/:id}) instead. - Wildcard captures are now in
req.params.splat(orsplat0,splat1, and so on for a converted bare*) as an array, not inreq.params[0]. - Routes that read
req.bodywithout a body parser running now getundefined. bodyParserandadditionalDataValidatorconfigs on a/x/*matcher no longer apply to/xor/x-other.
// Before
matcher: "/custom/:id?"
// After
matcher: "/custom{/:id}"Learn more in the Middlewares documentation.
React 19 in the Medusa Admin
🚧 Breaking change
The Medusa Admin, @medusajs/ui, and the official plugins now use React 19. @medusajs/medusa, @medusajs/ui, @medusajs/draft-order, and @medusajs/loyalty-plugin require react and react-dom ^19.3.1 as peer dependencies. A widened range isn't supported, because it installs two copies of React and breaks admin extensions.
If your admin customizations use TypeScript, you may need these type fixes:
useRef<T>()now requires an argument, for exampleuseRef<T>(undefined).useRef<T>(null)returnsRefObject<T | null>.
Tailwind CSS 4 in the Medusa Admin
🚧 Breaking change
This affects projects and plugins with admin customizations that use Tailwind CSS classes.
The Medusa Admin and admin extensions now compile with Tailwind CSS 4. Admin extensions must use Tailwind CSS 4 class names, for example outline-hidden instead of outline-none and rounded-sm instead of rounded. You can use the official upgrade tool to rename classes in your admin customizations:
npx @tailwindcss/upgradeThe admin build no longer loads a postcss.config.* file from your project, so a leftover Tailwind CSS 3 tailwindcss: {} PostCSS entry no longer breaks the build. To add PostCSS plugins, use the admin.vite configuration. Plugins with admin customizations should remove their unused tailwind.config.ts files.
Vite 8 for Admin Builds
🚧 Breaking change
The Medusa Admin now builds with Vite 8, which replaces Rollup and esbuild with Rolldown and Oxc. If your project lists vite in its package.json, as the official starters do, update it to avoid installing two copies of Vite.
If you customize the admin's Vite configuration with admin.vite:
- Rename
build.rollupOptionstobuild.rolldownOptions,esbuildtooxc, andoptimizeDeps.esbuildOptionstooptimizeDeps.rolldownOptions. The old names still work but are deprecated. - Remove
build.rollupOptions.output.interop. It has no replacement. build.minify: "esbuild"andbuild.cssMinify: "esbuild"now requireesbuildas a dev dependency.- Vite plugins added through
admin.vitemust support Vite 8. admin.viteis now type-checked against Vite'sInlineConfig, so unknown keys or wrong value types fail type checking. Projects usingnode10module resolution withoutskipLibCheckmust switch tonode16orbundler, or enableskipLibCheck.
Plugin authors must rebuild their plugin with this release so that its admin bundle works in the browser:
npx medusa plugin:buildOther changes to be aware of:
- An admin extension that imports the default export of a CommonJS package may now get a different value. Import the named export instead.
- The admin's supported browsers move up to Chrome and Edge 111, Firefox 114, and Safari 16.4. To support older browsers, set
build.targetinadmin.vite.
TanStack Table v9 in the Medusa Admin
🚧 Breaking change
This only affects admin customizations that use
DataTablefrom@medusajs/uiwith custom types or select columns, or that use the dashboard'sDataGridand configurable table components. Columns built withcreateDataTableColumnHelperorcreateDataGridHelperneed no change.
@medusajs/ui and @medusajs/dashboard now use @tanstack/react-table v9. If you use these components in your admin customizations:
DataTablerow types must now be objects or arrays. Generic wrappers must use<TData extends DataTableRowData>, whereDataTableRowDatais exported from@medusajs/ui. Wrap primitive rows, such asstring[], in objects.- Columns built with
@tanstack/react-tablev8 types (createColumnHelper,ColumnDef,CellContext) no longer type-check withDataTable. UsecreateDataTableColumnHelperandDataTableCellContextinstead. getIsSomePageRowsSelected()now also returnstruewhen all rows are selected.row.getToggleSelectedHandler()passed toCheckbox'sonCheckedChangenow throws on click. Use(checked) => row.toggleSelected(!!checked)instead.- The dashboard's
DataGridcolumn pinning values are now"start"and"end"instead of"left"and"right". @tanstack/react-tableis ESM-only, so Jest suites that importDataTablemay need@tanstackadded to theirtransformIgnorePatternsexceptions.
import { DataTableRowData } from "@medusajs/ui"
const MyTable = <TData extends DataTableRowData>({
data,
columns,
}: MyTableProps<TData>) => {
// ...
}
const selectColumn = columnHelper.select({
header: ({ table }) => (
<Checkbox
checked={
!table.getIsAllPageRowsSelected() && table.getIsSomePageRowsSelected()
? "indeterminate"
: table.getIsAllPageRowsSelected()
}
onCheckedChange={(value) => table.toggleAllPageRowsSelected(!!value)}
/>
),
})Admin Dependency Updates: i18next, React i18next, TanStack Query, and Radix UI
🚧 Breaking change
This only affects admin customizations that use the admin's mutation hooks with callbacks, or that use
i18nextdirectly.
The admin's pinned dependencies are updated, including major versions of i18next (27.1.1), react-i18next (18.0.1), and i18next-browser-languagedetector (8.3.0), along with @tanstack/react-query (5.107.1), radix-ui (1.8.1), react-hook-form (7.92.0), and zod (4.6.7).
- Mutation callbacks (
onSuccess,onError,onSettled) in the admin hooks now receive all four arguments(data, variables, onMutateResult, context). Previously, the third argument wasonMutateResultwhere callers expectedcontext. - Admin extensions now run on
react-i18next18. Callingt()from ani18nextinstance that was never initialized now returns""instead ofundefined. Use the admin's instance throughgetI18n()fromreact-i18nextinstead. - Translations with an empty value now fall back to English.
Redis Session Store Uses node-redis
🚧 Breaking change
This only affects projects that set
projectConfig.redisOptionsinmedusa-config.ts. If you only setredisUrl, no action is required. The options of Medusa's Redis modules are unchanged.
The Redis session store now uses connect-redis v11 with a redis (node-redis) client instead of ioredis. projectConfig.redisOptions now accepts node-redis client options. Options in the old ioredis shape are ignored without an error, so update them:
| ioredis | node-redis |
|---|---|
connectionName
| name
|
tls: { ... }
| socket: { tls: true, ... }, or a rediss:// URL in redisUrl
|
host, port, family, path
| socket.host, socket.port, socket.family, socket.path
|
connectTimeout, noDelay, socketTimeout
| socket.connectTimeout, socket.noDelay, socket.socketTimeout
|
keepAlive: <ms>
| socket.keepAlive: true, socket.keepAliveInitialDelay: <ms>
|
retryStrategy(times)
| socket.reconnectStrategy(retries, cause) (retries starts at 0)
|
db
| database
|
readOnly
| readonly
|
enableOfflineQueue: false
| disableOfflineQueue: true
|
commandTimeout
| commandOptions.timeout
|
module.exports = defineConfig({
projectConfig: {
redisUrl: process.env.REDIS_URL,
redisOptions: {
name: "medusa",
socket: {
tls: true,
},
},
},
})Other changes:
- Options without a node-redis equivalent are no longer supported, such as
maxRetriesPerRequest,reconnectOnError,enableReadyCheck,lazyConnect, and Redis Sentinel options. urlcan't be set inredisOptions. The connection URL always comes fromredisUrl.- Session commands now time out after 60 seconds by default. Override it with
redisOptions.commandOptions.timeout. - Code that types
redisOptionswithRedisOptionsfromioredismust useRedisClientOptionsfromredis. - Jest suites that boot the app with
redisUrland run withoutNODE_OPTIONS=--experimental-vm-modulesmust use the@medusajs/test-utilsJest preset.
Existing sessions stay valid after the upgrade.
Learn more in the Medusa Configurations documentation.
BullMQ 6 and ioredis 6 in Redis Modules
🚧 Breaking change
This affects projects that use the Redis Event Bus or Redis Workflow Engine modules. The other Redis modules only get the ioredis 6 changes.
The Redis Event Bus and Redis Workflow Engine modules now use BullMQ 6, and all Redis modules use ioredis 6. Scheduled workflows move to BullMQ Job Schedulers, and existing scheduled jobs are migrated automatically on startup.
- Deploy all instances together. Instances on the previous version can't read schedules or job IDs written by the new version.
- You can't downgrade after the new version starts, because scheduled workflows are stored in a format that BullMQ 5 doesn't manage.
- Custom event
jobIds that contain:are stored with|instead. Deduplication works as before, but lookups directly in BullMQ must use the|form. EventPriority.LOWESTis now2,097,151. Hard-coded priorities of2097152fall back to the default priority with a warning.- Custom
workerOptions,queueOptions, andjobOptionsuse BullMQ 6 types. Thedebounceevent option still works but is deprecated in favor ofdeduplication. - ioredis 6 changes connection defaults for options you don't set in
redisOptions:protocoldefaults to3(RESP3),keepAlivedefaults to30000ms, and the defaultretryStrategywaits longer between reconnects. Setprotocol: 2to keep the previous wire protocol.
Learn more in the Redis Event Bus Module and Redis Workflow Engine Module documentation.
OpenTelemetry SDK 3
🚧 Breaking change
This only affects projects that configure instrumentation in
instrumentation.ts.
Medusa now uses OpenTelemetry SDK 3.0. If you configure instrumentation:
- Import from
@medusajs/framework/opentelemetry/sdk-traceinstead of@medusajs/framework/opentelemetry/sdk-trace-node. NodeTracerProviderno longer exists. UseTracerProviderand register it withtrace.setGlobalTracerProvider().SimpleSpanProcessorandBatchSpanProcessortake{ exporter, ...options }instead of the exporter as the first argument.- Exporters passed to
registerOtelmust target SDK 3.0, for example the 0.300+ versions of@opentelemetry/exporter-zipkinand@opentelemetry/exporter-trace-otlp-*. - Traces now include the
os.*andservice.instance.idresource attributes by default.
Learn more in the Instrumentation documentation.
Loyalty Plugin Hides Gift Card References in Store Routes
🚧 Breaking change
This only affects projects using the Loyalty Plugin whose storefront requests these fields.
The Loyalty Plugin's store routes no longer allow retrieving a gift card's reference, reference_id, or *gift_cards. The reference_id holds the ID of the order the gift card was purchased in, which could expose the order's customer information. Remove these fields from the fields query parameter in your storefront requests.
Dedicated RBAC Policies for Admin-Wide Operations
Behavior change
Affects projects with the RBAC Module installed, including Medusa Cloud projects whose license covers RBAC.
Admin operations that required the super admin wildcard (*:*) now each have their own RBAC policy, so they can be granted to roles individually. The RBAC Module creates the new policies on startup, and super admins keep every action.
- Listing search indexes now requires
search_index:read. Roles without it can no longer list them. - Roles with operation wildcards (
*:create,*:update,*:delete) now match the new policies. For example,*:createcan reindex search indexes, run workflows, and create system default views. - Roles with
workflow_execution:createorworkflow_execution:*can now run any registered workflow.
Review your roles' policies after upgrading.
Auth Routes Restore the Original req.auth_context Behavior
Behavior change
Affects projects on v2.22.7 with customizations that read
req.auth_contextin the/authroutes.
Before v2.22.7, req.auth_context in the /auth routes was set based on the session or JWT token sent with the request. v2.22.7 changed this without mentioning it in its release notes, so on a successful login, req.auth_context was set based on the user that logged in through the route instead. This release reverts that change, so req.auth_context is again based only on the session or token sent with the request.
Tax Recalculation Rejected on Completed Carts
Behavior change
Affects stores that attempt to recalculate taxes on completed carts.
Medusa now rejects tax recalculation requests on completed carts. Previously, the recalculation ran without error; now an error is returned. The cart's payment collection is also refreshed when taxes are recalculated on active carts.
Inactive Promotions Reject Usage Registration
Behavior change
Affects stores whose checkout or order flows register usage for promotions that are no longer active.
Medusa now rejects usage registration for promotions that are no longer active. Previously, registering usage succeeded even for inactive promotions; now it returns an error.
Cart Line Item Tax-Inclusive Flag Updated with Unit Price
Behavior change
Affects stores with tax-inclusive pricing that update a cart line item's unit price.
When a cart line item's unit price is updated, its is_tax_inclusive flag is now updated at the same time. Previously, the two were updated independently, which could cause incorrect tax calculations when the unit price changed.
Features
- feat(dashboard): audit log pages by @sradevski in #17919
- feat(framework): audit namespaces and impersonator in audit logs by @sradevski in #17884
- feat(audit): filter audit logs by metadata values by @sradevski in #17873
- feat(framework): add a metadata function to a route's audit setting by @sradevski in #17854
- feat(utils,types,audit,rbac): register the Audit and RBAC modules by default on Medusa Cloud by @sradevski in #17823
Bugs
- fix(utils): pass redisUrl to the Redis Workflow Engine in defineConfig by @shahednasser in #17931
- fix(core-flows): keep linked promotions when cancelling a draft order edit by @medusa-os-bot in #17926
- fix(draft-order): delete removed metadata keys from draft orders by @medusa-os-bot in #17921
- fix(workflows-sdk): revert the parent when a runAsStep workflow fails by @medusa-os-bot in #17918
- fix(caching-redis): never shorten a tag set's expiry by @NicolasGorga in #17909
- fix(caching-redis): prune expired members from tag sets during clear by @NicolasGorga in #17908
- fix(caching): stop registering the invalidation handler as an event bus interceptor by @NicolasGorga in #17910
- fix(core-flows,medusa): refresh the cart's payment collection when recalculating taxes, and reject tax recalculation on completed carts by @NicolasGorga in #17901
- fix(medusa,core-flows,types): scope admin feed notifications to the requesting user by @shahednasser in #17869
- fix(medusa): only list entities with active translation settings in GET /admin/translations/entities by @shahednasser in #17875
- fix(core-flows): update a cart line item's is_tax_inclusive together with its unit price by @shahednasser in #17867
- fix(auth,modules-sdk): verify MFA challenges under a lock by @shahednasser in #17853
- fix(query): clone the expand once in getAllFieldsAndRelations by @shahednasser in #17862
- fix(core-flows): keep cart shipping country when address is updated without one by @shahednasser in #17798
- fix(promotion): reject usage registration for promotions that are no longer active by @shahednasser in #17838
- fix(loyalty-plugin): disallow reference retrieval +
*gift_cardson store routes by @shahednasser in #17813 - fix(framework,medusa): keep the session and admin middlewares after a backend HMR reload by @shahednasser in #17902
- fix(core-flows): save metadata and description when adding a shipping method by @medusa-os-bot in #17900
- fix(dashboard): translate boolean cells and property label editor strings by @medusa-os-bot in #17896
- fix(dashboard): keep search focus on inventory, reservation and location lists by @medusa-os-bot in #17888
- fix(product): unlink an option from a product when the pair has value ids by @medusa-os-bot in #17879
- fix(medusa,types,dashboard): guard admin-wide operations with dedicated RBAC policies by @shahednasser in #17872
- fix: Read audit data from the token directly by @sradevski in #17876
- fix(dashboard): keep list page and filters on back with view configurations by @medusa-os-bot in #17859
- fix(caching-redis): clear tagged entries in bounded batches by @medusa-os-bot in #17851
- fix(eslint-plugin): lint nested job and subscriber files like Medusa loads them by @medusa-os-bot in #17843
- fix(ui): give the toast dismiss button an accessible name by @medusa-os-bot in #17819
- fix(ui): forward onDismiss and onAutoClose from toast utilities by @medusa-os-bot in #17818
Documentation
- docs: rename ChatGPT app to ChatGPT plugin by @shahednasser in #17915
- docs: document organization license settings and payments redesign changelog [automated] by @medusa-os-bot in #17907
- docs: document live Medusa ChatGPT app and MCP static mode by @shahednasser in #17914
- docs: reduce pricing page font sizes and document Medusa Security on custom domains by @shahednasser in #17837
- docs: fix vale error by @shahednasser in #17861
- docs: add TypeScript 6 and 7 configuration chapter by @shahednasser in #17858
- docs: fix caching delete invalidation tags and document Redis tag TTL by @medusa-os-bot in #17856
- docs: document environment type and specs badges and Production renaming [automated] by @medusa-os-bot in #17839
- docs: warn against enabling public auth providers for admin users by @shahednasser in #17836
- docs(cloud): add guide on migrating from self-hosting to Cloud by @shahednasser in #17824
- docs: Revise sign-up guide for Cloud trial and billing by @shahednasser in #17825
- docs: doc changes for next release [automated] by @medusa-os-bot in #17733
Chores
- chore(utils): fix flaky cross-module query ordering assertion by @shahednasser in #17928
- chore(workflow-engine-redis,event-bus-redis,utils,cache-redis,caching-redis,locking-redis): update bullmq to 6.7.6 and ioredis to 6.0.0 by @shahednasser in #17580
- chore(deps): update @tanstack/react-table to v9 by @shahednasser in #17672
- chore(admin-bundler,admin-vite-plugin,types): update vite to v8 by @shahednasser in #17671
- chore: update the admin to Tailwind CSS 4 by @shahednasser in #17632
- chore: update react to v19.3.1 by @shahednasser in #17628
- chore(medusa,framework,utils,test-utils,admin-bundler,cli,loyalty-plugin): update express to v5 by @shahednasser in #17614
- chore(deps,framework,medusa): update OpenTelemetry to SDK 3 by @shahednasser in #17596
- chore(framework,types,utils): update connect-redis to v11 by @shahednasser in #17588
- chore: major dependency updates (includes breaking changes) by @shahednasser in #17568
- chore: improve release notes drafting and notify medusa-mcp by @shahednasser in #17883
- chore(docs): update next to 16.4.6 by @shahednasser in #17871
- chore(deps): update minor dependencies by @medusa-os-bot in #17849
- chore(deps): update patch dependencies by @medusa-os-bot in #17848
- chore(docs): automated cloud documentation update by @medusa-os-bot in #17814
- chore: add ignore tags for audit code by @shahednasser in #17831
- chore(docs): Updated API Reference (automated) by @medusa-os-bot in #17830
- chore(docs): Generated References (automated) by @medusa-os-bot in #17829
- chore(docs): Generated + Updated UI Reference (automated) by @medusa-os-bot in #17828
- chore(docs): Update version in documentation (automated) by @medusa-os-bot in #17826
- chore(docs): Generated DML JSON files (automated) by @medusa-os-bot in #17827
Other Changes
- fix(draft-order): translate the draft orders menu label and list page by @medusa-os-bot in #17930
- chore(dashboard): add missing translations by @medusa-os-bot in #17927
- chore(dashboard): add missing translations by @medusa-os-bot in #17913
- chore(dashboard): add missing translations by @medusa-os-bot in #17889
- chore(dashboard): add missing translations by @medusa-os-bot in #17841
Full Changelog: v2.22.7...v2.23.0