@medusajs/dashboard 2.22.0-snapshot-20261020204851 → 2.22.0

package/AGENTS.md

@@ -0,0 +1,89 @@
+# @medusajs/dashboard
+
+The Medusa Admin single-page app (React, Vite, React Router, TanStack Query, `@medusajs/ui`). Applications never run it directly: `@medusajs/admin-bundler` mounts it at `admin.path` (default `/app`) and feeds it app and plugin extensions through `virtual:medusa/*` modules.
+
+## Using this package
+
+Widgets and UI routes are declared with `@medusajs/admin-sdk`. This package supplies the building blocks to use inside them (public since v2.21.0):
+
+- `@medusajs/dashboard/components`: `LayoutComposer`, `DataTable`, `DataGrid`, `ActionMenu`, `RouteDrawer`, `RouteFocusModal`, `StackedDrawer`, `StackedFocusModal`, `useRouteModal`, `Form`, `Combobox`, `SectionRow`, `JsonViewSection`, product table cells, ...
+- `@medusajs/dashboard/hooks`: TanStack Query hooks per resource (`useProducts`, `useOrder`, `useRegions`, ...) and their query key factories (`productsQueryKeys`, ...), plus `useQueryParams`, `useDate`, `useComboboxData`.
+- `@medusajs/dashboard/lib`: `defineCellRenderer`, `defineSearchEntity`, `formatCurrency`, `getStylizedAmount`, address and validation helpers.
+- `@medusajs/dashboard` (root): types `Resources` (for i18next type augmentation) and `DashboardPlugin`.
+
+Only what `src/exports/*` re-exports is public. Never deep-import from `src/`.
+
+```tsx
+import { useProducts, productsQueryKeys } from "@medusajs/dashboard/hooks"
+import { useQueryClient } from "@tanstack/react-query"
+
+const ProductCount = () => {
+  const queryClient = useQueryClient()
+  const { products, count, isPending } = useProducts({ limit: 10 })
+
+  const refresh = () =>
+    queryClient.invalidateQueries({ queryKey: productsQueryKeys.lists() })
+  // ...
+}
+```
+
+Expose injection zones on a custom page with `LayoutComposer` (zones are `<prefix>` and `<prefix>.side`):
+
+```tsx
+import { LayoutComposer } from "@medusajs/dashboard/components"
+
+<LayoutComposer
+  widgetsZonePrefix="brand.details"
+  preferredLayoutId="core:two-column"
+  data={brand}
+  sections={{ main: <GeneralSection brand={brand} /> }}
+/>
+```
+
+Docs:
+- https://docs.medusajs.com/resources/admin-components.md
+- https://docs.medusajs.com/resources/admin-components/layouts/layout-composer.md
+- https://docs.medusajs.com/resources/admin-components/hooks.md
+- https://docs.medusajs.com/learn/fundamentals/admin/custom-injection-zones.md
+
+## Architecture
+
+- `src/app.tsx`: entry. Imports the `virtual:medusa/*` modules; tsup keeps them `external` so `@medusajs/admin-vite-plugin` resolves them when the host app builds.
+- `src/dashboard-app/`: `DashboardApp` merges core routes with extension routes, menu items, widgets, custom-field forms/displays, and layouts. `routes/get-route.map.tsx` is the core route table; every page is lazy-loaded.
+- `src/routes/<domain>/<domain>-<page>/`: each page's `index.ts` exports `Component`, and optionally `loader`, `Breadcrumb`, `seo`, consumed by `lazy()` in the route map. Create/edit forms are child routes rendered in `RouteDrawer` / `RouteFocusModal` through the parent's `<Outlet />`.
+- `src/hooks/api/<resource>.tsx`: one file per resource:
+  - `xQueryKeys = queryKeysFactory("x")` (`all`, `lists()`, `list(query)`, `details()`, `detail(id, query)`).
+  - Query hooks call `sdk.admin.*` from `src/lib/client` and return `{ ...data, ...rest }`.
+  - Mutation hooks invalidate the affected `lists()` / `detail(id)` keys in `onSuccess`, then call `options?.onSuccess?.(...)`.
+- Detail-page loaders prefetch with `queryClient.getQueryData(key) ?? queryClient.fetchQuery(...)` using the same key and `fields` as the page's hook, which then receives the result as `initialData`. Keep loader and hook `fields` identical or the cache misses.
+- Detail and list pages render `LayoutComposer` with `widgetsZonePrefix` set to the page's injection zone and wrap each core section in `<LayoutComposer.Entry id="...">`.
+- `src/lib/client/client.ts`: JS SDK instance built from bundler defines `__BACKEND_URL__`, `__AUTH_TYPE__` (default `"session"`), `__JWT_TOKEN_STORAGE_KEY__`.
+- `src/i18n/translations/`: `en.json` is the source of truth; `$schema.json` is generated from it.
+
+## Development
+
+```bash
+yarn build          # tsgo typecheck, then tsup
+yarn typecheck
+yarn lint
+yarn test           # vitest --run
+yarn test src/lib/__tests__/promotions.spec.ts
+yarn dev            # standalone Vite dev server
+yarn i18n:schema    # regenerate translations/$schema.json from en.json
+yarn i18n:validate de.json
+yarn i18n:sync missing
+```
+
+- `yarn dev` env vars (in `.env`): `VITE_MEDUSA_BACKEND_URL` (default `http://localhost:9000`), `VITE_MEDUSA_STOREFRONT_URL`, `VITE_MEDUSA_BASE`, and `VITE_MEDUSA_PROJECT`: path to a project's `src/admin` directory whose extensions should be loaded.
+- Vitest runs in the `node` environment by default. Component tests need `// @vitest-environment jsdom` on the first line.
+- Tests live in `__tests__/` directories or as `*.spec.tsx` beside the source.
+
+## Gotchas
+
+- After adding or removing keys in `en.json`, run `yarn i18n:schema` and commit `$schema.json`; `src/i18n/translations/__tests__/validate-translations.spec.ts` validates every locale against it.
+- Add new strings to `en.json` only. Other locales are filled by the daily `.github/workflows/admin-i18n-sync.yml` workflow.
+- A new `widgetsZonePrefix` on a core page also needs its zones added to `INJECTION_ZONES` in `@medusajs/admin-shared`. Do not add `.before` / `.after` zones; they are legacy.
+- Layout preferences are stored per `widgetsZonePrefix`, keyed by widget id and `LayoutComposer.Entry` id. Renaming an entry id drops users' saved placement for it.
+- The `src/exports/*` surface is documented API for extensions. Changing a signature breaks plugins; update the matching page under `www/apps/resources/app/admin-components`.
+- A new virtual module must be added to `external` in `tsup.config.cjs` and to `VIRTUAL_MODULES` in `@medusajs/admin-shared`.
+- `yarn generate:static` writes `src/lib/currencies.ts`, but the app imports `src/lib/data/currencies.ts`. Move the output before relying on it.

