Medusa logo

Medusa DTC Starter

Documentation | Website

Building blocks for digital commerce

Medusa is released under the MIT license. Current CircleCI build status. PRs welcome! Product Hunt Discord Chat Follow @medusajs

# Medusa DTC Starter 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. ## Features - All of [Medusa's commerce features](https://docs.medusajs.com/resources/commerce-modules) - 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 ## Getting Started ### Deploy with Medusa Cloud The fastest way to get started is deploying with [Medusa Cloud](https://cloud.medusajs.com): 1. [Create a Medusa Cloud account](https://cloud.medusajs.com) 2. Deploy this starter directly from your dashboard ### Local Installation > **Prerequisites:** > > - [Node.js](https://nodejs.org/) v22.22+ > - [PostgreSQL](https://www.postgresql.org/) v15+ > - [pnpm](https://pnpm.io/) v10+ 1. Clone the repository and install dependencies: ```bash git clone https://github.com/medusajs/dtc-starter.git cd dtc-starter pnpm install ``` 2. Set up environment variables for the backend: ```bash cp apps/backend/.env.template apps/backend/.env ``` 3. Set the database URL in `apps/backend/.env`: ```bash # Replace with actual database URL, make sure the database exists. DATABASE_URL=postgres://postgres:@localhost:5432/medusa-dtc-starter ``` 4. Run migrations (this also seeds initial store data): ```bash cd apps/backend pnpm medusa db:migrate ``` 5. Add admin user: ```bash cd apps/backend pnpm medusa user -e admin@test.com -p supersecret ``` 6. Start Medusa backend: ```bash cd apps/backend pnpm dev ``` 7. Open the admin dashboard at `localhost:9000/app` and log in. Retrieve your publishable API key at Settings > Publishable API key. 8. Set up environment variables for the storefront: ```bash cp apps/storefront/.env.template apps/storefront/.env.local ``` 9. Update `apps/storefront/.env.local` with your Medusa publishable API key: ```bash NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_6c3... ``` 10. Start the storefront: ```bash cd apps/storefront pnpm dev ``` The storefront runs on `http://localhost:8000`. You can also start both the backend and storefront from the root: ```bash pnpm dev ``` ## Project Structure ```text apps/ ├── backend/ # Medusa application: API routes, workflows, modules, admin extensions └── storefront/ # Next.js storefront (optional) ``` ## Building with AI Agents This repo is set up for AI coding agents such as Claude Code, Cursor, and Codex: - [`AGENTS.md`](./AGENTS.md) holds the project's commands, conventions, and off-limits paths. `CLAUDE.md` points to it. - Installed `@medusajs/*` packages ship their own `AGENTS.md` in `node_modules`, documenting the API of the exact version you have installed. - Install the [Medusa agent skills](https://docs.medusajs.com/learn/introduction/build-with-llms-ai/agentic-skills) and [MCP server](https://docs.medusajs.com/learn/introduction/build-with-llms-ai/mcp-server) for documentation-backed answers: ```bash claude mcp add --transport http medusa https://docs.medusajs.com/mcp ``` - If you deploy on [Medusa Cloud](https://cloud.medusajs.com), 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: ```bash claude mcp add --transport http medusa-cloud https://cloud.medusajs.com/mcp ``` ## Configuration The 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` | ## Resources - [Medusa Documentation](https://docs.medusajs.com) - [Medusa Cloud](https://cloud.medusajs.com) - [Build with AI agents](https://docs.medusajs.com/learn/introduction/build-with-llms-ai) - [Medusa docs for LLMs (`llms.txt`)](https://docs.medusajs.com/llms.txt)