import { Table, DetailsList, Prerequisites } from "docs-ui" import PortForwardingTroubleshooting from "../troubleshooting/_sections/create-medusa-app-errors/forwarding.mdx" import DBUrlTroubleshooting from "../troubleshooting/_sections/create-medusa-app-errors/db-url-error.mdx" import EaddrinuseTroubleshooting from "../troubleshooting/_sections/other/eaddrinuse.mdx" import DockerTroubleshooting from "../troubleshooting/_sections/database-errors/docker.mdx" import EagainTroubleshooting from "../troubleshooting/_sections/create-medusa-app-errors/eagain-error.mdx" import TypeErrorTroubleshooting from "../troubleshooting/_sections/create-medusa-app-errors/typeerror.mdx" import ConnectionErrorTroubleshooting from "../troubleshooting/_sections/database-errors/connection-error.mdx" import NoBrowserTroubleshooting from "../troubleshooting/_sections/create-medusa-app-errors/no-browser-token-error.mdx" import OtherErrorsTroubleshooting from "../troubleshooting/_sections/create-medusa-app-errors/other-errors.mdx"

export const metadata = { title: create-medusa-app CLI Tool, }

{metadata.title}

The create-medusa-app CLI tool simplifies the process of creating a new Medusa project. It creates a monorepo containing your Medusa backend application and, optionally, a Next.js storefront. It also allows you to setup a Medusa plugin project.

Usage

bash

npx create-medusa-app@latest [project-name]

The command will use the package manager you run it with to create a new Medusa project in a directory named after the provided project-name.

Arguments

<Table> <Table.Header> <Table.Row> <Table.HeaderCell>Option</Table.HeaderCell> <Table.HeaderCell>Description</Table.HeaderCell> </Table.Row> </Table.Header> <Table.Body> <Table.Row> <Table.Cell>

    `project-name`

  </Table.Cell>
  <Table.Cell>
    The name of the project's directory and PostgreSQL database to be created. For example, `my-medusa-store`. If not provided, you'll be prompted to enter a project name.
  </Table.Cell>
</Table.Row>

</Table.Body>

</Table>

Command Options

<Table> <Table.Header> <Table.Row> <Table.HeaderCell>Option</Table.HeaderCell> <Table.HeaderCell>Description</Table.HeaderCell> <Table.HeaderCell>Default</Table.HeaderCell> </Table.Row> </Table.Header> <Table.Body> <Table.Row> <Table.Cell>

    `--repo-url <url>`

  </Table.Cell>
  <Table.Cell>
    The repository URL to create the project from.
  </Table.Cell>
  <Table.Cell>
  
  `https://github.com/medusajs/dtc-starter`

  </Table.Cell>
</Table.Row>
<Table.Row>
  <Table.Cell>

    `--no-browser`

  </Table.Cell>
  <Table.Cell>

    Disables opening the browser at the end of the project creation and only shows success message.

  </Table.Cell>
  <Table.Cell>
  
    `false`

  </Table.Cell>
</Table.Row>
<Table.Row>
  <Table.Cell>

    `--skip-db`

  </Table.Cell>
  <Table.Cell>

    Skips creating the database, running migrations, and seeding, and subsequently skips opening the browser. Useful if you want to set the database URL with the `--db-url` option.

  </Table.Cell>
  <Table.Cell>
  
    `false`

  </Table.Cell>
</Table.Row>
<Table.Row>
  <Table.Cell>

    `--db-url <url>`

  </Table.Cell>
  <Table.Cell>

    Skips database creation and sets the database URL to the provided URL. Throws an error if connection to the database fails. Will still run migrations and open the admin after project creation. Useful if you already have a database created, locally or remotely.

  </Table.Cell>
  <Table.Cell>
  
    \-

  </Table.Cell>
</Table.Row>
<Table.Row>
  <Table.Cell>

    `--no-migrations`

  </Table.Cell>
  <Table.Cell>

    Skips running migrations, creating admin user, and seeding. If used, it's expected that you pass the `--db-url` option with a URL of a database that has all necessary migrations. Otherwise, unexpected errors will occur. Helpful only if combined with `--db-url`.

  </Table.Cell>
  <Table.Cell>
  
    `false`

  </Table.Cell>
</Table.Row>
<Table.Row>
  <Table.Cell>

    `--directory-path <path>`

  </Table.Cell>
  <Table.Cell>

    Allows specifying the parent directory path to create the directory of the new project in.

  </Table.Cell>
  <Table.Cell>
  
    The current directory the command is running in.

  </Table.Cell>
</Table.Row>
<Table.Row>
  <Table.Cell>

    `--with-nextjs-starter`

  </Table.Cell>
  <Table.Cell>

    Installs the Next.js Starter storefront in the `apps/storefront` directory within your project monorepo. If this option is not specified, the storefront directory is removed from the project.

  </Table.Cell>
  <Table.Cell>
  
    `false`

  </Table.Cell>
