medusa-store/docs/content/create-medusa-app.mdx

---
description: 'Learn how to create a composable commerce platform using Medusa. This quickstart guide will help you set up your Medusa backend and the storefront all at once.'
addHowToData: true
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Feedback from '@site/src/components/Feedback'
import Troubleshooting from '@site/src/components/Troubleshooting'
import TypeErrorSection from "./troubleshooting/create-medusa-app-errors/_typeerror.md"
import OtherErrorsSection from "./troubleshooting/create-medusa-app-errors/_other-errors.md"
import ConnectionErrorSection from './troubleshooting/database-errors/_connection-error.md'
import FreshInstallationSection from './troubleshooting/awilix-resolution-error/_fresh-installation.md'

# 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.

:::note

If you only want to set up a Medusa backend, follow [this quickstart guide](./development/backend/install.mdx) instead.

:::

---

## Prerequisites

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

- [Node.js v16+](./development/backend/prepare-environment.mdx#nodejs)
- [Git](./development/backend/prepare-environment.mdx#git)
- [PostgreSQL](./development/backend/prepare-environment.mdx#postgresql)

---

## How to Create a Medusa Project

A Medusa project is composed of the backend and the storefront.

In your terminal, run the following command:

<Tabs groupId="npxyarn" isCodeTabs={true}>
  <TabItem value="npx" label="NPX" default>

  ```bash
  npx create-medusa-app
  ```

  </TabItem>
  <TabItem value="yarn" label="Yarn">

  ```bash
  yarn create medusa-app
  ```

  </TabItem>
  <TabItem value="pnpm" label="pnpm">

  ```bash
  pnpm dlx create-medusa-app
  ```

  </TabItem>
</Tabs>

### 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`:

```bash noReport
? 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:

```bash noReport
? 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.

:::tip

Learn more about the [Next.js starter storefront](./starters/nextjs-medusa-starter.mdx).

:::

### 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.

```bash noReport
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.

:::note

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:

```bash
DATABASE_TYPE=postgres
DATABASE_URL=<YOUR_DATABASE_URL>
```

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](./development/backend/configurations.md).

:::note

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:

<Tabs groupId="npxyarn" isCodeTabs={true}>
  <TabItem value="npx" label="NPX" default>

  ```bash
  npx @medusajs/medusa-cli@latest migrations run
  ```

  </TabItem>
  <TabItem value="pnpm" label="pnpm">

  ```bash
  pnpm dlx @medusajs/medusa-cli@latest migrations run
  ```

  </TabItem>
</Tabs>

You can optionally seed your database with demo data by running the following command:

<Tabs groupId="npxyarn" isCodeTabs={true}>
  <TabItem value="npx" label="NPX" default>

  ```bash
  npx @medusajs/medusa-cli@latest seed -f ./data/seed.json
  ```

  </TabItem>
  <TabItem value="pnpm" label="pnpm">

  ```bash
  pnpm dlx @medusajs/medusa-cli@latest seed -f ./data/seed.json
  ```

  </TabItem>
</Tabs>

### Step 6: Run the Medusa backend

While in your `backend` directory, run the following command to start your Medusa backend:

<Tabs groupId="npxyarn" isCodeTabs={true}>
  <TabItem value="npx" label="NPX" default>

  ```bash
  npx @medusajs/medusa-cli@latest develop
  ```

  </TabItem>
  <TabItem value="pnpm" label="pnpm">

  ```bash
  pnpm dlx @medusajs/medusa-cli@latest develop
  ```

  </TabItem>
</Tabs>

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:

```bash npm2yarn
npm run dev
```

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](./admin/quickstart.mdx) to start adding products.

<Feedback 
   event="survey_create-medusa-app"
   question="Did you set up Medusa successfully?"
   positiveQuestion="Is there anything that should improved?"
   negativeQuestion="Please describe the issue you faced."
/>

---

## Troubleshooting

<Troubleshooting
  sections={[
    {
      title: "TypeError: cmd is not a function",
      content: <TypeErrorSection />
    },
    {
      title: "Error: connect ECONNREFUSED ::1:5432",
      content: <ConnectionErrorSection />
    },
    {
      title: 'AwilixResolutionError: Could Not Resolve X',
      content: <FreshInstallationSection />
    },
    {
      title: "Other Errors",
      content: <OtherErrorsSection />
    },
  ]}
/>

---

## 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:

```bash noReport
/my-medusa-store
  /backend // Medusa backend
  /storefront // Medusa storefront starter
```

---

## What’s Next

- [Check out Medusa's features](./modules/overview.mdx)
- [Learn about backend configurations](./development/backend/configurations.md)
- [Prepare environment for advanced development](./development/backend/prepare-environment.mdx)