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
If you run into any errors during the installation, please refer to this troubleshooting guide for a potential help.
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