docs: update admin extension docs (#4778)
* docs: update admin extension docs * eslint fixes * fix broken links * fix broken link * added admin upgrade guide * fix lint errors
This commit is contained in:
Shahed Nasser
@@ -52,16 +52,6 @@ In the directory of your Medusa backend, run the following command to install ad
|
||||
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`:
|
||||
@@ -81,20 +71,23 @@ const plugins = [
|
||||
|
||||
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".
|
||||
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](./configuration.md#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. It must be prefixed with a slash `/`, but it can't end with a `/`, which throws an error. It also 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).
|
||||
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](./configuration.md#build-command-options).
|
||||
5. `develop`: An optional object that accepts the following properties:
|
||||
- `open`: (default: `true`) a boolean value that indicates if the browser should be opened when the medusa project is first started.
|
||||
- `port`: (default: `7001`) a number indicating the port the admin dashboard runs on.
|
||||
|
||||
### 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.
|
||||
If you have `autoRebuild` disabled, you must build your admin dashboard before starting the Medusa backend. Refer to the [build command](./configuration.md#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)
|
||||
If you disabled the `serve` option, you need to run the admin dashboard separately using the [dev command](./configuration.md#dev-command-options)
|
||||
|
||||
:::
|
||||
|
||||
@@ -104,13 +97,7 @@ You can test the admin dashboard by running the following command in the directo
|
||||
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.
|
||||
|
||||
:::
|
||||
This starts the Medusa Backend and the admin dashboard in a development environment. By default, the admin will be available on the URL `localhost:7001` and the browser will open automatically to the admin dashboard in your default browser, unless you have the `develop.open` option disabled.
|
||||
|
||||
<Feedback
|
||||
event="survey_admin_quickstart"
|
||||
@@ -121,6 +108,23 @@ If you're using the `@beta` version of the admin plugin, the admin dashboard wil
|
||||
|
||||
---
|
||||
|
||||
## Production Path
|
||||
|
||||
:::note
|
||||
|
||||
This doesn't apply if you have the `serve` option disabled.
|
||||
|
||||
:::
|
||||
|
||||
When you run the Medusa project in a production environment (such as with the `npx medusa start` command), the admin dashboard will be available at `<MEDUSA_URL>/<ADMIN_PATH>`, where:
|
||||
|
||||
1. `<MEDUSA_URL>` is the URL of your Medusa backend. By default, it'll be `localhost:9000` locally.
|
||||
2. `<ADMIN_PATH>` is the path you define in the [admin's configurations](#step-2-add-admin-to-medusa-configurations).
|
||||
|
||||
So, if you simulate a production environment locally, the admin dashboard will run by default on `localhost:9000/app`.
|
||||
|
||||
---
|
||||
|
||||
## Demo Credentials
|
||||
|
||||
If you installed the demo data when you installed the Medusa backend by running:
|
||||
@@ -151,49 +155,6 @@ 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.
|
||||
@@ -221,5 +182,6 @@ You can learn more about the admin dashboard and its features in the [User Guide
|
||||
|
||||
## See Also
|
||||
|
||||
- [Admin Configuration](./configuration.md)
|
||||
- [Admin widgets](./widgets.md)
|
||||
- [Admin UI routes](./routes.md)
|
||||
|
||||
Reference in New Issue
Block a user