Skip to main content

​
Quickstart

Get a complete Medusa backend and admin dashboard running in under 5 minutes using create-medusa-app.

​
Prerequisites

1

Node.js 20 or higher

Medusa requires Node.js version 20 or higher. Check your version:
node -v
If needed, download from nodejs.org
2

PostgreSQL 13 or higher

Medusa uses PostgreSQL as its database. You can:
  • Install locally from postgresql.org
  • Use a hosted service like Neon, Supabase, or Railway
  • Run via Docker: docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres:13

​
Create Your Medusa Project

1

Run the create command

Execute the following command in your terminal:
npx create-medusa-app@latest
The create-medusa-app CLI is from package version 2.13.3 which scaffolds a complete Medusa project.
2

Answer the prompts

The CLI will ask you several questions:Project name: Enter a name for your project (e.g., my-medusa-store)Database setup: Choose how to configure your PostgreSQL database:
  • Enter database URL (recommended if you have PostgreSQL running)
  • Skip database setup (configure manually later)
Package manager: Select your preferred package manager (npm, yarn, or pnpm)Seed demo data: Choose whether to populate your store with sample products
Seeding with demo data is helpful for exploring Medusa’s features immediately.
3

Wait for installation

The CLI will:
  1. Create your project directory
  2. Install all dependencies
  3. Set up the database connection
  4. Run database migrations
  5. Seed demo data (if selected)
  6. Create an admin user
This typically takes 2-3 minutes depending on your internet connection.

​
Start Your Application

Once installation completes:
1

Navigate to your project

cd my-medusa-store
2

Start the development server

npm run dev
The Medusa server will start on http://localhost:9000
3

Access the admin dashboard

Open your browser and navigate to:
http://localhost:9000/app
Log in with the admin credentials created during setup (check your terminal output for the email and password).

​
Your First API Request

Test your Medusa API with a simple product list request: 
curl http://localhost:9000/store/products

​
Project Structure

Your new Medusa project contains: 
my-medusa-store/
├── src/
│   ├── api/              # Custom API routes
│   ├── workflows/        # Custom workflows
│   ├── subscribers/      # Event subscribers
│   └── modules/          # Custom modules
├── medusa-config.ts      # Medusa configuration
├── package.json          # Dependencies and scripts
└── .env                  # Environment variables

​
Key Files

medusa-config.ts - Main configuration file:
medusa-config.ts
import { defineConfig, Modules } from "@medusajs/framework/utils"

export default defineConfig({
  projectConfig: {
    databaseUrl: process.env.DATABASE_URL,
    http: {
      storeCors: process.env.STORE_CORS,
      adminCors: process.env.ADMIN_CORS,
      jwtSecret: process.env.JWT_SECRET,
      cookieSecret: process.env.COOKIE_SECRET,
    },
  },
  admin: {
    path: "/app",
  },
  modules: {
    [Modules.FILE]: {
      resolve: "@medusajs/file",
    },
    [Modules.NOTIFICATION]: {
      resolve: "@medusajs/notification",
    },
  },
})
.env - Environment variables:
.env
DATABASE_URL=postgres://user:password@localhost:5432/medusa-store
JWT_SECRET=your-secret-key
COOKIE_SECRET=your-cookie-secret
STORE_CORS=http://localhost:8000
ADMIN_CORS=http://localhost:9000

​
Available Scripts

Your Medusa project includes these npm scripts: 
# Start development server with hot reload
npm run dev

# Build for production
npm run build

# Start production server
npm run start

​
Next Steps

Create Your First Product

Learn how to create products using the admin dashboard or API

Build a Custom API Route

Add custom endpoints to extend Medusa’s functionality

Create a Workflow

Compose complex business logic with the Workflow SDK

Install a Storefront

Connect a Next.js storefront to your Medusa backend

​
Common Issues

Database connection failedMake sure PostgreSQL is running and your DATABASE_URL in .env is correct:
psql -U postgres -h localhost -p 5432
Port 9000 already in useChange the port in your start command or kill the process using port 9000:
# macOS/Linux
lsof -ti:9000 | xargs kill -9

# Windows
netstat -ano | findstr :9000
taskkill /PID <PID> /F
Node version mismatchMedusa requires Node.js 20+. Use nvm to manage versions:
nvm install 20
nvm use 20

​
CLI Options Reference

The create-medusa-app command supports these options:
OptionDescriptionDefault
--seedSeed database with demo datafalse
--skip-dbSkip database setup and migrationsfalse
--db-url <url>Use existing database at this URL-
--no-migrationsSkip running migrationsfalse
--no-browserDon’t open browser after setupfalse
--use-npmForce npm as package manager-
--use-yarnForce yarn as package manager-
--use-pnpmForce pnpm as package manager-
--directory-path <path>Install in specific directoryCurrent directory
--repo-url <url>Use custom repository templateOfficial template
--verboseShow all logs for debuggingfalse

​
Example with Options

npx create-medusa-app@latest my-store \
  --seed \
  --db-url postgres://localhost:5432/medusa \
  --use-pnpm \
  --verbose

​
Get Help

If you’re stuck:

Build docs developers (and LLMs) love

Get started for freeTalk to us