Medusa Backend Development
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 routesarch-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 callsarch-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.validatedBodytype-authenticated-request - Use AuthenticatedMedusaRequest for protected routes (not MedusaRequest)type-export-schema - Export both Zod schema AND inferred type from middlewarestype-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 routeslogic-ownership-checks - Validate ownership/permissions in workflows, not routeslogic-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 bodyimport-static-only - Use static imports for all dependenciesimport-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 displayingdata-query-method - Use query.graph() for retrieving data; use query.index() (Index Module) for filtering across linked modulesdata-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 modulesdata-list-and-count - Use listAndCount for single-module paginated queriesdata-linked-filtering - query.graph() can't filter by linked module fields - use query.index() or query from that entity directlydata-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)data-auth-middleware - Trust authenticate middleware, don't manually check req.auth_context
6. File Organization (MEDIUM)
file-workflow-steps - Recommended: Create steps in src/workflows/steps/[name].tsfile-workflow-composition - Composition functions in src/workflows/[name].tsfile-middleware-exports - Export schemas and types from middleware filesfile-links-directory - Define module links in src/links/[name].ts
Workflow Composition Rules
The workflow function has critical constraints:
const myWorkflow = createWorkflow(
"name",
function (input) {
const result = myStep(input)
return new WorkflowResponse(result)
}
)
const myWorkflow = createWorkflow(
"name",
async (input) => {
const result = await myStep(input)
if (input.condition) { }
return new WorkflowResponse(result)
}
)
Constraints:
- No async/await (runs at load time)
- No arrow functions (use
function)
- No conditionals/ternaries (use
when())
- No variable manipulation (use
transform())
- No date creation (use
transform())
- Multiple step calls need
.config({ name: "unique-name" }) to avoid conflicts
Common Mistakes Checklist
Before implementing, verify you're NOT doing these:
Architecture:
Type Safety:
Business Logic:
Imports:
Data Access:
Validating Implementation
CRITICAL: Always run the build command after completing implementation to catch type errors and runtime issues.
When to Validate
- After implementing any new feature
- After making changes to modules, workflows, or API routes
- Before marking tasks as complete
- Proactively, without waiting for the user to ask
How to Run Build
Detect the package manager and run the appropriate command:
npm run build
Handling Build Errors
If the build fails:
- Read the error messages carefully
- Fix type errors, import issues, and syntax errors
- Run the build again to verify the fix
- Do NOT mark implementation as complete until build succeeds
Common build errors:
- Missing imports or exports
- Type mismatches (e.g., missing
MedusaRequest<T> type argument)
- Incorrect workflow composition (async functions, conditionals)
Next Steps - Testing Your Implementation
After successfully implementing a feature, always provide these next steps to the user:
1. Start the Development Server
If the server isn't already running, start it:
npm run dev
2. Access the Admin Dashboard
Open your browser and navigate to:
Log in with your admin credentials to test any admin-related features.
3. Test API Routes
If you implemented custom API routes, list them for the user to test:
Admin Routes (require authentication):
POST http://localhost:9000/admin/[your-route] - Description of what it doesGET http://localhost:9000/admin/[your-route] - Description of what it does
Store Routes (public or customer-authenticated):
POST http://localhost:9000/store/[your-route] - Description of what it doesGET http://localhost:9000/store/[your-route] - Description of what it does
Testing with cURL example:
curl -X POST http://localhost:9000/admin/reviews/123/approve \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_TOKEN" \
--cookie "connect.sid=YOUR_SESSION_COOKIE"
curl -X POST http://localhost:9000/store/reviews \
-H "Content-Type: application/json" \
-d '{"product_id": "prod_123", "rating": 5, "comment": "Great product!"}'
4. Additional Testing Steps
Depending on what was implemented, mention:
- 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
