8c67e32d41
- Move the admin plugin's options to the Admin Configuration documentation. - Add a section on how to change the backend URL for both development and production. - Fix the troubleshooting section related to port forwarding. - General fixes.
338 lines
10 KiB
Plaintext
338 lines
10 KiB
Plaintext
---
|
|
description: "In this document, you'll learn about the different ways you can configure the admin dashboard."
|
|
---
|
|
|
|
import ParameterTypes from "@site/src/components/ParameterTypes"
|
|
|
|
# Admin Configuration
|
|
|
|
In this document, you'll learn about the different ways you can configure the admin dashboard.
|
|
|
|
## Plugin Options
|
|
|
|
The plugin accepts the following options:
|
|
|
|
```js title=medusa-config.js
|
|
const plugins = [
|
|
// ...
|
|
{
|
|
resolve: "@medusajs/admin",
|
|
/** @type {import('@medusajs/admin').PluginOptions} */
|
|
options: {
|
|
serve: true,
|
|
autoRebuild: true,
|
|
backend: "https://example.com",
|
|
path: "/app",
|
|
outDir: "build",
|
|
develop: {
|
|
open: true,
|
|
port: 7001,
|
|
logLevel: "error",
|
|
stats: "normal",
|
|
allowedHosts: "auto",
|
|
webSocketURL: undefined,
|
|
},
|
|
},
|
|
},
|
|
]
|
|
```
|
|
|
|
<ParameterTypes parameters={[
|
|
{
|
|
name: "serve",
|
|
type: "boolean",
|
|
optional: true,
|
|
defaultValue: "true",
|
|
description: "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](#develop-command-options).",
|
|
expandable: false,
|
|
children: []
|
|
},
|
|
{
|
|
name: "autoRebuild",
|
|
type: "boolean",
|
|
optional: true,
|
|
defaultValue: "false",
|
|
description: "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).",
|
|
expandable: false,
|
|
children: []
|
|
},
|
|
{
|
|
name: "backend",
|
|
type: "string",
|
|
optional: true,
|
|
defaultValue: "",
|
|
description: "The URL of the Medusa backend. Its value is only used if the `serve` option is set to `false`.",
|
|
expandable: false,
|
|
children: []
|
|
},
|
|
{
|
|
name: "path",
|
|
type: "string",
|
|
optional: true,
|
|
defaultValue: "/app",
|
|
description: "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\".",
|
|
expandable: false,
|
|
children: []
|
|
},
|
|
{
|
|
name: "outDir",
|
|
type: "string",
|
|
optional: true,
|
|
defaultValue: "",
|
|
description: "The directory to output the admin build to. By default, the plugin builds the admin to the `build` directory in the root of the Medusa backend directory.",
|
|
expandable: false,
|
|
children: []
|
|
},
|
|
{
|
|
name: "develop",
|
|
type: "object",
|
|
optional: true,
|
|
defaultValue: "",
|
|
description: "Options for the admin development server.",
|
|
expandable: false,
|
|
children: [
|
|
{
|
|
name: "open",
|
|
type: "boolean",
|
|
optional: true,
|
|
defaultValue: "true",
|
|
description: "Whether the browser should be opened when the admin development server starts.",
|
|
expandable: false,
|
|
children: []
|
|
},
|
|
{
|
|
name: "port",
|
|
type: "number",
|
|
optional: true,
|
|
defaultValue: "7001",
|
|
description: "The port the admin dashboard runs on.",
|
|
expandable: false,
|
|
children: []
|
|
},
|
|
{
|
|
name: "logLevel",
|
|
type: "\"error\" \\| \"none\" \\| \"warn\" \\| \"info\" \\| \"log\" \\| \"verbose\"",
|
|
optional: true,
|
|
defaultValue: "error",
|
|
description: "The log level of the admin development server.",
|
|
expandable: false,
|
|
children: []
|
|
},
|
|
{
|
|
name: "stats",
|
|
type: "\"normal\" \\| \"debug\"",
|
|
optional: true,
|
|
defaultValue: "normal",
|
|
description: "The verbosity of the admin development server.",
|
|
expandable: false,
|
|
children: []
|
|
},
|
|
{
|
|
name: "allowedHosts",
|
|
type: "\"auto\" \\| \"all\" \\| string[]",
|
|
optional: true,
|
|
defaultValue: "auto",
|
|
description: "The development server's allowed hosts.",
|
|
expandable: false,
|
|
children: []
|
|
},
|
|
{
|
|
name: "webSocketURL",
|
|
type: "string \\| object \\| undefined",
|
|
optional: true,
|
|
defaultValue: "",
|
|
description: "The URL to a web socket server",
|
|
expandable: false,
|
|
children: [
|
|
{
|
|
name: "hostname",
|
|
type: "string",
|
|
optional: true,
|
|
defaultValue: "",
|
|
description: "The web socket's hostname.",
|
|
expandable: false,
|
|
children: []
|
|
},
|
|
{
|
|
name: "password",
|
|
type: "string",
|
|
optional: true,
|
|
defaultValue: "",
|
|
description: "The web socket's password.",
|
|
expandable: false,
|
|
children: []
|
|
},
|
|
{
|
|
name: "path name",
|
|
type: "string",
|
|
optional: true,
|
|
defaultValue: "",
|
|
description: "The web socket's path name.",
|
|
expandable: false,
|
|
children: []
|
|
},
|
|
{
|
|
name: "port",
|
|
type: "string",
|
|
optional: true,
|
|
defaultValue: "",
|
|
description: "The web socket's port.",
|
|
expandable: false,
|
|
children: []
|
|
},
|
|
{
|
|
name: "username",
|
|
type: "string",
|
|
optional: true,
|
|
defaultValue: "",
|
|
description: "The web socket's username.",
|
|
expandable: false,
|
|
children: []
|
|
},
|
|
]
|
|
},
|
|
]
|
|
}
|
|
]} />
|
|
|
|
---
|
|
|
|
## Admin CLI
|
|
|
|
### 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 option 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. This also means that the backend URL is loaded from the `MEDUSA_ADMIN_BACKEND_URL` environment variable. For example, `medusa-admin build --deployment`.
|
|
|
|
### Develop Command Options
|
|
|
|
The `develop` 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 develop"
|
|
}
|
|
}
|
|
```
|
|
|
|
You can add the following options to the `medusa-admin develop` command:
|
|
|
|
- `--backend` or `-b`: a string specifying the URL of the Medusa backend. By default, it's the value of the environment variable `MEDUSA_ADMIN_BACKEND_URL`. For example, `medusa-admin develop --backend example.com`.
|
|
- `--port` or `-p`: the port to run the admin on. By default, it's `7001`. For example, `medusa-admin develop --port 8000`.
|
|
|
|
---
|
|
|
|
## Change Backend URL
|
|
|
|
### In Development
|
|
|
|
To change the backend's URL that the admin sends request to in development, you must disable the `serve` plugin option and set the `backend` option to the URL of your Medusa backend.
|
|
|
|
However, this requires you to also set-up the [develop command](#develop-command-options) as the admin will no longer start with the Medusa backend.
|
|
|
|
For example:
|
|
|
|
```js title=medusa-config.js
|
|
const plugins = [
|
|
// ...
|
|
{
|
|
resolve: "@medusajs/admin",
|
|
/** @type {import('@medusajs/admin').PluginOptions} */
|
|
options: {
|
|
serve: false,
|
|
backend: "http://localhost:9001",
|
|
// other options...
|
|
},
|
|
},
|
|
]
|
|
```
|
|
|
|
### In Production
|
|
|
|
:::note
|
|
|
|
This assumes that you've deployed the admin separately and you're passing the `--deployment` option to the [build command](#build-command-options).
|
|
|
|
:::
|
|
|
|
To change the backend's URL that the admin sends request to in production, set the environment variable `MEDUSA_ADMIN_BACKEND_URL` to the backend's URL.
|
|
|
|
For example:
|
|
|
|
```bash
|
|
MEDUSA_ADMIN_BACKEND_URL=https://example.com
|
|
```
|
|
|
|
---
|
|
|
|
## Custom Environment Variables
|
|
|
|
If you want to set environment variables that you want to access in your admin dashboard's customizations (such as in [widgets](./widgets.md) or [UI routes](./routes.md)), your environment variables must be prefixed with `MEDUSA_ADMIN_`. Otherwise, it won't be loaded within the admin.
|
|
|
|
For example:
|
|
|
|
```bash
|
|
MEDUSA_ADMIN_CUSTOM_API_KEY=123...
|
|
```
|
|
|
|
---
|
|
|
|
## Custom Webpack Configurations
|
|
|
|
:::note
|
|
|
|
Plugins cannot include webpack customizations.
|
|
|
|
:::
|
|
|
|
The admin dashboard uses [Webpack](https://webpack.js.org/) to define the necessary configurations for both the core admin plugin and your extensions. So, for example, everything works out of the box with Tailwind CSS, the admin dependencies, and more.
|
|
|
|
However, you may have some advanced case where you need to tweak the webpack configurations. For example, you want to support styling your extensions with CSS Modules.
|
|
|
|
For such use cases, you can extend the default webpack configurations defined in the admin plugin to add your custom configurations.
|
|
|
|
To do that, create the file `src/admin/webpack.config.js` that uses the `withCustomWebpackConfig` method imported from `@medusajs/admin` to export the extended configurations. The method accepts a callback function that must return an object of [webpack configuration](https://webpack.js.org/configuration/). The callback function accepts two parameters:
|
|
|
|
1. `config`: the first parameter is an object that holds the default webpack configuration. You should add your configurations to this object, then return it. Not returning the default configurations will lead to the application breaking.
|
|
2. `webpack`: the second parameter is the webpack instance.
|
|
|
|
:::warning
|
|
|
|
This is an advanced feature and requires knowledge of configuring webpack. If configured wrongly, it may lead to the admin application breaking.
|
|
|
|
:::
|
|
|
|
For example:
|
|
|
|
```js title="src/admin/webpack.config.js"
|
|
import { withCustomWebpackConfig } from "@medusajs/admin"
|
|
|
|
export default withCustomWebpackConfig((config, webpack) => {
|
|
config.plugins.push(
|
|
new webpack.DefinePlugin({
|
|
"process.env": {
|
|
NODE_ENV: JSON.stringify("production"),
|
|
API_URL:
|
|
JSON.stringify("https://api.medusa-commerce.com"),
|
|
},
|
|
})
|
|
)
|
|
|
|
return config
|
|
})
|
|
```
|