# AGENTS.md ## Overview Medusa DTC Starter — a Turborepo workspace monorepo containing a Medusa backend (`@medusajs/medusa` 2.x, Node 22.22+, PostgreSQL 15+) and an optional Next.js storefront. ## Before You Start 1. **Detect the package manager** (see [Package Manager](#package-manager)). Never assume pnpm. 2. **Check whether `apps/storefront/` exists.** If not, the project is backend-only. 3. **Load the matching Medusa skill** if available (see [Medusa Skills & MCP Server](#medusa-skills--mcp-server)). 4. **Read the `AGENTS.md` of the `@medusajs/*` package you're about to use** (see [Medusa Package Docs](#medusa-package-docs-node_modules)). It describes the installed version, which beats memory. ## Where to Look | Task | Location | Read first | | --- | --- | --- | | Store/admin API route | `apps/backend/src/api/{store,admin}//route.ts` | `@medusajs/framework` (`/http`), `@medusajs/medusa` | | Middleware, auth, body validation | `apps/backend/src/api/middlewares.ts` | `@medusajs/framework` (`/http`) | | Business logic | `apps/backend/src/workflows/` | `@medusajs/framework` (`/workflows-sdk`), `@medusajs/core-flows` | | Reuse a built-in flow (create cart, product, order...) | import from `@medusajs/medusa/core-flows` | `@medusajs/core-flows` | | Custom data model + service | `apps/backend/src/modules//` | `@medusajs/framework` (`/utils`) | | Extend a commerce module (product, cart, order...) | `apps/backend/src/links/` | `@medusajs/` (e.g. `@medusajs/product`) | | Events / cron | `apps/backend/src/subscribers/`, `apps/backend/src/jobs/` | `@medusajs/framework` | | Product search index | `apps/backend/src/search/` | `@medusajs/framework` (`/types` `SearchTypes`) | | One-off scripts | `apps/backend/src/scripts/` (run with `medusa exec`) | `@medusajs/cli` | | Admin widgets / pages | `apps/backend/src/admin/` | `@medusajs/admin-sdk`, `@medusajs/ui`, `@medusajs/icons` | | Module/plugin config | `apps/backend/medusa-config.ts` | `@medusajs/framework` | | Tests | `apps/backend/integration-tests/`, `src/**/__tests__/` | `@medusajs/test-utils` | | Storefront API calls | `apps/storefront/src/lib/data/` | `@medusajs/js-sdk`, `@medusajs/types` (`HttpTypes`) | | Storefront UI | `apps/storefront/src/modules//`, routes in `src/app/` | `@medusajs/ui` | | Lint failure | the flagged file | `@medusajs/eslint-plugin` | ## Directory Structure ```text . ├── apps/ │ ├── backend/ # Medusa application (@dtc/backend) │ │ ├── medusa-config.ts # Medusa config: DB URL, CORS, secrets, modules │ │ ├── integration-tests/ # setup.js (Jest setupFiles) and http/*.spec.ts suites │ │ └── src/ │ │ ├── admin/ # Admin dashboard extensions (widgets/, routes/, i18n/) │ │ ├── api/ # API routes: api/store/*, api/admin/* (file-based) + middlewares.ts │ │ ├── jobs/ # Scheduled jobs │ │ ├── links/ # Module links between modules │ │ ├── migration-scripts/# Data migrations run by db:migrate (e.g. initial-data-seed.ts) │ │ ├── modules/ # Custom modules (service + models + migrations) │ │ ├── scripts/ # medusa exec scripts (e.g. seed-demo-products.ts) │ │ ├── search/ # Product search index definition │ │ ├── subscribers/ # Event subscribers │ │ └── workflows/ # Workflows and workflow steps │ └── storefront/ # OPTIONAL Next.js storefront (@dtc/storefront) │ └── src/ │ ├── app/ # Next.js App Router routes │ ├── lib/data/ # Server-side Medusa API calls (js-sdk) │ └── modules/ # Feature UI: cart, checkout, products, account, order... ├── eslint.config.ts # Root ESLint: @medusajs/eslint-plugin recommended └── turbo.json # Task graph: build, dev, start, lint, test, seed ``` **`apps/storefront` is optional and may not exist.** It is skipped when the user chooses not to install it. Before running any storefront command, referencing storefront files, or assuming a full-stack change is possible, check that `apps/storefront/` exists. If it doesn't, the project is backend-only — do not scaffold it or suggest it was deleted by mistake. Each app can have its own nested `AGENTS.md`; agents read the nearest one in the directory tree, so put app-specific context there rather than expanding this file. ## Package Manager **The package manager is chosen at install time and is not fixed.** Detect it before running anything, in this order: 1. The `packageManager` field in the root `package.json` (e.g. `"pnpm@10.11.1"`) — authoritative when present. 2. The lockfile at the repo root: `pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `package-lock.json` → npm. ```bash node -p "require('./package.json').packageManager ?? 'unset'" ls pnpm-lock.yaml yarn.lock package-lock.json bun.lock bun.lockb 2>/dev/null ``` Use that manager for every command and never introduce a second lockfile. Below, `` means the detected manager. The ` run