Skip to main content

Install Medusa with create-medusa-app

In this document, you’ll learn how to use create-medusa-app to set up a Medusa backend and an admin dashboard.

create-medusa-app allows you to install and setup a Medusa backend project with minimal configurations. If you're more familiar with Medusa or you need to have more control over the configurations of the Medusa backend, such as database connection details, you can either use the command's options to customize the setup, or use the backend quickstart instead.

Overview​

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.

Prerequisites​

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​

The create-medusa-app command can accept the following options:

  • --repo-url <url>: The repository URL to create the project from. By default it will be https://github.com/medusajs/medusa-starter-default.
  • --seed: A flag indicating whether the database should be seeded with demo data. By default, seeding is disabled.
  • --no-boilerplate: A flag that removes all files added for an enhanced onboarding experience (files under src/admin, src/api, etc...). This is helpful if you want to create a clean project, and is only recommended if you're familiar with Medusa.
  • --no-browser: Disables opening the browser at the end of the project creation and only shows success message.
  • --skip-db: Skips creating the database, running migrations, and seeding, and subsequently skips opening the browser. Useful if you want to set the database URL at a later point in the configurations.
  • --db-url <url>: 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.
  • --no-migrations: 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.
  • --directory-path <path>: Allows specifying the parent directory path to create the directory of the new project in.
  • --with-nextjs-starter: Installs the Next.js starter storefront under the <PROJECT_NAME>-storefront directory, where <PROJECT_NAME> is the name of the project you enter in the first question. If the <PROJECT_NAME>-storefront directory already exists, random characters are added at the end of <PROJECT_NAME>-storefront.

Example: Connect to a Vercel PostgreSQL Database​

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

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

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.

Example: Connect to a Supabase Database​

If you want to connect to a Supabase database, you must use the --db-url option with its value beign the connection URL to your Supabase database. For example:

npx create-medusa-app@latest --db-url postgresql://postgres:<password>@<host>.supabase.co:5432/postgres

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.

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 admin@medusa-test.com 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.

Troubleshooting​

Error: EADDRINUSE
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?
© 2023 Medusa, Inc. All rights reserved.