asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: update admin extension docs (#4778)

Browse Source 
* 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
2023-08-17 20:04:13 +03:00
committed by GitHub
parent 75881a2cfe
commit 80b1bff8cb
21 changed files with 234 additions and 146 deletions
Download Patch File Download Diff File Expand all files Collapse all files

107
www/docs/content/admin/configuration.md Normal file
View File

@@ -0,0 +1,107 @@
---
description: "In this document, you'll learn about the different ways you can configure the admin dashboard for your custom use cases."
---
# Admin Custom Configuration
In this document, you'll learn about the different ways you can configure the admin dashboard for your custom use cases.
## 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 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_ADMIN_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_ADMIN_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`.
---
## 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
})
```

5
www/docs/content/admin/onboarding.md
View File

@@ -2,9 +2,6 @@
title: 'Example: How to Create Onboarding Widget'
description: 'Learn how to build the onboarding widget available in the admin dashboard the first time you install a Medusa project.'
addHowToData: true
badge:
variant: orange
text: beta
---
In this guide, you’ll learn how to build the onboarding widget available in the admin dashboard the first time you install a Medusa project.
@@ -28,7 +25,7 @@ By following this tutorial, you’ll:
## Prerequisites
Before you follow along this tutorial, you must have a Medusa backend installed with the `beta` version of the `@medusajs/admin` package. If not, you can use the following command to get started:
Before you follow along this tutorial, you must have a Medusa backend installed. If not, you can use the following command to get started:
```bash
npx create-medusa-app@latest

92
www/docs/content/admin/quickstart.mdx
View File

@@ -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)

11
www/docs/content/admin/routes.md
View File

