Medusa Setup

Medusa v2 Development Setup

Before writing code

Fetch live docs:

1. Fetch https://docs.medusajs.com/learn/installation for installation guide
2. Web-search site:docs.medusajs.com create medusa starter for project scaffolding
3. Web-search site:docs.medusajs.com medusa-config reference for configuration options
4. Web-search site:docs.medusajs.com project directory structure for v2 layout

Prerequisites

Required Software

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

medusa-config.ts Key Fields

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

Worker Mode

Medusa supports three worker modes for handling background jobs:

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

Fetch the Medusa installation guide and CLI reference for exact commands, flags, and latest configuration options before setting up.