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

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

---

## 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`.
  - `--no-boilerplate`: A flag that removes all files added for an enhanced onboarding experience (files under `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: 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. Seed the database

### Step 4: Test it Out

Once the installation is finished, the Medusa backend will be started automatically. You can test it out by either opening the URL `localhost:9000/store/products` in your browser or using cURL:

```bash
cURL localhost:9000/store/products
```

This endpoint returns an array of available products in your Medusa backend.

<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={6} items={[
  {
    type: 'link',
    href: '/modules/overview',
    label: 'Commerce Modules',
    customProps: {
      icon: Icons['puzzle-solid'],
      description: "Learn about available commerce modules and features in Medusa."
    }
  },
  {
    type: 'link',
    href: '/development/overview',
    label: 'Medusa Development',
    customProps: {
      icon: Icons['server-stack-solid'],
      description: "Learn how to develop customized digital commerce applications with Medusa."
    }
  }
]} />

---

## 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 />
    },
  ]}
/>