@@ -2,9 +2,6 @@
title: 'How to Create an Admin UI Route'
description: 'Learn how to create a new route in the admin dashboard.'
addHowToData: true
badge:
variant: orange
text: beta
---
In this document, you’ll learn how to create a new route in the admin dashboard.
@@ -29,12 +26,6 @@ If you want to create a page under the Settings page, please refer to [this docu
It’s assumed you already have a Medusa backend with the admin plugin installed before you move forward with this guide. If not, you can follow [this documentation page](../create-medusa-app.mdx) to install a Medusa project.
Furthermore, Admin UI Routes are currently available as a beta feature. So, you must install the `beta` version of the `@medusajs/admin` and `@medusajs/medusa` packages:
```bash npm2yarn
npm install @medusajs/admin@beta @medusajs/medusa@beta
```
### (Optional) TypeScript Preparations
Since routes are React components, they should be written in `.tsx` or `.jsx` files. If you’re using Typescript, you need to make some adjustments to avoid Typescript errors in your Admin files.
@@ -190,7 +181,7 @@ For example:
```tsx
import { Post } from "../../../../../models/post"
import PostForm from "../../../../components/post/form"
import { RouteProps } from "@medusajs/admin-ui"
import { RouteProps } from "@medusajs/admin"
const BlogPostCreatePage = ({
notify,

17
www/docs/content/admin/setting-pages.md
View File

@@ -2,9 +2,6 @@
title: 'How to Create an Admin Setting Page'
description: 'Learn how to create a new setting page in the admin dashboard.'
addHowToData: true
badge:
variant: orange
text: beta
---
In this document, you’ll learn how to create a setting page in the admin.
@@ -25,12 +22,6 @@ This guide explains how to create a new setting page in the admin dashboard with
It’s assumed you already have a Medusa backend with the admin plugin installed before you move forward with this guide. If not, you can follow [this documentation page](../create-medusa-app.mdx) to install a Medusa project.
Furthermore, custom Admin Setting Pages are currently available as a beta feature. So, you must install the `beta` version of the `@medusajs/admin` and `@medusajs/medusa` packages:
```bash npm2yarn
npm install @medusajs/admin@beta @medusajs/medusa@beta
```
### (Optional) TypeScript Preparations
Since setting pages are React components, they should be written in `.tsx` or `.jsx` files. If you’re using Typescript, you need to make some adjustments to avoid Typescript errors in your Admin files.
@@ -128,6 +119,12 @@ All setting page paths are prefixed with `/a/settings`.
For example, if you want the setting page to be available in the admin dashboard under the path `/a/settings/custom` you should create your setting page under the file path `src/admin/settings/custom/page.tsx`.
:::note
Only one-level deep files are accepted. So, for example, you can create the page `src/admin/settings/custom/page.tsx`, but not `src/admin/settings/custom/nested/page.tsx`.
:::
### Step 2: Create React Component in File
For a setting page to be valid, it must default export a React component. There are no restrictions on the content of the React component. It must also export a configuration object that indicates how the tab is shown on the Setting page.
@@ -189,7 +186,7 @@ For example:
```tsx title=src/admin/settings/custom/page.tsx
import type { SettingConfig } from "@medusajs/admin"
import type { SettingProps } from "@medusajs/admin-ui"
import type { SettingProps } from "@medusajs/admin"
const CustomSettingPage = ({
notify,

9
www/docs/content/admin/widgets.md
View File

@@ -2,9 +2,6 @@
title: 'How to Create an Admin Widget'
description: 'Learn about what Admin widgets are and how you can create your own.'
addHowToData: true
badge:
variant: orange
text: beta
---
In this document, you will learn about what Admin widgets are and how you can create your own.
@@ -945,12 +942,6 @@ In this section, you’ll learn how to create an admin widget.
It’s assumed you already have a Medusa backend with the admin plugin installed before you move forward with this guide. If not, you can follow [this documentation page](../create-medusa-app.mdx) to install a Medusa project.
Furthermore, Admin Widgets are currently available as a beta feature. So, you must install the `beta` version of the `@medusajs/admin` and `@medusajs/medusa` packages:
```bash npm2yarn
npm install @medusajs/admin@beta @medusajs/medusa@beta
```
### (Optional) TypeScript Preparations
Since Widgets are React components, they should be written in `.tsx` or `.jsx` files. If you’re using Typescript, you need to make some adjustments to avoid Typescript errors in your Admin files.

6
www/docs/content/deployments/admin/deploying-on-vercel.mdx
View File

@@ -89,7 +89,7 @@ In the `package.json` of the Medusa backend, add or change a build script for th
Aside from `--deployment`, you can use the following options when building your admin for deployment:
- `--backend` or `-b`: a string specifying the URL of the Medusa backend. The default here is the value of the environment variable `MEDUSA_BACKEND_URL`. If this options is added, the value you set for `MEDUSA_BACKEND_URL` in Vercel will no longer have an effect. For example, `medusa-admin build --deployment --backend example.com`
- `--backend` or `-b`: a string specifying the URL of the Medusa backend. The default here is the value of the environment variable `MEDUSA_ADMIN_BACKEND_URL`. If this options is added, the value you set for `MEDUSA_ADMIN_BACKEND_URL` in Vercel will no longer have an effect. 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 hosting. 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 coopied 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`.
@@ -135,7 +135,7 @@ This section explains how to deploy the admin using the Vercel website:
5. In the Configure Project form:
1. Set the Framework Preset to Vite.
2. Open the Build and Output Settings collapsible, and set the Build Command to `yarn build:admin` and the Output Directory to `build`. If you’ve configured the admin to use a different output directory, then change it to that directory.
3. Open the Environment Variables collapsible, and add an environment variable with the name `MEDUSA_BACKEND_URL` with the value being the URL to your deployed Medusa backend.
3. Open the Environment Variables collapsible, and add an environment variable with the name `MEDUSA_ADMIN_BACKEND_URL` with the value being the URL to your deployed Medusa backend.
4. You can optionally edit the Project Name.
6. Once you’re done, click on the “Deploy” button.
@@ -154,7 +154,7 @@ This section explains how to deploy the admin using the Vercel CLI tool. You sho
In the directory of your Medusa backend, run the following command to deploy your admin:
```bash
vercel --build-env MEDUSA_BACKEND_URL=<YOUR_BACKEND_URL>
vercel --build-env MEDUSA_ADMIN_BACKEND_URL=<YOUR_BACKEND_URL>
```
Where `<YOUR_BACKEND_URL>` is the URL of your deployed Medusa backend.

2
www/docs/content/deployments/server/deploying-on-digital-ocean.md
View File

@@ -237,7 +237,7 @@ You can access `/health` to get health status of your deployed backend.
:::note
Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/quickstart.mdx#build-command-options) command as part of the start command of your backend.
Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/configuration.md#build-command-options) command as part of the start command of your backend.
:::

2
www/docs/content/deployments/server/deploying-on-heroku.mdx
View File

@@ -250,7 +250,7 @@ You can access `/health` to get health status of your deployed backend.
:::note
Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/quickstart.mdx#build-command-options) command as part of the `serve` command of your backend.
Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/configuration.md#build-command-options) command as part of the `serve` command of your backend.
:::

2
www/docs/content/deployments/server/deploying-on-microtica.md
View File

@@ -104,7 +104,7 @@ You can access `/health` to get health status of your deployed backend.
:::note
Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/quickstart.mdx#build-command-options) command as part of the start command of your backend.
Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/configuration.md#build-command-options) command as part of the start command of your backend.
:::

2
www/docs/content/deployments/server/deploying-on-qovery.md
View File

@@ -498,7 +498,7 @@ You can access any of the endpoints on your backend using the backend URL. For e
:::note
Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/quickstart.mdx#build-command-options) command as part of the start command of your backend.
Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/configuration.md#build-command-options) command as part of the start command of your backend.
:::

2
www/docs/content/deployments/server/deploying-on-railway.md
View File

@@ -221,7 +221,7 @@ You can access `/health` to get health status of your deployed backend.
:::note
Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/quickstart.mdx#build-command-options) command as part of the start command of your backend.
Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/configuration.md#build-command-options) command as part of the start command of your backend.
:::

14
www/docs/content/development/backend/directory-structure.md
View File

@@ -6,10 +6,6 @@ description: "In this document, you’ll learn about the directory structure of
In this document, you’ll learn about the directory structure of a Medusa backend. It’ll help you understand the purpose of each file and folder in your Medusa backend project.
## Note about Beta
Files that have the beta label are only available if you installed the Medusa backend using the `create-medusa-app` command.
---
## Root Files
@@ -54,17 +50,15 @@ Since the Medusa backend is an NPM package, this file defines its information as
Provides general information about the Medusa backend.
### tsconfig.admin.json (beta)
### tsconfig.admin.json
Defines the TypeScript configurations that are used to transpile admin customization files. So, it only works for files under the [src/admin directory](#admin-beta).
Defines the TypeScript configurations that are used to transpile admin customization files. So, it only works for files under the [src/admin directory](#admin).
### tsconfig.json
Defines the general TypeScript configurations used to transpile files from the `src` directory to the `dist` directory.
If you have the beta configuration files, they will extend the configurations in this file along with the configurations they each define.
### tsconfig.server.json (beta)
### tsconfig.server.json
Defines the TypeScript configurations that are used to transpile Medusa backend customization files. It works for all files except for the files under the `src/admin` directory.
@@ -133,7 +127,7 @@ Files under the `src` directory hold the Medusa backend and admin customizations
If any of these directories are not available, you can create them yourself.
### admin (beta)
### admin
This directory holds all Medusa admin customizations. The main subdirectories of this directory are:

12
www/docs/content/development/plugins/create.mdx
View File

@@ -69,16 +69,6 @@ const modules = {}
### Changes for Admin Plugins
:::note
Admin customizations are currently in beta and require you to use the `beta` version of `@medusajs/admin` and `@medusajs/medusa`. You can install them with the following command:
```bash npm2yarn
npm install @medusajs/admin@beta @medusajs/medusa@beta
```
:::
If your plugin contains customizations to the admin dashboard, it's recommended to create different `tsconfig` files for backend and admin customizations, then modify the scripts in `package.json` to handle building backend and admin customizations separately.
:::note
@@ -433,7 +423,7 @@ class MyService extends TransactionBaseService {
:::note
Since admin customizations are still in `beta` mode, `enableUI`'s default value is `false` if not provided by the plugin users. This means that it must be enabled manually in a plugin's option for the customizations to appear in the admin dashboard. Once the admin customizations are out of beta, this behavior will be reversed.
`enableUI`'s default value is `false` if not provided by the plugin users. This means that it must be enabled manually in a plugin's option for the customizations to appear in the admin dashboard.
:::

2
www/docs/content/development/plugins/overview.mdx
View File

@@ -67,7 +67,7 @@ All plugins accept an option named `enableUI`. This option allows you to disable
:::note
Since admin customizations are still in `beta` mode, `enableUI`'s default value is `false` if not provided by the plugin users. This means that it must be enabled manually in a plugin's configuration for the customizations to appear in the admin dashboard. Once the admin customizations are out of beta, this behavior will be reversed.
`enableUI`'s default value is `false` if not provided by the plugin users. This means that it must be enabled manually in a plugin's configuration for the customizations to appear in the admin dashboard.
:::

10
www/docs/content/medusa-react/overview.mdx
View File

@@ -213,16 +213,6 @@ Learn more about how you can use mutations in [Tanstack Query’s documentation]
### Custom Hooks
:::note
This feature is available in the `beta` version of Medusa React, which also requires the `beta` version of the Medusa core. You can install them with the following command:
```bash
npm install medusa-react@beta @medusajs/medusa@beta
```
:::
Medusa React provides three utility hooks that allows developers to consume their admin custom endpoints using the same Medusa React methods and conventions.
#### useAdminCustomQuery

2
www/docs/content/troubleshooting/custom-hooks-error.md
View File

@@ -2,7 +2,7 @@
title: createCustomAdminHooks Error
---
If you've installed Medusa prior to v1.12.3 with the `create-medusa-app` command, then you try to update the `@medusajs/medusa` and `@medusajs/admin` to the latest `beta` versions, you might run into the following error when running your Medusa backend:
If you've installed Medusa prior to v1.13.2 with the `create-medusa-app` command, then you try to update the `@medusajs/medusa` and `@medusajs/admin` to the latest `beta` versions, you might run into the following error when running your Medusa backend:
```bash
Module '"medusa-react"' has no exported member 'createCustomAdminHooks'.

2
www/docs/content/troubleshooting/eaddrinuse.md
View File

@@ -14,5 +14,5 @@ port: 9000
This means that there's another process running at port `9000`. You need to either:
- Change the default port used by the Medusa backend. You can do that by setting the `PORT` environment variable to a new port. When you do this, make sure to change the port used in other apps that interact with your Medusa backend, such as in your [admin](../admin/quickstart.mdx#build-command-options) or [storefront](../starters/nextjs-medusa-starter.mdx#changing-medusa-backend-url).
- Change the default port used by the Medusa backend. You can do that by setting the `PORT` environment variable to a new port. When you do this, make sure to change the port used in other apps that interact with your Medusa backend, such as in your [admin](../admin/configuration.md#build-command-options) or [storefront](../starters/nextjs-medusa-starter.mdx#changing-medusa-backend-url).
- Terminate other processes running on port `9000`.

64
www/docs/content/upgrade-guides/admin/7-0-0.md Normal file
View File

@@ -0,0 +1,64 @@
---
description: "Migrate to v7.0.0 of the admin that supports Admin Extensions"
sidebar_label: 'v7.0.0'
sidebar_custom_props:
iconName: 'computer-desktop-solid'
---
# Medusa Admin: v7.0.0
Version 7.0.0 introduces Admin Extensions, which were previously available as a `beta` version. By upgrading to this version, you'll be able to create admin [widgets](../../admin/widgets.md), [UI routes](../../admin/routes.md), and [setting pages](../../admin/setting-pages.md).
This version also introduces a breaking change to the `path` configuration of the admin plugin.
---
## How to Update
Run the following command in the root directory of your Medusa backend to update the admin plugin:
```bash npm2yarn
npm install @medusajs/admin@7.0.0
```
---
## Actions Required
### Path Configuration
Previously, the `path` configuration of the admin plugin set in `medusa-config.js` expected the path to not include a backslash `/` at its beginning or its end.
Starting from v7.0.0 of `@medusajs/admin`, the `path` configuration is required to start with a `/`, but not end with one.
For example, if you've set the admin configuration as follows:
```js title=medusa-config.js
const plugins = [
// ...
{
resolve: "@medusajs/admin",
/** @type {import('@medusajs/admin').PluginOptions} */
options: {
path: "admin",
// ...
},
},
]
```
You should change the value of `path` to `/admin`:
```js title=medusa-config.js
const plugins = [
// ...
{
resolve: "@medusajs/admin",
/** @type {import('@medusajs/admin').PluginOptions} */
options: {
path: "/admin",
// ...
},
},
]
```

12
www/docs/content/upgrade-guides/index.mdx
View File

@@ -16,14 +16,14 @@ Find in this page the upgrade guides that require necessary steps when upgrading
item={getFirstCategoryItem('Backend')}
/>
## Medusa React
<DocCard
item={getFirstCategoryItem('Medusa React')}
/>
## Admin Dashboard
<DocCard
item={getFirstCategoryItem('Admin Dashboard')}
/>
## Medusa React
<DocCard
item={getFirstCategoryItem('Medusa React')}
/>

5
www/docs/sidebars.js
View File

@@ -97,6 +97,11 @@ module.exports = {
},
className: "homepage-sidebar-item",
items: [
{
type: "doc",
label: "Admin Custom Configuration",
id: "admin/configuration",
},
{
type: "doc",
label: "Admin Widgets",