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 optional storefront.
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 allows you to optionally install a Medusa storefront.
If you only want to set up a Medusa backend, follow this quickstart guide instead.
Prerequisites
Before you can install and use Medusa, you need the following tools installed on your machine:
How to Create a Medusa Project
A Medusa project is composed of the backend and the storefront.
In your terminal, run the following command:
Step 1: Specify Project Directory Name
You’ll then be asked to enter the name of the directory you want the project to be installed in. You can either leave the default value my-medusa-store or enter a new name.
Step 2: Choose Medusa Backend Starter
Next, you’ll be asked to choose the Medusa backend starter. The Medusa Backend is created from a starter template. By default, it is created from the medusa-starter-default template.
You can either pick the default Medusa backend starter, the Contentful starter or enter a starter URL by choosing Other:
? Which Medusa starter would you like to install? …
❯ medusa-starter-default
medusa-starter-contentful
Other
The backend will be installed under the backend directory under the project directory.
Step 3: Choose Storefront Starter
After choosing the Medusa starter, you’ll be asked to choose the storefront starter. You can choose one of the starters in the list included or choose None to skip installing a storefront:
? Which storefront starter would you like to install?
❯ Next.js Starter
medusa.express (Next.js)
None
If you choose an option other than None, a storefront will be installed under the storefront directory.
Learn more about the Next.js starter storefront.
Step 4: Wait for Dependency Installation
After choosing the above starters, the installation of each component will begin along with its dependencies. Once the installation is done, you’ll see instructions related to how to start each component.
Your project is ready. The available commands are:
Medusa API
cd my-medusa-store/backend
yarn start
Storefront
cd my-medusa-store/storefront
yarn dev
The commands will differ based on your choices in previous prompts.
Step 5: Configuring your Backend Database
Before you can start your backend, you must configure your PostgreSQL database and run migrations.
Make sure your PostgreSQL service is running.
To configure your backend database, change to the backend directory under your project directory and edit the .env file to include the following:
Where <YOUR_DATABASE_URL> is the connection URL to your PostgreSQL database. For example, postgres://localhost/medusa-store. You can learn about its format and other configurations here.
Make sure to create your PostgreSQL database that you refer to in the connection URL before proceeding further. For example, if you use postgres://localhost/medusa-store make sure to create a medusa-store database.
Then, run the following command to migrate the Medusa schema to your database:
You can optionally seed your database with demo data by running the following command:
Step 6: Run the Medusa backend
While in your backend directory, run the following command to start your Medusa backend:
This will start your backend on localhost:9000. While your backend is running, you can also go to the storefront directory of your project and start the storefront. If you're using the Medusa Next.js storefront the following command starts it:
If you open your storefront now in your browser on localhost:8000, everything should be working as expected. If you're not seeing any products, you can run the seed command as instructed earlier or install the Medusa admin plugin to start adding products.
Troubleshooting
TypeError: cmd is not a function
This error typically occurs when you set up a Medusa project with create-medusa-app and try to run the Medusa backend.
To resolve this issue, make sure you change into the backend directory of the Medusa project you created before trying to start the Medusa backend:
Error: connect ECONNREFUSED ::1:5432
When you start your Medusa backend you may run into the following error:
This error occurs because the backend couldn't connect to the PostgreSQL database. The issue could be one of the following:
- PostgreSQL server isn't running. Make sure it's always running while the Medusa backend is running.
- 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
postgresql://[user[:password]@][host][:port][/dbname][?paramspec]. Make sure that the connection URL format is correct, and the credentials passed in the URL are correct.
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_modules directory, then run the following command in the root directory of the Medusa backend to re-install the dependencies:
Other Errors
If you ran into another error, 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.
Project Directory Structure
Inside the root project directory which was specified at the beginning of the installation process you’ll find the following directory structure:
/my-medusa-store
/backend // Medusa backend
/storefront // Medusa storefront starter