@medusajs/admin-sdk 2.22.0-snapshot-20261020204851 → 2.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/AGENTS.md +93 -0
  2. package/README.md +89 -1
  3. package/package.json +7 -3
package/AGENTS.md ADDED
@@ -0,0 +1,93 @@
1
+ # @medusajs/admin-sdk
2
+
3
+ Config helpers that Medusa apps and plugins use to declare Admin customizations under `src/admin`. The helpers only tag config objects; `@medusajs/admin-vite-plugin` finds and wires the files by statically parsing them.
4
+
5
+ ## Using this package
6
+
7
+ Import directly from `@medusajs/admin-sdk`:
8
+
9
+ - `defineWidgetConfig({ zone, id? })`: widget in `src/admin/widgets/*.tsx`.
10
+ - `defineRouteConfig({ label?, icon?, nested?, rank?, translationNs? })`: UI route in `src/admin/routes/**/page.tsx`.
11
+ - `defineLayoutConfig({ id, sections })`: custom layout in `src/admin/layouts/`.
12
+ - `unstable_defineCustomFieldsConfig`, `unstable_createFormHelper`: experimental custom fields (product model only) in `src/admin/custom-fields/`.
13
+ - Types: `WidgetConfig`, `RouteConfig`, `LayoutConfig`.
14
+
15
+ ```tsx
16
+ // src/admin/widgets/product-widget.tsx
17
+ import { defineWidgetConfig } from "@medusajs/admin-sdk"
18
+ import { DetailWidgetProps, AdminProduct } from "@medusajs/framework/types"
19
+ import { Container, Heading } from "@medusajs/ui"
20
+
21
+ const ProductWidget = ({ data }: DetailWidgetProps<AdminProduct>) => {
22
+ return (
23
+ <Container className="divide-y p-0">
24
+ <Heading level="h2">{data.title}</Heading>
25
+ </Container>
26
+ )
27
+ }
28
+
29
+ export const config = defineWidgetConfig({
30
+ zone: "product.details",
31
+ })
32
+
33
+ export default ProductWidget
34
+ ```
35
+
36
+ ```tsx
37
+ // src/admin/routes/brands/page.tsx -> /app/brands
38
+ import { defineRouteConfig } from "@medusajs/admin-sdk"
39
+ import { TagSolid } from "@medusajs/icons"
40
+
41
+ const BrandsPage = () => {
42
+ // ...
43
+ }
44
+
45
+ export const config = defineRouteConfig({
46
+ label: "Brands",
47
+ icon: TagSolid,
48
+ })
49
+
50
+ export default BrandsPage
51
+ ```
52
+
53
+ Widget zones:
54
+ - The full list is `INJECTION_ZONES` in `@medusajs/admin-shared` (`packages/admin/admin-shared/src/extensions/widgets/constants.ts`).
55
+ - Current zones are `<entity>.details`, `<entity>.details.side`, `<entity>.list`, plus `login.before`, `login.after`, `topbar`, `search.list`.
56
+ - `.before` / `.after` variants of other zones are legacy since v2.17.2. Users now reorder widgets with the layout customizer.
57
+ - Plugins can add zones by augmenting `InjectionZoneRegistry` from `@medusajs/admin-shared`.
58
+
59
+ Route config:
60
+ - `nested` puts the sidebar item under one of `/orders`, `/products`, `/inventory`, `/customers`, `/promotions`, `/price-lists`.
61
+ - Routes under `src/admin/routes/settings/` appear in Settings.
62
+ - Optionally export `handle` (`breadcrumb`, `seo`) and `loader` from the page file.
63
+
64
+ Docs:
65
+ - https://docs.medusajs.com/learn/fundamentals/admin/widgets.md
66
+ - https://docs.medusajs.com/learn/fundamentals/admin/ui-routes.md
67
+ - https://docs.medusajs.com/learn/fundamentals/admin/constraints.md
68
+ - https://docs.medusajs.com/learn/fundamentals/admin/custom-injection-zones.md
69
+ - https://docs.medusajs.com/resources/admin-widget-injection-zones.md
70
+
71
+ ## Architecture
72
+
73
+ - `src/config/utils.ts`: every helper wraps the config with `createConfigHelper`, which adds `$$typeof: Symbol.for("react.memo")` so React Fast Refresh treats the module as component-only and hot-reloads it instead of doing a full reload. Keep this when adding helpers.
74
+ - `src/config/types.ts`: public config types; zone, layout, and nested-route types come from `@medusajs/admin-shared`.
75
+ - `CustomFieldConfig` and its types are intentionally not re-exported from `src/config/index.ts`.
76
+
77
+ ## Development
78
+
79
+ ```bash
80
+ yarn build # tsup
81
+ ```
82
+
83
+ No tests in this package. Extraction behavior is tested in `@medusajs/admin-vite-plugin`.
84
+
85
+ ## Gotchas
86
+
87
+ - The vite plugin reads config by AST, not at runtime:
88
+ - `config` must be a named export initialized with a call that takes an object literal.
89
+ - `zone` must be a string literal or an array of string literals. Template literals and variables are rejected with a warning and the widget is dropped.
90
+ - Widget and route files without a default export are skipped. The docs also require the components to be arrow functions.
91
+ - Without `id`, a widget's id is a hash of its path from `widgets/` onward. Renaming or moving the file resets users' saved layout for it. Plugins should set an explicit, prefixed `id`.
92
+ - The `unstable_createFormHelper` JSDoc example uses stale keys (`entryPoint`, `form`). The real keys are `model` and `zone` (see `CustomFieldConfig`).
93
+ - Directories under `src/admin` whose names start with `_` are not crawled.
package/README.md CHANGED
@@ -1 +1,89 @@
1
- # @medusajs/admin-sdk
1
+ <p align="center">
2
+ <a href="https://www.medusajs.com">
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/59018053/229103275-b5e482bb-4601-46e6-8142-244f531cebdb.svg">
5
+ <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
6
+ <img alt="Medusa logo" src="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
7
+ </picture>
8
+ </a>
9
+ </p>
10
+ <h1 align="center">
11
+ @medusajs/admin-sdk
12
+ </h1>
13
+
14
+ <h4 align="center">
15
+ <a href="https://docs.medusajs.com">Documentation</a> |
16
+ <a href="https://www.medusajs.com">Website</a>
17
+ </h4>
18
+
19
+ <p align="center">
20
+ Building blocks for digital commerce
21
+ </p>
22
+ <p align="center">
23
+ <a href="https://github.com/medusajs/medusa/blob/develop/LICENSE">
24
+ <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="Medusa is released under the MIT license." />
25
+ </a>
26
+ <a href="https://github.com/medusajs/medusa/blob/develop/CONTRIBUTING.md">
27
+ <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" alt="PRs welcome!" />
28
+ </a>
29
+ <a href="https://discord.gg/xpCwq3Kfn8">
30
+ <img src="https://img.shields.io/badge/chat-on%20discord-7289DA.svg" alt="Discord Chat" />
31
+ </a>
32
+ <a href="https://twitter.com/intent/follow?screen_name=medusajs">
33
+ <img src="https://img.shields.io/twitter/follow/medusajs.svg?label=Follow%20@medusajs" alt="Follow @medusajs" />
34
+ </a>
35
+ </p>
36
+
37
+ Admin SDK for Medusa: helpers for configuring Medusa Admin dashboard extensions such as widgets, UI routes, and layouts. Import it in the `src/admin` directory of a Medusa application or plugin to export the config of each widget or UI route.
38
+
39
+ ## At a glance
40
+
41
+ | | |
42
+ |---|---|
43
+ | Package | `@medusajs/admin-sdk` |
44
+ | Type | Admin |
45
+ | Import from | `@medusajs/admin-sdk` |
46
+
47
+ ## Features
48
+
49
+ - `defineWidgetConfig`: set the injection zone(s) a widget is shown in, with an optional stable `id`.
50
+ - `defineRouteConfig`: set a UI route's sidebar `label`, `icon`, `nested` position, `rank`, and `translationNs`.
51
+ - `defineLayoutConfig`: declare a custom layout's `id` and `sections`.
52
+ - Types: `WidgetConfig`, `RouteConfig`, `LayoutConfig`.
53
+
54
+ ## Installation
55
+
56
+ ```bash
57
+ npm install @medusajs/admin-sdk
58
+ ```
59
+
60
+ ## Usage
61
+
62
+ ```tsx title="src/admin/widgets/product-widget.tsx"
63
+ import { defineWidgetConfig } from "@medusajs/admin-sdk"
64
+ import { Container, Heading } from "@medusajs/ui"
65
+
66
+ const ProductWidget = () => {
67
+ return (
68
+ <Container className="divide-y p-0">
69
+ <div className="flex items-center justify-between px-6 py-4">
70
+ <Heading level="h2">Product Widget</Heading>
71
+ </div>
72
+ </Container>
73
+ )
74
+ }
75
+
76
+ export const config = defineWidgetConfig({
77
+ zone: "product.details",
78
+ })
79
+
80
+ export default ProductWidget
81
+ ```
82
+
83
+ ## Resources
84
+
85
+ - [Admin Development](https://docs.medusajs.com/learn/fundamentals/admin)
86
+ - [Admin Widgets](https://docs.medusajs.com/learn/fundamentals/admin/widgets)
87
+ - [Admin UI Routes](https://docs.medusajs.com/learn/fundamentals/admin/ui-routes)
88
+ - [Widget Injection Zones](https://docs.medusajs.com/resources/admin-widget-injection-zones)
89
+ - [Admin Components](https://docs.medusajs.com/resources/admin-components)
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@medusajs/admin-sdk",
3
3
  "description": "SDK for building extension for the Medusa admin dashboard.",
4
- "version": "2.22.0-snapshot-20261020204851",
4
+ "version": "2.22.0",
5
5
  "author": "Kasper Kristensen <kasper@medusajs.com>",
6
6
  "types": "dist/index.d.ts",
7
7
  "main": "dist/index.js",
@@ -16,13 +16,17 @@
16
16
  },
17
17
  "files": [
18
18
  "dist",
19
- "package.json"
19
+ "package.json",
20
+ "AGENTS.md"
20
21
  ],
22
+ "llms": "https://docs.medusajs.com/llms.txt",
23
+ "llmsFull": "https://docs.medusajs.com/llms-full.txt",
24
+ "mcpServer": "https://docs.medusajs.com/mcp",
21
25
  "scripts": {
22
26
  "build": "yarn run -T tsup"
23
27
  },
24
28
  "dependencies": {
25
- "@medusajs/admin-shared": "2.22.0-snapshot-20261020204851",
29
+ "@medusajs/admin-shared": "2.22.0",
26
30
  "zod": "4.2.0"
27
31
  },
28
32
  "packageManager": "yarn@3.2.1"