npm @medusajs/medusa 2.23.0
v2.23.0: Express 5, React 19, Vite 8, Tailwind CSS 4

one hour ago

Medusa MCP users can update their project using the following prompt:

Update my Medusa project to v2.23.0

You 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.8

The 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 a RegExp matcher or Express 5 syntax ({/:id}) instead.
  • Wildcard captures are now in req.params.splat (or splat0, splat1, and so on for a converted bare *) as an array, not in req.params[0].
  • Routes that read req.body without a body parser running now get undefined.
  • bodyParser and additionalDataValidator configs on a /x/* matcher no longer apply to /x or /x-other.
// Before
matcher: "/custom/:id?"

// After
matcher: "/custom{/:id}"

Learn more in the Middlewares documentation.

#17614


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 example useRef<T>(undefined).
  • useRef<T>(null) returns RefObject<T | null>.

#17628


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/upgrade

The 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.

#17632


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.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.
  • admin.vite is now type-checked against Vite's InlineConfig, so unknown keys or wrong value types fail type checking. Projects using node10 module resolution without skipLibCheck must switch to node16 or bundler, or enable skipLibCheck.

Plugin authors must rebuild their plugin with this release so that its admin bundle works in the browser:

npx medusa plugin:build

Other 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.target in admin.vite.

#17671


TanStack Table v9 in the Medusa Admin

🚧 Breaking change

This only affects admin customizations that use DataTable from @medusajs/ui with custom types or select columns, or that use the dashboard's DataGrid and configurable table components. Columns built with createDataTableColumnHelper or createDataGridHelper need no change.

@medusajs/ui and @medusajs/dashboard now use @tanstack/react-table v9. If you use these components in your admin customizations:

  • DataTable row types must now be objects or arrays. Generic wrappers must use <TData extends DataTableRowData>, where DataTableRowData is exported from @medusajs/ui. Wrap primitive rows, such as string[], in objects.
  • Columns built with @tanstack/react-table v8 types (createColumnHelper, ColumnDef, CellContext) no longer type-check with DataTable. Use createDataTableColumnHelper and DataTableCellContext instead.
  • getIsSomePageRowsSelected() now also returns true when all rows are selected.
  • row.getToggleSelectedHandler() passed to Checkbox's onCheckedChange now throws on click. Use (checked) => row.toggleSelected(!!checked) instead.
  • The dashboard's DataGrid column pinning values are now "start" and "end" instead of "left" and "right".
  • @tanstack/react-table is ESM-only, so Jest suites that import DataTable may need @tanstack added to their transformIgnorePatterns exceptions.
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)}
    />
  ),
})

#17672


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 i18next directly.

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 was onMutateResult where callers expected context.
  • Admin extensions now run on react-i18next 18. Calling t() from an i18next instance that was never initialized now returns "" instead of undefined. Use the admin's instance through getI18n() from react-i18next instead.
  • Translations with an empty value now fall back to English.

#17568


Redis Session Store Uses node-redis

🚧 Breaking change

This only affects projects that set projectConfig.redisOptions in medusa-config.ts. If you only set redisUrl, 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.
  • url can't be set in redisOptions. The connection URL always comes from redisUrl.
  • Session commands now time out after 60 seconds by default. Override it 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.

Existing sessions stay valid after the upgrade.

Learn more in the Medusa Configurations documentation.

#17588


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.LOWEST is now 2,097,151. Hard-coded priorities of 2097152 fall back to the default priority with a warning.
  • Custom workerOptions, queueOptions, and jobOptions use BullMQ 6 types. The debounce event option still works but is deprecated in favor of deduplication.
  • ioredis 6 changes connection defaults for options you don't set in redisOptions: protocol defaults to 3 (RESP3), keepAlive defaults to 30000 ms, and the default retryStrategy waits longer between reconnects. Set protocol: 2 to keep the previous wire protocol.

Learn more in the Redis Event Bus Module and Redis Workflow Engine Module documentation.

#17580


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-trace instead of @medusajs/framework/opentelemetry/sdk-trace-node.
  • 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-*.
  • Traces now include the os.* and service.instance.id resource attributes by default.

Learn more in the Instrumentation documentation.

#17596


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.

#17776
#17813


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, *:create can reindex search indexes, run workflows, and create system default views.
  • Roles with workflow_execution:create or workflow_execution:* can now run any registered workflow.

Review your roles' policies after upgrading.

#17872


Auth Routes Restore the Original req.auth_context Behavior

Behavior change

Affects projects on v2.22.7 with customizations that read req.auth_context in the /auth routes.

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.

#17876


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.

#17901


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.

#17838


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.

#17867

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_cards on 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

Chores

Other Changes

Full Changelog: v2.22.7...v2.23.0

Don't miss a new medusa release

NewReleases is sending notifications on new releases.