Quickstart

Get a Medusa application up and running in under 5 minutes with create-medusa-app.

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:

   npm

   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

   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

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:

Development

# 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 failed

Make sure PostgreSQL is running and your DATABASE_URL in .env is correct:

psql -U postgres -h localhost -p 5432

Port 9000 already in use

Change 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 mismatch

Medusa 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:

Option	Description	Default
--seed	Seed database with demo data	false
--skip-db	Skip database setup and migrations	false
--db-url <url>	Use existing database at this URL	-
--no-migrations	Skip running migrations	false
--no-browser	Don’t open browser after setup	false
--use-npm	Force npm as package manager	-
--use-yarn	Force yarn as package manager	-
--use-pnpm	Force pnpm as package manager	-
--directory-path <path>	Install in specific directory	Current directory
--repo-url <url>	Use custom repository template	Official template
--verbose	Show all logs for debugging	false

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:

• Check the installation guide for detailed setup instructions
• Ask in Discord
• Search GitHub Discussions
• Review GitHub Issues