Skip to main content
Skip to main content

Install Medusa with create-medusa-app

Medusa is a toolkit for developers to create digital commerce applications. In its simplest form, Medusa is a Node.js backend with the core API, plugins, and modules installed through npm.

create-medusa-app is a command that facilitates creating a Medusa ecosystem. It installs the Medusa backend and admin dashboard, along with the necessary configurations to run the backend.


Before you can install and use Medusa, you need the following tools installed on your machine:

Step 1: Run create-medusa-app

In your terminal, run the following command:

npx create-medusa-app@latest
Command Options
Example: Connect to a Vercel PostgreSQL Database
Example: Connect to a Supabase Database

Step 2: Specify Project Name

You’ll first be asked to enter the name of your project, which is used to create the directory holding your Medusa backend. You can use the default my-medusa-store or enter another project name.

Step 3: Enter an admin email

You'll then be prompted to enter an admin email for your admin user. You'll be using this admin email later to login to your admin dashboard. You can use the default or enter any other email.

(Optional) Step 4: Install Next.js Starter Storefront

If you didn't pass the --with-nextjs-starter option, you'll be asked if you want to install the Next.js starter storefront along with the Medusa backend. This will install the storefront under the <PROJECT_NAME>-storefront directory, where <PROJECT_NAME> is the name of the project you specified in step 2.

If you want to install the storefront, type y and press enter. If not, you can use the default value N and just press enter.


You can always install the storefront at a later point. Medusa is a headless backend, so it operates without a storefront by default. You can connect any storefront to it. The Next.js Starter storefront is a good option to use, but you can also build your own storefront later on.

(Optional) Step 5: Specify PostgreSQL credentials


This doesn't apply if you supplied the --db-url option. In that case, the command will fail if it can't connect to the supplied connection URL.

By default, this command will try to use the default PostgreSQL credentials to connect to your PostgreSQL server. If they don't work, you'll be prompted to enter your PostgreSQL database and password. If they work, you can move ahead to the next step.

These credentials will be used to create a database during this setup and configure your Medusa backend to connect to that database.

After following the above steps, the project setup will start which includes:

  1. Creating the project directory. The directory name will be the project name you entered in step 1.
  2. Creating the project database if --db-url and --skip-db options are not passed.
  3. Installing dependencies in your project directory.
  4. Building project
  5. Running migrations to migrate the Medusa schema into your project database unless --skip-db or --no-migrations are passed.
  6. Creating the admin user unless --skip-db or --no-migrations are passed.
  7. Seeding the database with demo data unless --skip-db or --no-migrations are passed.

Step 6: Log into admin dashboard

Once the project is prepared, the Medusa backend will start and the admin dashboard will be opened in your default browser. You'll then be asked to enter a password for the admin email you entered earlier, as well as other account information.

Once you're logged in, you can start using Medusa! Try following the setup guide to create your first product and order.

Did you set up Medusa successfully?

Next Steps: Start your Development

Based on what you're building, you can find a development path for you in the Recipes page.


Errors when using VSCode or GitHub Codespaces
Can't connect to database with --db-url option
Can't Connect to PostgreSQL Docker Container
EAGAIN error
TypeError: cmd is not a function
Error: connect ECONNREFUSED ::1:5432
Invalid Token Error after Using --no-browser option
AwilixResolutionError: Could Not Resolve X
Other Errors
Was this section helpful?