@medusajs/admin-vite-plugin 2.22.0-snapshot-20261020204851 → 2.22.0

package/AGENTS.md

@@ -0,0 +1,62 @@
+# @medusajs/admin-vite-plugin
+
+Vite plugin that scans the `src/admin` directories of a Medusa app and its plugins and turns them into the `virtual:medusa/*` modules that `@medusajs/dashboard` imports (routes, menu items, widgets, layouts, i18n, custom fields, cell renderers, search entities).
+
+## Using this package
+
+App developers don't configure it: `@medusajs/admin-bundler` adds it with `sources` = every admin source directory. Options (`MedusaVitePluginOptions`):
+
+- `sources?: string[]`: absolute paths to `src/admin` directories.
+- `pluginMode?: boolean`: used by `medusa plugin:build`. It writes `src/admin/__admin-extensions__.js` in `buildStart` (re-exporting every generated module as one default `plugin` object) and deletes it in `buildEnd`.
+
+What it picks up, relative to each source:
+
+| Path | Requirement |
+| --- | --- |
+| `widgets/**` | default export + `export const config = defineWidgetConfig({ zone })` |
+| `routes/**/page.{tsx,jsx,ts,js}` (depth >= 1) | default export; optional `config`, `handle`, `loader` |
+| `layouts/**` | default export + `config` named export |
+| `i18n/index.*` (top level only) | default export; multiple sources are `deepMerge`d |
+| `custom-fields/**` | experimental custom-fields config |
+| `cell-renderers.tsx`, `search-entities.tsx` or `search-entities.ts` | imported for side effects |
+
+Route path mapping (`routes/helpers.ts`):
+- `[id]` becomes `:id`, `[[id]]` becomes `:id?`, `(foo)` becomes `foo?`, `[*]` becomes `*`, `[[*]]` becomes `*?`.
+- A folder starting with `@` is a parallel route, added as a child of its parent path with the `@` removed.
+
+## Architecture
+
+- `src/plugin.ts`:
+  - `resolveId` / `load` serve the virtual modules.
+  - In dev, a watcher computes a content hash per admin subdirectory and reloads only the virtual modules whose hash changed.
+- `src/<feature>/`: one folder per extension type, each with `generate-*.ts` (code generation) and `generate-*-hash.ts` (change detection).
+- `src/virtual-modules/`: assembles generated code into modules. Each generator takes `pluginMode` and emits `const xModule = ...` instead of `export default` so plugin mode can concatenate them.
+- `src/utils.ts`:
+  - `crawl` (fdir) skips directories starting with `_`.
+  - `getConfigObjectProperties` handles both unbundled (`ExportNamedDeclaration`) and bundled (`VariableDeclarator`) shapes, because plugin output is re-parsed when the host app builds.
+- `src/vmod.ts`: virtual and resolved (`\0`-prefixed) ids, built from `@medusajs/admin-shared`.
+
+## Development
+
+```bash
+yarn build        # tsup (cjs + esm)
+yarn watch
+yarn test         # vitest --run
+yarn test src/widgets/__tests__/generate-widgets.spec.ts
+```
+
+Specs live in `src/<feature>/__tests__/`. They mock the filesystem and compare generated code with `normalizeString` (whitespace-insensitive).
+
+## Gotchas
+
+- All extraction is static (Babel AST). Values computed at runtime (variables, template literals, spreads for `zone`) are ignored with a `logger.warn` and the extension is silently dropped.
+- `getParserOptions` enables the `typescript` Babel plugin only for `.tsx`. A `.ts` widget, route, or layout file containing type syntax fails to parse and is skipped.
+- Widget ids default to `Widget-<4-char md5>` of the path from `widgets/` onward, so they are stable across machines but change when the file moves. Saved user layouts are keyed by this id.
+- Unknown zones pass validation (`isValidInjectionZone` only warns), so custom zones from plugins work without registration here.
+- When adding a new extension type, update all of these:
+  - the virtual id in `@medusajs/admin-shared`
+  - `vmod.ts`
+  - `loadConfigs` and `watcherConfigs` in `plugin.ts`
+  - `ADMIN_SUBDIRECTORIES` in `utils.ts`
+  - `generatePluginEntryModule`
+  - the dashboard's `tsup.config.cjs` externals

package/README.md

@@ -1 +1,56 @@
-# @medusajs/admin-vite-plugin
+<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/admin-vite-plugin
+</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>
+
+Vite plugin for the Medusa Admin dashboard: finds admin extensions (widgets, UI routes, custom fields, layouts, translations, and more) under `src/admin` in a Medusa application or plugin and loads them into the dashboard. It's internal plumbing used by `@medusajs/admin-bundler` and the `@medusajs/dashboard` dev server, so you don't need to install or configure it in a Medusa application.
+
+## At a glance
+
+| | |
+|---|---|
+| Package | `@medusajs/admin-vite-plugin` |
+| Type | Internal tooling |
+| Import from | `@medusajs/admin-vite-plugin` (default export) |
+
+## Configuration
+
+| Option | Type | Description | Default |
+|---|---|---|---|
+| `sources` | `string[]` | Paths of the Medusa application or plugin directories to load admin extensions from. | `[]` |
+| `pluginMode` | `boolean` | Build extensions for a Medusa plugin instead of an application. | `false` |
+
+## Resources
+
+- [Admin Development](https://docs.medusajs.com/learn/fundamentals/admin)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medusajs/admin-vite-plugin",
-  "version": "2.22.0-snapshot-20261020204851",
+  "version": "2.22.0",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -21,8 +21,12 @@
   },
   "files": [
     "dist",
-    "package.json"
+    "package.json",
+    "AGENTS.md"
   ],
+  "llms": "https://docs.medusajs.com/llms.txt",
+  "llmsFull": "https://docs.medusajs.com/llms-full.txt",
+  "mcpServer": "https://docs.medusajs.com/mcp",
   "scripts": {
     "build": "yarn run -T tsup",
     "watch": "yarn run -T tsup --watch",
@@ -39,7 +43,7 @@
     "@babel/parser": "7.25.6",
     "@babel/traverse": "7.25.6",
     "@babel/types": "7.25.6",
-    "@medusajs/admin-shared": "2.22.0-snapshot-20261020204851",
+    "@medusajs/admin-shared": "2.22.0",
     "fdir": "6.1.1",
     "magic-string": "0.30.5",
     "outdent": "^0.8.0",