Medusa v2 Plugin Development
Before writing code
Fetch live docs:
- Fetch
https://docs.medusajs.com/learn/fundamentals/plugins for plugin overview
- Web-search
site:docs.medusajs.com plugin vs module for comparison
- Web-search
site:docs.medusajs.com create medusa plugin for plugin scaffolding
- Web-search
site:docs.medusajs.com plugin options configuration for plugin options pattern
- Web-search
site:docs.medusajs.com publish plugin npm for packaging and distribution
Plugin vs Module
| Aspect |
Module |
Plugin |
| Scope |
Single concern (data + service) |
Full feature (modules + routes + workflows + admin) |
| Location |
src/modules/ in project |
Separate npm package |
| Distribution |
Not distributable |
Published to npm |
| Configuration |
Registered in modules array |
Registered in plugins array |
| Contains |
Models, service, loaders |
Modules, API routes, workflows, subscribers, admin, links |
| Use case |
Project-specific domain |
Reusable across projects |
A plugin is essentially a packaged Medusa project that can contain all the same src/ directories.
Plugin Directory Structure
| Directory |
Contents |
src/modules/ |
Custom modules (models, services) |
src/workflows/ |
Workflow definitions |
src/api/store/, src/api/admin/ |
API routes + middlewares.ts |
src/subscribers/ |
Event subscribers |
src/admin/widgets/, src/admin/routes/ |
Admin UI extensions |
src/links/ |
Module link definitions |
| Root |
package.json, tsconfig.json, README.md |
A plugin mirrors the standard Medusa src/ directory structure — all conventions apply.
Plugin Definition
The plugin's package.json must include specific fields:
package.json Key Fields
| Field |
Value |
Purpose |
name |
medusa-plugin-my-feature |
npm package name |
main |
./dist/index.js |
Compiled entry point |
types |
./dist/index.d.ts |
TypeScript declarations |
files |
["dist", "!dist/**/*.map"] |
Included in npm package |
keywords |
["medusa-plugin"] |
Discoverability |
peerDependencies |
@medusajs/framework |
Medusa version compatibility |
Plugin Entry Point
// src/index.ts
// Fetch live docs for plugin export shape
// Plugin entry exports nothing directly --
// Medusa discovers modules, routes, etc. by convention
export default {}
Plugin Options
Plugins receive configuration options from the consuming project:
Consuming a Plugin
// In consuming project's medusa-config.ts plugins array
// Fetch live docs for plugin registration options
{
resolve: "medusa-plugin-my-feature",
options: { apiKey: process.env.MY_FEATURE_API_KEY },
}
Accessing Options in Plugin Code
// In a plugin loader or service
// Fetch live docs for accessing plugin options from container
// Options are injected via the module/plugin options mechanism
Build and Compilation
| Step |
Command |
Purpose |
| Build |
tsc or tsup |
Compile TypeScript to dist/ |
| Watch |
tsc --watch |
Development rebuild on changes |
| Clean |
rm -rf dist |
Remove compiled output |
| Pack |
npm pack |
Create tarball for testing |
Local Development with npm link
| Step |
Command |
Context |
| 1. Build plugin |
npm run build |
In plugin directory |
| 2. Create link |
npm link |
In plugin directory |
| 3. Link in project |
npm link medusa-plugin-my-feature |
In Medusa project |
| 4. Register |
Add to plugins in medusa-config.ts |
In Medusa project |
| 5. Migrate |
npx medusa db:migrate |
In Medusa project |
Plugin Testing
| Approach |
Description |
| Unit tests |
Test services, workflow steps in isolation |
| Integration tests |
Use medusa-test-utils to spin up a test Medusa instance |
| Local linking |
Link plugin into a real Medusa project and test manually |
| CI pipeline |
Build + unit tests on every push |
Publishing to npm
Pre-publish Checklist
| Check |
Why |
| Build succeeds |
Consumers need compiled JS |
files in package.json |
Only ship dist/, not src/ |
peerDependencies set |
Avoid version conflicts |
| README with install instructions |
Developer experience |
.npmignore or files field |
Exclude tests, config, etc. |
| License field set |
Legal clarity |
| Version follows semver |
Compatibility signals |
Publishing Commands
npm version patch # or minor / major
npm publish --access public
# Fetch live docs for Medusa plugin registry conventions
Naming Conventions
| Convention |
Example |
| npm package name |
medusa-plugin-my-feature |
| Module key inside plugin |
my-feature |
| API route prefix |
/store/my-feature, /admin/my-feature |
| Admin widget files |
src/admin/widgets/my-feature-widget.tsx |
Best Practices
- Follow the
medusa-plugin-* naming convention for npm discoverability
- Keep
peerDependencies on @medusajs/framework and @medusajs/medusa -- do not bundle them
- Ship only compiled output (
dist/) -- never ship src/ or test files
- Include TypeScript declarations for consuming projects to get type safety
- Document all plugin options in your README with required vs optional markers
- Test with
npm link against a real Medusa project before publishing
- Use semantic versioning -- breaking changes to options or models require a major bump
Fetch the Medusa plugin documentation for exact project structure, build configuration, and publishing requirements before implementing.
1---2name: medusa-plugins3description: Develop and publish Medusa v2 plugins — plugin structure, plugin vs module comparison, npm packaging, and reusable plugin template. Use when building distributable Medusa extensions.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/medusa-plugins7---89# Medusa v2 Plugin Development1011## Before writing code1213**Fetch live docs**:141. Fetch `https://docs.medusajs.com/learn/fundamentals/plugins` for plugin overview152. Web-search `site:docs.medusajs.com plugin vs module` for comparison163. Web-search `site:docs.medusajs.com create medusa plugin` for plugin scaffolding174. Web-search `site:docs.medusajs.com plugin options configuration` for plugin options pattern185. Web-search `site:docs.medusajs.com publish plugin npm` for packaging and distribution1920## Plugin vs Module2122| Aspect | Module | Plugin |23|--------|--------|--------|24| Scope | Single concern (data + service) | Full feature (modules + routes + workflows + admin) |25| Location | `src/modules/` in project | Separate npm package |26| Distribution | Not distributable | Published to npm |27| Configuration | Registered in `modules` array | Registered in `plugins` array |28| Contains | Models, service, loaders | Modules, API routes, workflows, subscribers, admin, links |29| Use case | Project-specific domain | Reusable across projects |3031A plugin is essentially a packaged Medusa project that can contain all the same `src/` directories.3233## Plugin Directory Structure3435| Directory | Contents |36|-----------|----------|37| `src/modules/` | Custom modules (models, services) |38| `src/workflows/` | Workflow definitions |39| `src/api/store/`, `src/api/admin/` | API routes + `middlewares.ts` |40| `src/subscribers/` | Event subscribers |41| `src/admin/widgets/`, `src/admin/routes/` | Admin UI extensions |42| `src/links/` | Module link definitions |43| Root | `package.json`, `tsconfig.json`, `README.md` |4445A plugin mirrors the standard Medusa `src/` directory structure — all conventions apply.4647## Plugin Definition4849The plugin's `package.json` must include specific fields:5051### package.json Key Fields5253| Field | Value | Purpose |54|-------|-------|---------|55| `name` | `medusa-plugin-my-feature` | npm package name |56| `main` | `./dist/index.js` | Compiled entry point |57| `types` | `./dist/index.d.ts` | TypeScript declarations |58| `files` | `["dist", "!dist/**/*.map"]` | Included in npm package |59| `keywords` | `["medusa-plugin"]` | Discoverability |60| `peerDependencies` | `@medusajs/framework` | Medusa version compatibility |6162### Plugin Entry Point6364```typescript65// src/index.ts66// Fetch live docs for plugin export shape67// Plugin entry exports nothing directly --68// Medusa discovers modules, routes, etc. by convention69export default {}70```7172## Plugin Options7374Plugins receive configuration options from the consuming project:7576### Consuming a Plugin7778```typescript79// In consuming project's medusa-config.ts plugins array80// Fetch live docs for plugin registration options81{82 resolve: "medusa-plugin-my-feature",83 options: { apiKey: process.env.MY_FEATURE_API_KEY },84}85```8687### Accessing Options in Plugin Code8889```typescript90// In a plugin loader or service91// Fetch live docs for accessing plugin options from container92// Options are injected via the module/plugin options mechanism93```9495## Build and Compilation9697| Step | Command | Purpose |98|------|---------|---------|99| Build | `tsc` or `tsup` | Compile TypeScript to `dist/` |100| Watch | `tsc --watch` | Development rebuild on changes |101| Clean | `rm -rf dist` | Remove compiled output |102| Pack | `npm pack` | Create tarball for testing |103104## Local Development with npm link105106| Step | Command | Context |107|------|---------|---------|108| 1. Build plugin | `npm run build` | In plugin directory |109| 2. Create link | `npm link` | In plugin directory |110| 3. Link in project | `npm link medusa-plugin-my-feature` | In Medusa project |111| 4. Register | Add to `plugins` in `medusa-config.ts` | In Medusa project |112| 5. Migrate | `npx medusa db:migrate` | In Medusa project |113114## Plugin Testing115116| Approach | Description |117|----------|-------------|118| Unit tests | Test services, workflow steps in isolation |119| Integration tests | Use `medusa-test-utils` to spin up a test Medusa instance |120| Local linking | Link plugin into a real Medusa project and test manually |121| CI pipeline | Build + unit tests on every push |122123## Publishing to npm124125### Pre-publish Checklist126127| Check | Why |128|-------|-----|129| Build succeeds | Consumers need compiled JS |130| `files` in package.json | Only ship `dist/`, not `src/` |131| `peerDependencies` set | Avoid version conflicts |132| README with install instructions | Developer experience |133| `.npmignore` or `files` field | Exclude tests, config, etc. |134| License field set | Legal clarity |135| Version follows semver | Compatibility signals |136137### Publishing Commands138139```bash140npm version patch # or minor / major141npm publish --access public142# Fetch live docs for Medusa plugin registry conventions143```144145## Naming Conventions146147| Convention | Example |148|-----------|---------|149| npm package name | `medusa-plugin-my-feature` |150| Module key inside plugin | `my-feature` |151| API route prefix | `/store/my-feature`, `/admin/my-feature` |152| Admin widget files | `src/admin/widgets/my-feature-widget.tsx` |153154## Best Practices155156- Follow the `medusa-plugin-*` naming convention for npm discoverability157- Keep `peerDependencies` on `@medusajs/framework` and `@medusajs/medusa` -- do not bundle them158- Ship only compiled output (`dist/`) -- never ship `src/` or test files159- Include TypeScript declarations for consuming projects to get type safety160- Document all plugin options in your README with required vs optional markers161- Test with `npm link` against a real Medusa project before publishing162- Use semantic versioning -- breaking changes to options or models require a major bump163164Fetch the Medusa plugin documentation for exact project structure, build configuration, and publishing requirements before implementing.