Skip to content

The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.

2.5 KB
Raw Blame

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/api
  • src/modules
  • src/workflows
  • src/links
  • src/subscribers
  • src/jobs
  • src/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:

  • dev
  • dev:codegen
  • build
  • test:integration:http
  • test:integration:modules
  • test: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:

  • build
  • test:integration:http for changed route behavior
  • test:integration:modules for module-level behavior
  • test:unit for local utility or service logic
  • dev:codegen or equivalent codegen verification when generated types changed

If a block was installed, also verify the files landed in the expected src/* locations.