package/README.md

@@ -1,33 +1,83 @@
-# React + TypeScript + Vite
-
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
-
-Currently, two official plugins are available:
+<p align="center">
+  <a href="https://www.medusajs.com">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/59018053/229103275-b5e482bb-4601-46e6-8142-244f531cebdb.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
+    <img alt="Medusa logo" src="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
+    </picture>
+  </a>
+</p>
+<h1 align="center">
+  @medusajs/dashboard
+</h1>
+
+<h4 align="center">
+  <a href="https://docs.medusajs.com">Documentation</a> |
+  <a href="https://www.medusajs.com">Website</a>
+</h4>
+
+<p align="center">
+  Building blocks for digital commerce
+</p>
+<p align="center">
+  <a href="https://github.com/medusajs/medusa/blob/develop/LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="Medusa is released under the MIT license." />
+  </a>
+  <a href="https://github.com/medusajs/medusa/blob/develop/CONTRIBUTING.md">
+    <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" alt="PRs welcome!" />
+  </a>
+  <a href="https://discord.gg/xpCwq3Kfn8">
+    <img src="https://img.shields.io/badge/chat-on%20discord-7289DA.svg" alt="Discord Chat" />
+  </a>
+  <a href="https://twitter.com/intent/follow?screen_name=medusajs">
+    <img src="https://img.shields.io/twitter/follow/medusajs.svg?label=Follow%20@medusajs" alt="Follow @medusajs" />
+  </a>
+</p>
+
+The Medusa Admin dashboard: the React and Vite single-page app that merchants use to manage a Medusa store. `@medusajs/medusa` builds it with `@medusajs/admin-bundler` and serves it at the `admin.path` set in `medusa-config.ts` (`/app` by default), so you don't install or run it yourself. Admin extensions can import its components, hooks, and utilities from the subpaths below.
+
+## At a glance
+
+| | |
+|---|---|
+| Package | `@medusajs/dashboard` |
+| Type | Admin |
+| Import from | `@medusajs/dashboard/components`, `@medusajs/dashboard/hooks`, `@medusajs/dashboard/lib` |
+| Entry points | `.` (the app), `./components`, `./hooks`, `./lib`, `./css` |
+
+## Usage
+
+Import shared admin components, hooks, and utilities in your admin extensions:
+
+```tsx
+import { getStylizedAmount } from "@medusajs/dashboard/lib"
+```
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md) uses [Babel](https://babeljs.io/) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+## Development
 
-## Expanding the ESLint configuration
+Run these from `packages/admin/dashboard`:
 
-If you are developing a production application, we recommend updating the configuration to enable type aware lint rules:
+| Command | Description |
+|---|---|
+| `yarn dev` | Start the Vite dev server. |
+| `yarn build` | Type-check and build the package with tsup. |
+| `yarn build:preview` | Build the app with Vite. |
+| `yarn preview` | Preview the Vite build. |
+| `yarn test` | Run the Vitest tests. |
+| `yarn lint` | Run ESLint. |
+| `yarn typecheck` | Type-check the package. |
+| `yarn i18n:validate <file>` | Validate a translation file, such as `de.json`, against the schema. |
+| `yarn i18n:schema` | Regenerate `src/i18n/translations/$schema.json` from `en.json`. Run it after adding or removing keys in `en.json`. |
+| `yarn i18n:sync` | Find or apply missing translations. See [Translations](#translations). |
 
-- Configure the top-level `parserOptions` property like this:
+The dev server reads these variables from a `.env` file:
 
-```js
-export default {
-  // other rules...
-  parserOptions: {
-    ecmaVersion: 'latest',
-    sourceType: 'module',
-    project: ['./tsconfig.json', './tsconfig.node.json'],
-    tsconfigRootDir: __dirname,
-  },
-}
-```
-
-- Replace `plugin:@typescript-eslint/recommended` to `plugin:@typescript-eslint/recommended-type-checked` or `plugin:@typescript-eslint/strict-type-checked`
-- Optionally add `plugin:@typescript-eslint/stylistic-type-checked`
-- Install [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react) and add `plugin:react/recommended` & `plugin:react/jsx-runtime` to the `extends` list
+| Variable | Description | Default |
+|---|---|---|
+| `VITE_MEDUSA_BACKEND_URL` | URL of the Medusa server. | `http://localhost:9000` |
+| `VITE_MEDUSA_STOREFRONT_URL` | URL of the storefront. | `http://localhost:8000` |
+| `VITE_MEDUSA_BASE` | Base path the app is served from. | `/` |
+| `VITE_MEDUSA_PROJECT` | Path to a Medusa project to load admin extensions from. | - |
 
 ## Translations
 
@@ -67,3 +117,10 @@ New keys are inserted next to their neighbors in `en.json`, and existing keys ke
 ### Automated sync
 
 The [Admin i18n Sync](../../../.github/workflows/admin-i18n-sync.yml) workflow runs daily. It finds missing translations, translates them with Claude, and opens a PR on the `chore/admin-i18n-sync-translations` branch. It skips runs while a previous sync PR is still open.
+
+## Resources
+
+- [Admin Development](https://docs.medusajs.com/learn/fundamentals/admin)
+- [Admin Components](https://docs.medusajs.com/resources/admin-components)
+- [Admin Utilities](https://docs.medusajs.com/resources/admin-components/utilities)
+- [Contribute Admin Translations](https://docs.medusajs.com/learn/resources/contribution-guidelines/admin-translations)

package/dist/app.js

@@ -237839,7 +237839,7 @@ var init_search_index_reindex_modal = __esm({
           body.since = data.since.toISOString();
         }
         if (ids?.length) {
-          body.filters = { ids };
+          body.filters = { id: ids };
         }
         await mutateAsync(
           {

package/dist/app.mjs

@@ -14,7 +14,7 @@ import "./chunk-P3UUX2T6.mjs";
 import "./chunk-DG7J63J2.mjs";
 import {
   DashboardApp
-} from "./chunk-STD4XF6S.mjs";
+} from "./chunk-ZCERNCOX.mjs";
 import "./chunk-ONB3JEHR.mjs";
 import "./chunk-JAW6ZD7F.mjs";
 import "./chunk-TO7QJZLE.mjs";

package/dist/{chunk-B5FWZTCF.mjs → chunk-O6JNJQ4K.mjs}

@@ -1,6 +1,6 @@
 import {
   getLinkedFields
-} from "./chunk-STD4XF6S.mjs";
+} from "./chunk-ZCERNCOX.mjs";
 
 // src/routes/products/product-detail/constants.ts
 var PRODUCT_DETAIL_FIELDS = getLinkedFields(

package/dist/{chunk-STD4XF6S.mjs → chunk-ZCERNCOX.mjs}

@@ -138787,7 +138787,7 @@ function getRouteMap({
                   children: [
                     {
                       path: "create",
-                      lazy: () => import("./product-create-BTTUQ3BI.mjs")
+                      lazy: () => import("./product-create-WUZ22WMJ.mjs")
                     },
                     {
                       path: "import",
@@ -138803,7 +138803,7 @@ function getRouteMap({
                   path: ":id",
                   errorElement: /* @__PURE__ */ jsx21(ErrorBoundary, {}),
                   lazy: async () => {
-                    const { Breadcrumb, loader, seo } = await import("./product-detail-VBWNWTIK.mjs");
+                    const { Breadcrumb, loader, seo } = await import("./product-detail-Q7R6CEZD.mjs");
                     return {
                       Component: Outlet5,
                       loader,
@@ -138816,11 +138816,11 @@ function getRouteMap({
                   children: [
                     {
                       path: "",
-                      lazy: () => import("./product-detail-VBWNWTIK.mjs"),
+                      lazy: () => import("./product-detail-Q7R6CEZD.mjs"),
                       children: [
                         {
                           path: "edit",
-                          lazy: () => import("./product-edit-RLWEFGUD.mjs")
+                          lazy: () => import("./product-edit-FIAXOVZP.mjs")
                         },
                         {
                           path: "edit-variant",
@@ -138832,11 +138832,11 @@ function getRouteMap({
                         },
                         {
                           path: "attributes",
-                          lazy: () => import("./product-attributes-I637MRGI.mjs")
+                          lazy: () => import("./product-attributes-VDTTOEN6.mjs")
                         },
                         {
                           path: "organization",
-                          lazy: () => import("./product-organization-EFRLOE45.mjs")
+                          lazy: () => import("./product-organization-PAEWTW56.mjs")
                         },
                         {
                           path: "shipping-profile",
@@ -138868,7 +138868,7 @@ function getRouteMap({
                         },
                         {
                           path: "options/manage",
-                          lazy: () => import("./product-options-manage-UYESJVPQ.mjs")
+                          lazy: () => import("./product-options-manage-H3RCESKS.mjs")
                         }
                       ]
                     },
@@ -140194,7 +140194,7 @@ function getRouteMap({
               handle: {
                 breadcrumb: () => t("searchIndexes.domain")
               },
-              lazy: () => import("./search-index-list-VFEM2IOS.mjs")
+              lazy: () => import("./search-index-list-UMBYJEE2.mjs")
             },
             {
               path: "product-types",

package/dist/{product-attributes-I637MRGI.mjs → product-attributes-VDTTOEN6.mjs}

@@ -6,7 +6,7 @@ import "./chunk-DG7J63J2.mjs";
 import {
   FormExtensionZone,
   useExtendableForm
-} from "./chunk-STD4XF6S.mjs";
+} from "./chunk-ZCERNCOX.mjs";
 import "./chunk-ONB3JEHR.mjs";
 import "./chunk-JAW6ZD7F.mjs";
 import "./chunk-TO7QJZLE.mjs";

package/dist/{product-create-BTTUQ3BI.mjs → product-create-WUZ22WMJ.mjs}

@@ -23,7 +23,7 @@ import {
 import {
   FormExtensionZone,
   useExtendableForm
-} from "./chunk-STD4XF6S.mjs";
+} from "./chunk-ZCERNCOX.mjs";
 import "./chunk-ONB3JEHR.mjs";
 import "./chunk-JAW6ZD7F.mjs";
 import "./chunk-TO7QJZLE.mjs";

package/dist/{product-detail-VBWNWTIK.mjs → product-detail-Q7R6CEZD.mjs}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-AM2BU2RH.mjs";
 import {
   PRODUCT_DETAIL_FIELDS
-} from "./chunk-B5FWZTCF.mjs";
+} from "./chunk-O6JNJQ4K.mjs";
 import {
   SidebarLink
 } from "./chunk-U726TGCM.mjs";
@@ -19,7 +19,7 @@ import {
   getFormattedCountry
 } from "./chunk-B6ZOPCPA.mjs";
 import "./chunk-DG7J63J2.mjs";
-import "./chunk-STD4XF6S.mjs";
+import "./chunk-ZCERNCOX.mjs";
 import "./chunk-ONB3JEHR.mjs";
 import "./chunk-JAW6ZD7F.mjs";
 import "./chunk-TO7QJZLE.mjs";

package/dist/{product-edit-RLWEFGUD.mjs → product-edit-FIAXOVZP.mjs}

@@ -7,7 +7,7 @@ import {
 import {
   FormExtensionZone,
   useExtendableForm
-} from "./chunk-STD4XF6S.mjs";
+} from "./chunk-ZCERNCOX.mjs";
 import "./chunk-ONB3JEHR.mjs";
 import "./chunk-JAW6ZD7F.mjs";
 import "./chunk-TO7QJZLE.mjs";

package/dist/{product-options-manage-UYESJVPQ.mjs → product-options-manage-H3RCESKS.mjs}

@@ -1,9 +1,9 @@
 import {
   PRODUCT_DETAIL_FIELDS
-} from "./chunk-B5FWZTCF.mjs";
+} from "./chunk-O6JNJQ4K.mjs";
 import {
   useExtendableForm
-} from "./chunk-STD4XF6S.mjs";
+} from "./chunk-ZCERNCOX.mjs";
 import "./chunk-ONB3JEHR.mjs";
 import "./chunk-JAW6ZD7F.mjs";
 import "./chunk-TO7QJZLE.mjs";

package/dist/{product-organization-EFRLOE45.mjs → product-organization-PAEWTW56.mjs}

@@ -4,7 +4,7 @@ import {
 import {
   FormExtensionZone,
   useExtendableForm
-} from "./chunk-STD4XF6S.mjs";
+} from "./chunk-ZCERNCOX.mjs";
 import "./chunk-ONB3JEHR.mjs";
 import "./chunk-JAW6ZD7F.mjs";
 import "./chunk-TO7QJZLE.mjs";

package/dist/{search-index-list-VFEM2IOS.mjs → search-index-list-UMBYJEE2.mjs}

@@ -77,7 +77,7 @@ var SearchIndexReindexModal = ({
       body.since = data.since.toISOString();
     }
     if (ids?.length) {
-      body.filters = { ids };
+      body.filters = { id: ids };
     }
     await mutateAsync(
       {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medusajs/dashboard",
-  "version": "2.22.0-snapshot-20261020204851",
+  "version": "2.22.0",
   "license": "SEE LICENSE IN LICENSE",
   "scripts": {
     "typecheck": "tsgo --noEmit -p tsconfig.typecheck.json",
@@ -58,8 +58,12 @@
   "files": [
     "package.json",
     "src",
-    "dist"
+    "dist",
+    "AGENTS.md"
   ],
+  "llms": "https://docs.medusajs.com/llms.txt",
+  "llmsFull": "https://docs.medusajs.com/llms-full.txt",
+  "mcpServer": "https://docs.medusajs.com/mcp",
   "dependencies": {
     "@ariakit/react": "^0.4.15",
     "@babel/runtime": "^7.26.10",
@@ -68,10 +72,10 @@
     "@dnd-kit/utilities": "^3.2.2",
     "@hookform/error-message": "^2.0.1",
     "@hookform/resolvers": "5.5.7",
-    "@medusajs/admin-shared": "2.22.0-snapshot-20261020204851",
-    "@medusajs/icons": "2.22.0-snapshot-20261020204851",
-    "@medusajs/js-sdk": "2.22.0-snapshot-20261020204851",
-    "@medusajs/ui": "4.2.7-snapshot-20261020204851",
+    "@medusajs/admin-shared": "2.22.0",
+    "@medusajs/icons": "2.22.0",
+    "@medusajs/js-sdk": "2.22.0",
+    "@medusajs/ui": "4.2.7",
     "@radix-ui/react-dialog": "1.1.4",
     "@radix-ui/react-dismissable-layer": "1.1.4",
     "@tanstack/react-query": "5.64.2",
@@ -103,10 +107,10 @@
     "zod": "4.2.0"
   },
   "devDependencies": {
-    "@medusajs/admin-shared": "2.22.0-snapshot-20261020204851",
-    "@medusajs/admin-vite-plugin": "2.22.0-snapshot-20261020204851",
-    "@medusajs/types": "2.22.0-snapshot-20261020204851",
-    "@medusajs/ui-preset": "2.22.0-snapshot-20261020204851",
+    "@medusajs/admin-shared": "2.22.0",
+    "@medusajs/admin-vite-plugin": "2.22.0",
+    "@medusajs/types": "2.22.0",
+    "@medusajs/ui-preset": "2.22.0",
     "@types/qrcode": "^1.5.5",
     "@typescript/native-preview": "^7.0.0-dev.20260423.1",
     "eslint": "8",

package/src/routes/search-indexes/search-index-list/components/search-index-reindex-modal.tsx

@@ -52,7 +52,7 @@ export const SearchIndexReindexModal = ({
       body.since = data.since.toISOString()
     }
     if (ids?.length) {
-      body.filters = { ids }
+      body.filters = { id: ids }
     }
 
     await mutateAsync(