Medusa Development

Medusa is a headless commerce framework built around modules, data models, and workflows; almost every piece of business logic — from an API route to a scheduled job — should be expressed as a workflow made of discrete, composable steps.

Workflow for Building a Medusa Feature

1. Define or extend the data model — Use the model utility from @medusajs/framework/utils to declare the module's data model(s) under src/modules/<module>/models/.
2. Write the module service — Create a service in src/modules/<module>/service.ts that extends MedusaService when the module has data models, exposing async methods for domain operations.
3. Register the module — Add the module to medusa-config.ts so Medusa's container can resolve it.
4. Build steps — Define each unit of work as a step with createStep from @medusajs/framework/workflows-sdk, including a compensation function for anything that needs to be undone on failure.
5. Compose the workflow — Wire steps together with createWorkflow, using transform for data shaping and when for conditional branches.
6. Expose the workflow — Call the workflow from an API route, a scheduled job, or a subscriber — never put business logic directly in the route/job/subscriber handler.
7. Read data with Query — Use Medusa's Query (req.scope.resolve("query") or the workflow-level useQueryGraphStep) to fetch data instead of calling module services directly for reads.

General Rules

• Don't use type aliases when importing files — import types and values directly from their source module rather than re-exporting through a local alias.
• When throwing errors, always throw MedusaError (from @medusajs/framework/utils) instead of a plain Error, so the API layer can map it to the correct HTTP status and error code.
• Always use Query to retrieve data rather than calling a module's service methods directly for reads — Query understands module links and can join data across modules in one call.