Medusa v2 Development Setup
Before writing code
Fetch live docs:
- Fetch
https://docs.medusajs.com/learn/installation for installation guide
- Web-search
site:docs.medusajs.com create medusa starter for project scaffolding
- Web-search
site:docs.medusajs.com medusa-config reference for configuration options
- Web-search
site:docs.medusajs.com project directory structure for v2 layout
Prerequisites
Required Software
| Software |
Minimum Version |
Purpose |
| Node.js |
v20+ |
Runtime |
| PostgreSQL |
— (see docs) |
Primary database |
| Redis |
v6+ |
Event bus, caching (optional for dev) |
| Git |
any |
Version control |
| npm / yarn / pnpm |
latest |
Package manager |
PostgreSQL Setup
- Create a dedicated database:
CREATE DATABASE medusa_db;
- Create a user with full privileges on that database
- Connection string format:
postgres://user:password@localhost:5432/medusa_db
Redis Setup (Optional for Development)
- Default connection:
redis://localhost:6379
- Required in production for the event bus module and caching
- In development, Medusa falls back to an in-memory event bus
Project Creation
CLI Scaffolding
npx create-medusa-app@latest my-store
# Prompts: project name, PostgreSQL credentials
# Creates: backend + Next.js storefront starter
Backend Only
npx create-medusa-app@latest my-store --skip-client
# Fetch live docs for current CLI flags
Project Directory Structure
| Directory |
Purpose |
src/modules/ |
Custom modules (DML data models, services) |
src/workflows/ |
Custom workflows and steps |
src/api/store/, src/api/admin/ |
Custom API routes + middlewares.ts |
src/subscribers/, src/jobs/ |
Event subscribers, scheduled jobs |
src/admin/widgets/, src/admin/routes/ |
Admin UI extensions |
src/links/ |
Module link definitions |
| Root |
medusa-config.ts, package.json, tsconfig.json, .env |
medusa-config.ts Key Fields
| Field |
Purpose |
projectConfig.databaseUrl |
PostgreSQL connection string |
projectConfig.redisUrl |
Redis connection (optional) |
projectConfig.http.adminCors |
Allowed origins for admin API |
projectConfig.http.storeCors |
Allowed origins for store API |
projectConfig.http.authCors |
Allowed origins for auth routes |
projectConfig.workerMode |
shared, worker, or server |
modules |
Array of module configurations |
plugins |
Array of plugin configurations |
Minimal Configuration Skeleton
// medusa-config.ts — Fetch live docs for current defineConfig shape
import { defineConfig } from "@medusajs/framework/utils"
export default defineConfig({
projectConfig: { databaseUrl: process.env.DATABASE_URL },
// Fetch live docs for modules, plugins, http config
})
Environment Variables
DATABASE_URL=postgres://user:password@localhost:5432/medusa_db
REDIS_URL=redis://localhost:6379
COOKIE_SECRET=your-cookie-secret
JWT_SECRET=your-jwt-secret
STORE_CORS=http://localhost:8000
ADMIN_CORS=http://localhost:5173
AUTH_CORS=http://localhost:5173
Never hardcode secrets -- always use .env files excluded from version control.
CLI Commands
| Command |
Purpose |
npx medusa develop |
Start dev server with hot reload |
npx medusa build |
Build for production |
npx medusa start |
Start production server |
npx medusa worker |
Start background worker process |
npx medusa db:migrate |
Run database migrations |
npx medusa db:generate |
Generate migration files |
npx medusa db:rollback |
Rollback last migration |
npx medusa user --email admin@example.com |
Create admin user |
npx medusa exec ./src/scripts/seed.ts |
Run seed script |
Worker Mode
Medusa supports three worker modes for handling background jobs:
| Mode |
Description |
shared |
Single process handles HTTP and background jobs (default) |
worker |
Dedicated process for background jobs only |
server |
HTTP-only, no background job processing |
In production, run one server instance and one or more worker instances.
Database Migrations
- Medusa v2 auto-generates migrations from DML model changes
- Run
npx medusa db:generate after modifying data models
- Run
npx medusa db:migrate to apply pending migrations
- Always commit migration files to version control
Best Practices
- Use
npx create-medusa-app@latest to scaffold -- do not set up manually
- Always run
npx medusa db:migrate after pulling changes that include new migrations
- Keep
.env in .gitignore and provide .env.template for team members
- Use
shared worker mode in development, separate server + worker in production
- Pin your Medusa version in
package.json to avoid unexpected breaking changes
- Run
npx medusa user to create the first admin user after initial setup
Common Issues
| Issue |
Resolution |
| Database connection refused |
Verify PostgreSQL is running and DATABASE_URL is correct |
| Migrations fail |
Ensure database exists and user has DDL privileges |
| Admin dashboard blank |
Check ADMIN_CORS matches the admin URL |
| Store API 403 |
Check STORE_CORS matches the storefront URL |
| Redis connection error |
Either start Redis or remove redisUrl from config |
Fetch the Medusa installation guide and CLI reference for exact commands, flags, and latest configuration options before setting up.
1---2name: medusa-setup3description: Set up a Medusa v2 development environment — CLI, PostgreSQL/Redis prerequisites, project creation, medusa-config.ts, directory structure, environment variables. Use when starting a new Medusa project.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/medusa-setup7---89# Medusa v2 Development Setup1011## Before writing code1213**Fetch live docs**:141. Fetch `https://docs.medusajs.com/learn/installation` for installation guide152. Web-search `site:docs.medusajs.com create medusa starter` for project scaffolding163. Web-search `site:docs.medusajs.com medusa-config reference` for configuration options174. Web-search `site:docs.medusajs.com project directory structure` for v2 layout1819## Prerequisites2021### Required Software2223| Software | Minimum Version | Purpose |24|----------|----------------|---------|25| Node.js | v20+ | Runtime |26| PostgreSQL | — (see docs) | Primary database |27| Redis | v6+ | Event bus, caching (optional for dev) |28| Git | any | Version control |29| npm / yarn / pnpm | latest | Package manager |3031### PostgreSQL Setup3233- Create a dedicated database: `CREATE DATABASE medusa_db;`34- Create a user with full privileges on that database35- Connection string format: `postgres://user:password@localhost:5432/medusa_db`3637### Redis Setup (Optional for Development)3839- Default connection: `redis://localhost:6379`40- Required in production for the event bus module and caching41- In development, Medusa falls back to an in-memory event bus4243## Project Creation4445### CLI Scaffolding4647```bash48npx create-medusa-app@latest my-store49# Prompts: project name, PostgreSQL credentials50# Creates: backend + Next.js storefront starter51```5253### Backend Only5455```bash56npx create-medusa-app@latest my-store --skip-client57# Fetch live docs for current CLI flags58```5960## Project Directory Structure6162| Directory | Purpose |63|-----------|---------|64| `src/modules/` | Custom modules (DML data models, services) |65| `src/workflows/` | Custom workflows and steps |66| `src/api/store/`, `src/api/admin/` | Custom API routes + `middlewares.ts` |67| `src/subscribers/`, `src/jobs/` | Event subscribers, scheduled jobs |68| `src/admin/widgets/`, `src/admin/routes/` | Admin UI extensions |69| `src/links/` | Module link definitions |70| Root | `medusa-config.ts`, `package.json`, `tsconfig.json`, `.env` |7172## medusa-config.ts Key Fields7374| Field | Purpose |75|-------|---------|76| `projectConfig.databaseUrl` | PostgreSQL connection string |77| `projectConfig.redisUrl` | Redis connection (optional) |78| `projectConfig.http.adminCors` | Allowed origins for admin API |79| `projectConfig.http.storeCors` | Allowed origins for store API |80| `projectConfig.http.authCors` | Allowed origins for auth routes |81| `projectConfig.workerMode` | `shared`, `worker`, or `server` |82| `modules` | Array of module configurations |83| `plugins` | Array of plugin configurations |8485### Minimal Configuration Skeleton8687```typescript88// medusa-config.ts — Fetch live docs for current defineConfig shape89import { defineConfig } from "@medusajs/framework/utils"9091export default defineConfig({92 projectConfig: { databaseUrl: process.env.DATABASE_URL },93 // Fetch live docs for modules, plugins, http config94})95```9697## Environment Variables9899```100DATABASE_URL=postgres://user:password@localhost:5432/medusa_db101REDIS_URL=redis://localhost:6379102COOKIE_SECRET=your-cookie-secret103JWT_SECRET=your-jwt-secret104STORE_CORS=http://localhost:8000105ADMIN_CORS=http://localhost:5173106AUTH_CORS=http://localhost:5173107```108109Never hardcode secrets -- always use `.env` files excluded from version control.110111## CLI Commands112113| Command | Purpose |114|---------|---------|115| `npx medusa develop` | Start dev server with hot reload |116| `npx medusa build` | Build for production |117| `npx medusa start` | Start production server |118| `npx medusa worker` | Start background worker process |119| `npx medusa db:migrate` | Run database migrations |120| `npx medusa db:generate` | Generate migration files |121| `npx medusa db:rollback` | Rollback last migration |122| `npx medusa user --email admin@example.com` | Create admin user |123| `npx medusa exec ./src/scripts/seed.ts` | Run seed script |124125## Worker Mode126127Medusa supports three worker modes for handling background jobs:128129| Mode | Description |130|------|-------------|131| `shared` | Single process handles HTTP and background jobs (default) |132| `worker` | Dedicated process for background jobs only |133| `server` | HTTP-only, no background job processing |134135In production, run one `server` instance and one or more `worker` instances.136137## Database Migrations138139- Medusa v2 auto-generates migrations from DML model changes140- Run `npx medusa db:generate` after modifying data models141- Run `npx medusa db:migrate` to apply pending migrations142- Always commit migration files to version control143144## Best Practices145146- Use `npx create-medusa-app@latest` to scaffold -- do not set up manually147- Always run `npx medusa db:migrate` after pulling changes that include new migrations148- Keep `.env` in `.gitignore` and provide `.env.template` for team members149- Use `shared` worker mode in development, separate `server` + `worker` in production150- Pin your Medusa version in `package.json` to avoid unexpected breaking changes151- Run `npx medusa user` to create the first admin user after initial setup152153## Common Issues154155| Issue | Resolution |156|-------|-----------|157| Database connection refused | Verify PostgreSQL is running and `DATABASE_URL` is correct |158| Migrations fail | Ensure database exists and user has DDL privileges |159| Admin dashboard blank | Check `ADMIN_CORS` matches the admin URL |160| Store API 403 | Check `STORE_CORS` matches the storefront URL |161| Redis connection error | Either start Redis or remove `redisUrl` from config |162163Fetch the Medusa installation guide and CLI reference for exact commands, flags, and latest configuration options before setting up.