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-appCopy to Clipboard allows you to install and setup a Medusa backend project with minimal configurations. If you're more familiar with Medusa and you need to have more control over the configurations of the Medusa backend, please 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-appCopy to Clipboard 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:

How to Create a Medusa Project​

create-medusa-appCopy to Clipboard uses a beta version of the Medusa backend and admin. If you want to use a stable Medusa setup, consider passing the --stableCopy to Clipboard option to the command. However, when using this option, you'll have to install the Medusa admin manually.

In your terminal, run the following command:

npx create-medusa-app@latest
Report Incorrect CodeCopy to Clipboard
Available Options
  • --stableCopy to Clipboard: A flag that allows you to opt-out of the beta Medusa backend project. When using this option, the Medusa admin won't be installed.
  • --repo-url <url>Copy to Clipboard: The repository URL to create the project from. By default it will be https://github.com/medusajs/medusa-starter-defaultCopy to Clipboard.
  • --seedCopy to Clipboard: A flag indicating whether the database should be seeded with demo data. By default, seeding is disabled.
  • --no-boilerplateCopy to Clipboard: A flag that removes all files added for an enhanced onboarding experience (files under src/adminCopy to Clipboard, src/apiCopy to Clipboard, etc...). This is helpful if you want to create a clean project, and is only recommended if you're familiar with Medusa.

Step 1: 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-storeCopy to Clipboard or enter another project name.

(Optional) Step 2: Specify PostgreSQL credentials​

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.

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.comCopy to Clipboard or enter any other email.

Step 4: Wait for Project Setup​

After 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.
  3. Installing dependencies in your project directory.
  4. Building project and running migrations to migrate the Medusa schema into your project database.
  5. Create the admin user.
  6. Seeding the database with demo data.

Step 5: Log into admin dashboard​

If you passed the --stableCopy to Clipboard option, the localhost:9000/store/productsCopy to Clipboard endpoint will open in your browser instead.

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

When you run your backend you may run to an error similar to the following:

code: 'EADDRINUSE',
errno: -48,
syscall: 'Listen',
address: '::',
port: 9000
Report Incorrect CodeCopy to Clipboard

This means that there's another process running at port 9000Copy to Clipboard. You need to either:

  • Change the default port used by the Medusa backend. You can do that by setting the PORTCopy to Clipboard environment variable to a new port. When you do this, make sure to change the port used in other apps that interact with your Medusa backend, such as in your admin or storefront.
  • Terminate other processes running on port 9000Copy to Clipboard.
EAGAIN error

When using the create-medusa-appCopy to Clipboard npx command, you might run into an NPM EAGAINCopy to Clipboard error. This error can randomly occur due to conflicting processes.

The easiest solution is to start the command over. Alternatively, if your setup crossed the "create database" point, you can manually perform the following steps in the directory of your created project. You can skip any steps that you're sure have been performed by create-medusa-appCopy to Clipboard:

1. Install dependencies:

yarn install
Report Incorrect CodeCopy to Clipboard

2. Build project:

yarn build
Report Incorrect CodeCopy to Clipboard

3. Run migrations:

npx @medusajs/medusa-cli migrations run
Report Incorrect CodeCopy to Clipboard

4. Create an admin user:

npx @medusajs/medusa-cli user -e user@test.com -p supersecret
Report Incorrect CodeCopy to Clipboard

5. Optionally seed the database:

npx @medusajs/medusa-cli seed -f ./data/seed.json
Report Incorrect CodeCopy to Clipboard

6. Start project:

npx @medusajs/medusa-cli develop
Report Incorrect CodeCopy to Clipboard
TypeError: cmd is not a function

This error typically occurs when you set up a Medusa project with create-medusa-appCopy to Clipboard and try to run the Medusa backend.

To resolve this issue, make sure you change into the backendCopy to Clipboard directory of the Medusa project you created before trying to start the Medusa backend:

cd backend
npx @medusajs/medusa-cli develop
Report Incorrect CodeCopy to Clipboard
Error: connect ECONNREFUSED ::1:5432

When you start your Medusa backend you may run into the following error:

Error: connect ECONNREFUSED ::1:5432
Report Incorrect CodeCopy to Clipboard

This error occurs because the backend couldn't connect to the PostgreSQL database. The issue could be one of the following:

  1. PostgreSQL server isn't running. Make sure it's always running while the Medusa backend is running.
  2. The connection URL to your PostgreSQL database is incorrect. This could be because of incorrect credentials, port number, or connection URL format. The format should be postgres://[user][:password]@[host][:port]/[dbname]Copy to Clipboard. Make sure that the connection URL format is correct, and the credentials passed in the URL are correct. You can learn more about formatting the connection URL here
AwilixResolutionError: Could Not Resolve X

If you get the error on a fresh installation of the Medusa backend, or you haven't made any customizations that would cause this error, try to remove the node_modulesCopy to Clipboard directory, then run the following command in the root directory of the Medusa backend to re-install the dependencies:

yarn install
Report Incorrect CodeCopy to Clipboard
Other Errors

As a last resort to resolve your issue, please try to clear your npxCopy to Clipboard cache, as it could hold a cached version of create-medusa-appCopy to Clipboard with errors.

Run the following command:

rm -rf "$(npm config get cache)/_npx"
Report Incorrect CodeCopy to Clipboard

Try running the create-medusa-appCopy to Clipboard command again.

If your issue persists, please try to search through our GitHub issues to see if there's a solution for your issue. If not, please create an issue on GitHub and our team will help you resolve it soon.

Was this page helpful?
© 2023 Medusa, Inc. All rights reserved.