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 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 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.md"
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'

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

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

:::note

`create-medusa-app` uses a beta version of the admin dashboard. If you want to use a stable Medusa setup, you can install the stable backend and the admin using the following guides:

1. [Install Medusa backend](./development/backend/install.mdx)
2. [Install admin package](./admin/quickstart.mdx)

:::

---

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

:::note

Make sure your PostgreSQL server is running before you run the command.

:::

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>

  - `--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 passowrd. 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

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.

<DocCard item={{
  type: 'link',
  href: '/recipes',
  label: 'Recipes',
  customProps: {
    icon: Icons['map'],
    description: "Find learning paths based on what you're building"
  }
}} />

---

## Troubleshooting

<Troubleshooting
  sections={[
    {
      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 />
    },
  ]}
/>