Load automatically when planning, researching, or implementing ANY Medusa backend features (custom modules, API routes, workflows, data models, module links, business logic). REQUIRED for all Medusa backend work in ALL modes (planning, implementation, exploration). Contains architectural patterns, best practices, and critical rules that MCP servers don't provide.
Comprehensive backend development guide for Medusa applications. Contains patterns across 6 categories covering architecture, type safety, business logic placement, and common pitfalls.
When to Apply
Load this skill for ANY backend development task, including:
Creating or modifying custom modules and data models
Implementing workflows for mutations
Building API routes (store or admin)
Defining module links between entities
Writing business logic or validation
Querying data across modules
Implementing authentication/authorization
Also load these skills when:
building-admin-dashboard-customizations: Building admin UI (widgets, pages, forms)
building-storefronts: Calling backend API routes from storefronts (SDK integration)
CRITICAL: Load Reference Files When Needed
The quick reference below is NOT sufficient for implementation. You MUST load relevant reference files before writing code for that component.
Load these references based on what you're implementing:
Creating a module? → MUST load reference/custom-modules.md first
Creating workflows? → MUST load reference/workflows.md first
Creating API routes? → MUST load reference/api-routes.md first
Creating module links? → MUST load reference/module-links.md first
Querying data? → MUST load reference/querying-data.md first
Adding authentication? → MUST load reference/authentication.md first
Minimum requirement: Load at least 1-2 reference files relevant to your specific task before implementing.
Critical Architecture Pattern
ALWAYS follow this flow - never bypass layers:
Module (data models + CRUD operations)
↓ used by
Workflow (business logic + mutations with rollback)
↓ executed by
API Route (HTTP interface, validation middleware)
↓ called by
Frontend (admin dashboard/storefront via SDK)
Key conventions:
Only GET, POST, DELETE methods (never PUT/PATCH)
Workflows are required for ALL mutations
Business logic belongs in workflow steps, NOT routes
Query with query.graph() for cross-module data retrieval
Query with query.index() (Index Module) for filtering across separate modules with links
Module links maintain isolation between modules
Rule Categories by Priority
Priority
Category
Impact
Prefix
1
Architecture Violations
CRITICAL
arch-
2
Type Safety
CRITICAL
type-
3
Business Logic Placement
HIGH
logic-
4
Import & Code Organization
HIGH
import-
5
Data Access Patterns
MEDIUM (includes CRITICAL price rule)
data-
6
File Organization
MEDIUM
file-
Quick Reference
1. Architecture Violations (CRITICAL)
arch-workflow-required - Use workflows for ALL mutations, never call module services from routes
arch-layer-bypass - Never bypass layers (route → service without workflow)
arch-http-methods - Use only GET, POST, DELETE (never PUT/PATCH)
arch-module-isolation - Use module links, not direct cross-module service calls
arch-query-config-fields - Don't set explicit fields when using req.queryConfig
2. Type Safety (CRITICAL)
type-request-schema - Pass Zod inferred type to MedusaRequest<T> when using req.validatedBody
type-authenticated-request - Use AuthenticatedMedusaRequest for protected routes (not MedusaRequest)
type-export-schema - Export both Zod schema AND inferred type from middlewares
type-linkable-auto - Never add .linkable() to data models (automatically added)
type-module-name-camelcase - Module names MUST be camelCase, never use dashes (causes runtime errors)
3. Business Logic Placement (HIGH)
logic-workflow-validation - Put business validation in workflow steps, not API routes
logic-ownership-checks - Validate ownership/permissions in workflows, not routes
logic-module-service - Keep modules simple (CRUD only), put logic in workflows
4. Import & Code Organization (HIGH)
import-top-level - Import workflows/modules at file top, never use await import() in route body
import-static-only - Use static imports for all dependencies
import-no-dynamic-routes - Dynamic imports add overhead and break type checking
5. Data Access Patterns (MEDIUM)
data-price-format - CRITICAL: Prices are stored as-is in Medusa (49.99 stored as 49.99, NOT in cents). Never multiply by 100 when saving or divide by 100 when displaying
data-query-method - Use query.graph() for retrieving data; use query.index() (Index Module) for filtering across linked modules
data-query-graph - Use query.graph() for cross-module queries with dot notation (without cross-module filtering)
data-query-index - Use query.index() when filtering by properties of linked data models in separate modules
data-list-and-count - Use listAndCount for single-module paginated queries
data-linked-filtering - query.graph() can't filter by linked module fields - use query.index() or query from that entity directly
data-no-js-filter - Don't use JavaScript .filter() on linked data - use database filters (query.index() or query the entity)
data-same-module-ok - Can filter by same-module relations with query.graph() (e.g., product.variants)
Workflows: Test mutation operations and verify rollback on errors
Subscribers: Trigger events and check logs for subscriber execution
Scheduled jobs: Wait for job execution or check logs for cron output
Format for Presenting Next Steps
Always present next steps in a clear, actionable format after implementation:
## Implementation Complete
The [feature name] has been successfully implemented. Here's how to test it:
### Start the Development Server
[server start command based on package manager]
### Access the Admin Dashboard
Open http://localhost:9000/app in your browser
### Test the API Routes
I've added the following routes:
**Admin Routes:**
- POST /admin/[route] - [description]
- GET /admin/[route] - [description]
**Store Routes:**
- POST /store/[route] - [description]
### What to Test
1. [Specific test case 1]
2. [Specific test case 2]
3. [Specific test case 3]
How to Use
For detailed patterns and examples, load reference files:
reference/custom-modules.md - Creating modules with data models
reference/workflows.md - Workflow creation and step patterns
reference/api-routes.md - API route structure and validation
reference/module-links.md - Linking entities across modules
reference/querying-data.md - Query patterns and filtering rules
reference/authentication.md - Protecting routes and accessing users
reference/error-handling.md - MedusaError types and patterns
reference/scheduled-jobs.md - Cron jobs and periodic tasks
reference/subscribers-and-events.md - Event handling
reference/troubleshooting.md - Common errors and solutions
Each reference file contains:
Step-by-step implementation checklists
Correct vs incorrect code examples
TypeScript patterns and type safety
Common pitfalls and solutions
When to Use This Skill vs MedusaDocs MCP Server
⚠️ CRITICAL: This skill should be consulted FIRST for planning and implementation.
Use this skill for (PRIMARY SOURCE):
Planning - Understanding how to structure Medusa backend features
Architecture - Module → Workflow → API Route patterns
Best practices - Correct vs incorrect code patterns
Critical rules - What NOT to do (common mistakes and anti-patterns)
Implementation patterns - Step-by-step guides with checklists
Use MedusaDocs MCP server for (SECONDARY SOURCE):
Specific method signatures after you know which method to use
Built-in module configuration options
Official type definitions
Framework-level configuration details
Why skills come first:
Skills contain opinionated guidance and anti-patterns MCP doesn't have
Skills show architectural patterns needed for planning
MCP is reference material; skills are prescriptive guidance
Integration with Frontend Applications
⚠️ CRITICAL: Frontend applications MUST use the Medusa JS SDK for ALL API requests
When building features that span backend and frontend:
For Admin Dashboard:
Backend (this skill): Module → Workflow → API Route