</Table.Row>
<Table.Row>
  <Table.Cell>

    `--verbose`

  </Table.Cell>
  <Table.Cell>

    Shows detailed logs. Useful when you're reporting an issue with the tool.

  </Table.Cell>
  <Table.Cell>
  
    `false`

  </Table.Cell>
</Table.Row>
<Table.Row>
  <Table.Cell>

    `--plugin`

  </Table.Cell>
  <Table.Cell>

    Create a [plugin project](#create-a-medusa-plugin-project) instead of a Medusa application. This option is available starting from [Medusa v2.3.0](https://github.com/medusajs/medusa/releases/tag/v2.3.0).

  </Table.Cell>
  <Table.Cell>
  
    `false`

  </Table.Cell>
</Table.Row>
<Table.Row>
  <Table.Cell>

    `--version`

  </Table.Cell>
  <Table.Cell>

    Specify the Medusa version to install in the project. The specified version will be used for every `@medusajs/*` package in the Medusa and Next.js Starter projects.

  </Table.Cell>
  <Table.Cell>
  
    The latest version of Medusa at the time of running the command.

  </Table.Cell>
</Table.Row>
<Table.Row>
  <Table.Cell>

    `--use-npm`

  </Table.Cell>
  <Table.Cell>

    Uses `npm` as the package manager to create the project, regardless of the package manager used to run the command.

  </Table.Cell>
  <Table.Cell>
  
    The package manager used to run the command.

  </Table.Cell>
</Table.Row>
<Table.Row>
  <Table.Cell>

    `--use-yarn`

  </Table.Cell>
  <Table.Cell>

    Uses `yarn` as the package manager to create the project, regardless of the package manager used to run the command.

  </Table.Cell>
  <Table.Cell>
  
    The package manager used to run the command.

  </Table.Cell>
</Table.Row>
<Table.Row>
  <Table.Cell>

    `--use-pnpm`

  </Table.Cell>
  <Table.Cell>

    Uses `pnpm` as the package manager to create the project, regardless of the package manager used to run the command.

  </Table.Cell>
  <Table.Cell>
  
    The package manager used to run the command.

  </Table.Cell>
</Table.Row>

</Table.Body>

</Table>

Examples

Connect to a Vercel PostgreSQL Database

To use a PostgreSQL database hosted on Vercel, use the --db-url option and add to the end of your connection URL ?sslmode=require. For example:

bash

npx create-medusa-app@latest --db-url "postgres://default:<password><host-region>.postgres.vercel-storage.com:5432/verceldb?sslmode=require"

<Note>

If the database already has the necessary migrations and you don't need the command to run migrations, you can pass the --no-migrations option.

</Note>

Connect to a Supabase Database

To connect to a Supabase database, use the --db-url option with its value being the connection URL to your Supabase database. For example:

bash

npx create-medusa-app@latest --db-url "postgres://postgres.<host>:<password>@aws-0-eu-central-1.pooler.supabase.com:5432/postgres"

<Note>

If the database already has the necessary migrations and you don't need the command to run migrations, you can pass the --no-migrations option.

</Note>

Project Structure

The create-medusa-app tool creates a monorepo project with the following structure:

my-medusa-store/
├── apps/
│   ├── backend/          # Your Medusa backend application
│   │   ├── src/
│   │   ├── package.json
│   │   └── medusa-config.ts
│   └── storefront/       # Next.js storefront (if --with-nextjs-starter is used)
│       ├── src/
│       ├── package.json
│       └── next.config.js
├── package.json          # Root package.json for workspace management
└── pnpm-workspace.yaml   # Workspace configuration

Your Medusa backend will be located in the apps/backend directory, and the optional Next.js storefront in apps/storefront.

Create a Medusa Plugin Project

The create-medusa-app tool can also be used to create a Medusa Plugin Project. You can do that by passing the --plugin option:

bash

npx create-medusa-app@latest my-plugin --plugin

Learn more about how to create a plugin in this documentation.

Install a Specific Medusa Version

To install a specific version of Medusa, use the --version option. This will install the specified version for every @medusajs/* package in the Medusa and Next.js Starter projects. For example:

bash

npx create-medusa-app@latest my-medusa-store --version 2.3.0

This will create a new Medusa project with the 2.3.0 version.

Troubleshooting

<DetailsList sections={[ { title: "Errors when using VSCode or GitHub Codespaces", content: <PortForwardingTroubleshooting /> }, { title: "Can't connect to database with --db-url option", content: <DBUrlTroubleshooting /> }, { title: "Error: EADDRINUSE", content: <EaddrinuseTroubleshooting /> }, { title: "Can't Connect to PostgreSQL Docker Container", content: <DockerTroubleshooting /> }, { title: "EAGAIN Error", content: <EagainTroubleshooting /> }, { title: "TypeError: cmd is not a function", content: <TypeErrorTroubleshooting /> }, { title: "Error: connect ECONNREFUSED ::1:5432", content: <ConnectionErrorTroubleshooting /> }, { title: "Invalid Token Error After Using --no-browser option", content: <NoBrowserTroubleshooting /> }, { title: "Other Errors", content: <OtherErrorsTroubleshooting /> } ]} />