medusa-store/www/docs/content/admin/quickstart.mdx

---
description: "Learn how to install Medusa's admin dashboard. The admin dashboard gives merchants an easy-to-use interface to manage their data such as orders, products, regions, and more."
addHowToData: true
---

import Feedback from '@site/src/components/Feedback';
import Troubleshooting from '@site/src/components/Troubleshooting'
import AdminLoginSection from '../troubleshooting/signing-in-to-admin.md'
import CorsSection from '../troubleshooting/cors-issues.md'

# Admin Dashboard Quickstart

This document will guide you through setting up the admin dashboard in the Medusa backend.

## Overview

The admin dashboard is installed on the Medusa backend. The admin dashboard starts when you start the Medusa backend. This also means you can later deploy the Medusa backend along with the admin dashboard on the same hosting.

This guide will explain the steps and configurations required to set up the admin dashboard.

---

## Prerequisites

### Medusa Backend

As the admin dashboard is a plugin installed on the Medusa Backend, you must have a Medusa Backend installed first. You can learn how to install it in [this documentation](../development/backend/install.mdx).

### Node.js

The Admin uses [Vite v4.1.4](https://vitejs.dev/guide/#scaffolding-your-first-vite-project) which requires v14.8+ or v16+ of Node.js, and as Medusa requires v16 or greater it's recommended you use v16+ of Node.js.

You can check which version of Node you have by running the following command:

```bash noReport
node -v
```

You can install Node from the [official website](https://nodejs.org/en/).

---

## Install and Serve Admin with the Backend

This section explains how to install the admin to be served with the Medusa Backend and later deployed together.

### Step 1: Install the Package

In the directory of your Medusa backend, run the following command to install admin dashboard:

```bash npm2yarn
npm install @medusajs/admin
```

:::note

Installing the `@beta` version of the admin and Medusa core allows you to perform customizations such as creating [Admin Widgets](./widgets.md) or [Admin Dashboard Routes](./routes.md). You can install the `beta` version with the following command:

```bash npm2yarn
npm install @medusajs/admin@beta @medusajs/medusa@beta
```

:::

### Step 2: Add Admin to Medusa Configurations

In `medusa-config.js`, add the admin plugin into the array of `plugins`:

```js title=medusa-config.js
const plugins = [
  // ...
  {
    resolve: "@medusajs/admin",
    /** @type {import('@medusajs/admin').PluginOptions} */
    options: {
      // ...
    },
  },
]
```

The plugin accepts the following options:

1. `serve`: (default: `true`) a boolean indicating whether to serve the admin dashboard when the Medusa backend starts. If set to `false`, you can serve the admin dashboard using the [dev command](#dev-command-options).
2. `path`: (default: `app`) a string indicating the path the admin server should run on when [running the Medusa backend in production](#note-on-admin-path). It shouldn't be prefixed or suffixed with a slash `/`, and it can't be one of the reserved paths: "admin" and "store".
3. `outDir`: Optional path for where to output the admin build files.
4. `autoRebuild`: (default: `false`) a boolean indicating whether the admin UI should be rebuilt if there are any changes or if a missing build is detected when the backend starts. If not set, you must [manually build the admin dashboard](#build-command-options).

### Optional: Manually Building Admin Dashboard

If you have `autoRebuild` disabled, you must build your admin dashboard before starting the Medusa backend. Refer to the [build command](#build-command-options) for more details.

### Step 3: Test the Admin Dashboard

:::tip

If you disabled the `serve` option, you need to run the admin dashboard separately using the [dev command](#dev-command-options)

:::

You can test the admin dashboard by running the following command in the directory of the Medusa backend:

```bash
npx medusa develop
```

This starts the Medusa Backend and the admin dashboard. By default, the admin will be available on the URL `localhost:9000/app`. If you set the path option, then the admin will be available on `localhost:9000/<PATH>` with `<PATH>` being the value of the path option.

:::note

If you're using the `@beta` version of the admin plugin, the admin dashboard will run on `localhost:7001` when you run the `develop` command.

:::

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

---

## Demo Credentials

If you installed the demo data when you installed the Medusa backend by running:

```bash npm2yarn
npm run seed
```

You can use the email `admin@medusa-test.com` and password `supersecret` to log in.

:::info

Passwords in Medusa are hashed using the [scrypt-kdf](https://www.npmjs.com/package/scrypt-kdf). The password hash is then stored in the database.

:::

---

## Create a New Admin User

To create a new admin user from the command line, run the following command in the directory holding your Medusa backend:

```bash
npx medusa user -e some@email.com -p some-password
```

This will create a new user that you can use to log into your admin panel.

---

## Build Command Options

The `build` command in the admin CLI allows you to manually build the admin dashboard. If you intend to use it, you should typically add it to the `package.json` of the Medusa backend:

```json title=package.json
{
  "scripts": {
    // other scripts...
    "build:admin": "medusa-admin build"
  }
}
```

You can add the following options to the `medusa-admin build` command:

- `--deployment`: a boolean value indicating that the build should be ready for deployment. When this option is added, options are not loaded from `medusa-config.js` anymore, and it means the admin will be built to be hosted on an external host. For example, `medusa-admin build --deployment`.
- `--backend` or `-b`: a string specifying the URL of the Medusa backend. This can be useful with the `--deployment` option. The default here is the value of the environment variable `MEDUSA_BACKEND_URL`. For example, `medusa-admin build --deployment --backend example.com`
- `--out-dir` or `-o`: a string specifying a custom path to output the build files to. By default, it will be the `build` directory. For example, `medusa-admin --deployment --out-dir public`.
- `--include` or `-i`: a list of strings of paths to files you want to include in the build output. It can be useful if you want to inject files that are relevant to your external hosting, such as adding a `200.html` file that is needed for redirects on Surge. For example, `medusa-admin --deployment --include 200.html`
- `--include-dist` or `-d`: a string specifying the path to copy the files specified in `--include` to. By default, the files are copied to the root of the build directory. You can use this option to change that. For example, `medusa-admin --deployment --include 200.html --include-dist static`.

---

## Dev Command Options

The `dev` command in the admin CLI allows you to run the admin dashboard in development separately from the Medusa backend. If you intend to use it, you should typically add it to the `package.json` of the Medusa backend:

```json title=package.json
{
  "scripts": {
    // other scripts...
    "dev:admin": "medusa-admin dev"
  }
}
```

You can add the following options to the `medusa-admin dev` command:

- `--backend` or `-b`: a string specifying the URL of the Medusa backend. By default, it's the value of the environment variable `MEDUSA_BACKEND_URL`. For example, `medusa-admin dev --backend example.com`.
- `--port` or `-p`: the port to run the admin on. By default, it's `7001`. For example, `medusa-admin dev --port 8000`.

---

## Admin User Guide

The admin dashboard provides a lot of ecommerce features including managing Return Merchandise Authorization (RMA) flows, store settings, products, orders, and much more.

You can learn more about the admin dashboard and its features in the [User Guide](../user-guide.mdx).

---

## Troubleshooting Installation

<Troubleshooting
  sections={[
    {
      title: 'Signing into Admin',
      content: <AdminLoginSection />
    },
    {
      title: 'CORS Errors',
      content: <CorsSection />
    }
  ]}
/>

---

## See Also

- [Admin widgets](./widgets.md)
- [Admin UI routes](./routes.md)