medusa-store/www/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 admin dashboard.'
addHowToData: true
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Feedback from '@site/src/components/Feedback';
import DocCard from '@theme/DocCard';
import DocCardList from '@theme/DocCardList';
import Icons from '@theme/Icon';
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.mdx"
import EagainError from "./troubleshooting/create-medusa-app-errors/_eagain-error.md"
import ConnectionErrorSection from './troubleshooting/database-errors/_connection-error.md'
import FreshInstallationSection from './troubleshooting/awilix-resolution-error/_fresh-installation.md'
import EaddrinuseSection from './troubleshooting/eaddrinuse.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 admin dashboard.

:::tip

`create-medusa-app` 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](./development/backend/install.mdx).

:::

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

- [Node.js v16+](./development/backend/prepare-environment.mdx#nodejs)
- [Git](./development/backend/prepare-environment.mdx#git)
- [PostgreSQL](./development/backend/prepare-environment.mdx#postgresql). The PostgreSQL server should also be running during your installation process.

---

## How to Create a Medusa Project

:::note

`create-medusa-app` uses a beta version of the Medusa backend and admin. If you want to use a stable Medusa setup, consider passing the `--stable` option to the command. However, when using this option, you'll have to [install the Medusa admin](./admin/quickstart.mdx) manually.

:::

In your terminal, run the following command:

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

  ```bash
  npx create-medusa-app@latest
  ```

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

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

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

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

  </TabItem>
</Tabs>

<details>
  <summary>Available Options</summary>

  - `--stable`: 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>`: 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.

</details>

### 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-store` 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.com` 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

:::note

If you passed the `--stable` option, the `localhost:9000/store/products` 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.

<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."
/>

---

## Next Steps: Start your Development

Based on what you're building, you can find a development path for you in the Recipes page.

<DocCardList colSize={4} items={[
  {
    type: 'link',
    href: '/recipes',
    label: 'Recipes',
    customProps: {
      icon: Icons['map'],
      description: "Find learning paths based on what you're building"
    }
  },
  {
    type: 'link',
    href: '/development/overview',
    label: 'Medusa Backend Basics',
    customProps: {
      icon: Icons['server-stack-solid'],
      description: 'Learn all the basics of developing with the Medusa backend.'
    }
  },
  {
    type: 'link',
    href: '/modules/overview',
    label: 'Commerce Modules',
    customProps: {
      icon: Icons['puzzle-solid'],
      description: 'Learn about the available commerce modules and features in the Medusa backend.'
    }
  },
]} />

---

## Troubleshooting

<Troubleshooting
  sections={[
    {
      title: 'Error: EADDRINUSE',
      content: <EaddrinuseSection />
    },
    {
      title: "EAGAIN error",
      content: <EagainError />
    },
    {
      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 />
    },
  ]}
/>