From medusa-commerce
Sets up Medusa v2 development environment: CLI scaffolding with create-medusa-app, PostgreSQL/Redis prerequisites, medusa-config.ts configuration, directory structure, environment variables. Use when starting a new Medusa project.
npx claudepluginhub orcaqubits/agentic-commerce-skills-plugins --plugin medusa-commerceThis skill is limited to using the following tools:
**Fetch live docs**:
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
Fetch live docs:
https://docs.medusajs.com/learn/installation for installation guidesite:docs.medusajs.com create medusa starter for project scaffoldingsite:docs.medusajs.com medusa-config reference for configuration optionssite:docs.medusajs.com project directory structure for v2 layout| 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 |
CREATE DATABASE medusa_db;postgres://user:password@localhost:5432/medusa_dbredis://localhost:6379npx create-medusa-app@latest my-store
# Prompts: project name, PostgreSQL credentials
# Creates: backend + Next.js storefront starter
npx create-medusa-app@latest my-store --skip-client
# Fetch live docs for current CLI flags
| 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 |
| 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 |
// 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
})
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.
| 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 |
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.
npx medusa db:generate after modifying data modelsnpx medusa db:migrate to apply pending migrationsnpx create-medusa-app@latest to scaffold -- do not set up manuallynpx medusa db:migrate after pulling changes that include new migrations.env in .gitignore and provide .env.template for team membersshared worker mode in development, separate server + worker in productionpackage.json to avoid unexpected breaking changesnpx medusa user to create the first admin user after initial setup| 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.