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.
