The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.
API Workspace Guide
This guide covers work in packages/api.
Read this guide when a task touches:
- custom API routes
- modules, services, models, and migrations
- workflows, links, subscribers, or jobs
- backend configuration or generated route types
Scope
packages/api owns:
- Medusa backend configuration in
medusa-config.ts - custom code under
src/ - route type codegen consumed through
./_generated - backend tests and verification commands
If src/ does not exist yet, create only the folders needed for the feature:
src/apisrc/modulessrc/workflowssrc/linkssrc/subscriberssrc/jobssrc/scripts
Choosing the right backend surface
- Use a route when you need an HTTP endpoint.
- Use a module when you need a persistent domain model or service boundary.
- Use a workflow when the feature is a multi-step business process.
- Use a link when the feature defines a relationship across modules.
- Use a subscriber when the feature reacts to domain events.
- Use a job when the feature runs on a schedule or in the background.
blocks.json relationship
Blocks installed through Mercur CLI route backend files through the api alias:
api->packages/api/src
If a block touches backend code, inspect:
- installed file locations
- required updates to
medusa-config.ts - whether codegen or backend tests must run afterwards
Commands that already exist
Run these from packages/api unless noted otherwise:
devdev:codegenbuildtest:integration:httptest:integration:modulestest:unit
Codegen
Run route codegen when a task changes:
- route paths
- request or response typing used by generated routes
- block-installed API routes that should surface in generated types
If a route task changes generated types, confirm @acme/api/_generated still makes sense for consumers.
medusa-config.ts
Review medusa-config.ts when a task:
- adds a module
- adds module options
- needs env-driven configuration
- adds a provider, feature, or plugin-level dependency
Verification
After non-trivial backend changes, verify the smallest relevant set:
buildtest:integration:httpfor changed route behaviortest:integration:modulesfor module-level behaviortest:unitfor local utility or service logicdev:codegenor equivalent codegen verification when generated types changed
If a block was installed, also verify the files landed in the expected src/* locations.