Building blocks for digital commerce
A production-ready monorepo starter for direct-to-consumer ecommerce stores powered by Medusa and Next.js. Includes a fully featured storefront with product browsing, cart, checkout, customer accounts, and order management.
- All of Medusa's commerce features
- Multi-region support with automatic country detection
- Product catalog with variant selection
- Cart with promotion codes
- Multi-step checkout with shipping and payment
- Customer accounts with order history and address management
- Order transfer between accounts
The fastest way to get started is deploying with Medusa Cloud:
- Create a Medusa Cloud account
- Deploy this starter directly from your dashboard
Prerequisites:
- Node.js v22.22+
- PostgreSQL v15+
- pnpm v10+
- Clone the repository and install dependencies:
git clone https://github.com/medusajs/dtc-starter.git
cd dtc-starter
pnpm install- Set up environment variables for the backend:
cp apps/backend/.env.template apps/backend/.env- Set the database URL in
apps/backend/.env:
# Replace with actual database URL, make sure the database exists.
DATABASE_URL=postgres://postgres:@localhost:5432/medusa-dtc-starter- Run migrations (this also seeds initial store data):
cd apps/backend
pnpm medusa db:migrate- Add admin user:
cd apps/backend
pnpm medusa user -e admin@test.com -p supersecret- Start Medusa backend:
cd apps/backend
pnpm dev-
Open the admin dashboard at
localhost:9000/appand log in. Retrieve your publishable API key at Settings > Publishable API key. -
Set up environment variables for the storefront:
cp apps/storefront/.env.template apps/storefront/.env.local- Update
apps/storefront/.env.localwith your Medusa publishable API key:
NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_6c3...- Start the storefront:
cd apps/storefront
pnpm devThe storefront runs on http://localhost:8000.
You can also start both the backend and storefront from the root:
pnpm devapps/
├── backend/ # Medusa application: API routes, workflows, modules, admin extensions
└── storefront/ # Next.js storefront (optional)
This repo is set up for AI coding agents such as Claude Code, Cursor, and Codex:
AGENTS.mdholds the project's commands, conventions, and off-limits paths.CLAUDE.mdpoints to it.- Installed
@medusajs/*packages ship their ownAGENTS.mdinnode_modules, documenting the API of the exact version you have installed. - Install the Medusa agent skills and MCP server for documentation-backed answers:
claude mcp add --transport http medusa https://docs.medusajs.com/mcp- If you deploy on Medusa Cloud, add the Medusa Cloud MCP server so your agent can inspect deployments, build and runtime logs, environment variables, and your store's data. It authenticates with your Medusa Cloud account:
claude mcp add --transport http medusa-cloud https://cloud.medusajs.com/mcpThe storefront is configured via environment variables in apps/storefront/.env.local:
| Variable | Description | Default |
|---|---|---|
NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY |
Publishable API key from your Medusa backend | — |
NEXT_PUBLIC_MEDUSA_BACKEND_URL |
URL of your Medusa backend | http://localhost:9000 |
NEXT_PUBLIC_DEFAULT_REGION |
Default region country code | dk |
NEXT_PUBLIC_BASE_URL |
Base URL of the storefront | https://localhost:8000 |
NEXT_PUBLIC_STRIPE_KEY |
Stripe publishable key (optional) | — |
NEXT_PUBLIC_ADYEN_CLIENT_KEY |
Adyen client key (optional), when the Adyen payment provider is registered in the backend | — |
NEXT_PUBLIC_ADYEN_ENVIRONMENT |
Adyen environment, test or live (optional) |
test |