> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/medusajs/medusa/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Node.js 20 or higher">
    Medusa requires Node.js version 20 or higher. Check your version:

    ```bash theme={null}
    node -v
    ```

    If needed, download from [nodejs.org](https://nodejs.org)
  </Step>

  <Step title="PostgreSQL 13 or higher">
    Medusa uses PostgreSQL as its database. You can:

    * Install locally from [postgresql.org](https://www.postgresql.org/download/)
    * Use a hosted service like [Neon](https://neon.tech), [Supabase](https://supabase.com), or [Railway](https://railway.app)
    * Run via Docker: `docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres:13`
  </Step>
</Steps>

## Create Your Medusa Project

<Steps>
  <Step title="Run the create command">
    Execute the following command in your terminal:

    <CodeGroup>
      ```bash npm theme={null}
      npx create-medusa-app@latest
      ```

      ```bash yarn theme={null}
      yarn create medusa-app
      ```

      ```bash pnpm theme={null}
      pnpm create medusa-app
      ```
    </CodeGroup>

    <Note>
      The `create-medusa-app` CLI is from package version `2.13.3` which scaffolds a complete Medusa project.
    </Note>
  </Step>

  <Step title="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

    <Tip>
      Seeding with demo data is helpful for exploring Medusa's features immediately.
    </Tip>
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Start Your Application

Once installation completes:

<Steps>
  <Step title="Navigate to your project">
    ```bash theme={null}
    cd my-medusa-store
    ```
  </Step>

  <Step title="Start the development server">
    <CodeGroup>
      ```bash npm theme={null}
      npm run dev
      ```

      ```bash yarn theme={null}
      yarn dev
      ```

      ```bash pnpm theme={null}
      pnpm dev
      ```
    </CodeGroup>

    The Medusa server will start on `http://localhost:9000`
  </Step>

  <Step title="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).
  </Step>
</Steps>

## Your First API Request

Test your Medusa API with a simple product list request:

<CodeGroup>
  ```bash cURL theme={null}
  curl http://localhost:9000/store/products
  ```

  ```javascript fetch theme={null}
  fetch('http://localhost:9000/store/products')
    .then(res => res.json())
    .then(data => console.log(data))
  ```

  ```typescript Medusa JS SDK theme={null}
  import Medusa from "@medusajs/js-sdk"

  const medusa = new Medusa({
    baseUrl: "http://localhost:9000",
    debug: true,
  })

  const { products } = await medusa.store.product.list()
  console.log(products)
  ```
</CodeGroup>

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

```typescript medusa-config.ts theme={null}
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:

```bash .env theme={null}
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:

<CodeGroup>
  ```bash Development theme={null}
  # Start development server with hot reload
  npm run dev

  # Build for production
  npm run build

  # Start production server
  npm run start
  ```

  ```bash Database theme={null}
  # Run database migrations
  npm run migrations:run

  # Revert last migration
  npm run migrations:revert

  # Seed database with demo data
  npm run seed
  ```

  ```bash Admin theme={null}
  # Build admin dashboard
  npm run admin:build

  # Develop admin with hot reload
  npm run admin:dev
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Your First Product" icon="box">
    Learn how to create products using the admin dashboard or API
  </Card>

  <Card title="Build a Custom API Route" icon="code">
    Add custom endpoints to extend Medusa's functionality
  </Card>

  <Card title="Create a Workflow" icon="diagram-project">
    Compose complex business logic with the Workflow SDK
  </Card>

  <Card title="Install a Storefront" icon="store">
    Connect a Next.js storefront to your Medusa backend
  </Card>
</CardGroup>

## Common Issues

<Warning>
  **Database connection failed**

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

  ```bash theme={null}
  psql -U postgres -h localhost -p 5432
  ```
</Warning>

<Warning>
  **Port 9000 already in use**

  Change the port in your start command or kill the process using port 9000:

  ```bash theme={null}
  # macOS/Linux
  lsof -ti:9000 | xargs kill -9

  # Windows
  netstat -ano | findstr :9000
  taskkill /PID <PID> /F
  ```
</Warning>

<Warning>
  **Node version mismatch**

  Medusa requires Node.js 20+. Use [nvm](https://github.com/nvm-sh/nvm) to manage versions:

  ```bash theme={null}
  nvm install 20
  nvm use 20
  ```
</Warning>

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

```bash theme={null}
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](/installation) for detailed setup instructions
* Ask in [Discord](https://discord.gg/medusajs)
* Search [GitHub Discussions](https://github.com/medusajs/medusa/discussions)
* Review [GitHub Issues](https://github.com/medusajs/medusa/issues)