docs: create docs workspace (#5174)
* docs: migrate ui docs to docs universe * created yarn workspace * added eslint and tsconfig configurations * fix eslint configurations * fixed eslint configurations * shared tailwind configurations * added shared ui package * added more shared components * migrating more components * made details components shared * move InlineCode component * moved InputText * moved Loading component * Moved Modal component * moved Select components * Moved Tooltip component * moved Search components * moved ColorMode provider * Moved Notification components and providers * used icons package * use UI colors in api-reference * moved Navbar component * used Navbar and Search in UI docs * added Feedback to UI docs * general enhancements * fix color mode * added copy colors file from ui-preset * added features and enhancements to UI docs * move Sidebar component and provider * general fixes and preparations for deployment * update docusaurus version * adjusted versions * fix output directory * remove rootDirectory property * fix yarn.lock * moved code component * added vale for all docs MD and MDX * fix tests * fix vale error * fix deployment errors * change ignore commands * add output directory * fix docs test * general fixes * content fixes * fix announcement script * added changeset * fix vale checks * added nofilter option * fix vale error
This commit is contained in:
Shahed Nasser
GitHub
103
www/apps/docs/content/admin/configuration.md
Normal file
103
www/apps/docs/content/admin/configuration.md
Normal file
@@ -0,0 +1,103 @@
|
||||
---
|
||||
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 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`.
|
||||
|
||||
### Dev 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 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
|
||||
})
|
||||
```
|
||||
2400
www/apps/docs/content/admin/onboarding.md
Normal file
2400
www/apps/docs/content/admin/onboarding.md
Normal file
File diff suppressed because it is too large
Load Diff
201
www/apps/docs/content/admin/quickstart.mdx
Normal file
201
www/apps/docs/content/admin/quickstart.mdx
Normal file
@@ -0,0 +1,201 @@
|
||||
---
|
||||
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
|
||||
```
|
||||
|
||||
### 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](./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](./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](./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](./configuration.md#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 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"
|
||||
question="Did you set up the admin successfully?"
|
||||
positiveQuestion="Is there anything that should improved?"
|
||||
negativeQuestion="Please describe the issue you faced."
|
||||
/>
|
||||
|
||||
---
|
||||
|
||||
## 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:
|
||||
|
||||
```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.
|
||||
|
||||
---
|
||||
|
||||
## 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).
|
||||
|
||||
---
|
||||
|
||||
## Multi-Language Support
|
||||
|
||||
Medusa supports multiple languages and translations.
|
||||
|
||||
Refer to this user guide to learn how to switch the language of the Medusa admin.
|
||||
|
||||
:::note
|
||||
|
||||
Can't find your language? Learn how you can contribute by translating the admin to other languages [here](../contribution/admin-translations.md).
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Installation
|
||||
|
||||
<Troubleshooting
|
||||
sections={[
|
||||
{
|
||||
title: 'Signing into Admin',
|
||||
content: <AdminLoginSection />
|
||||
},
|
||||
{
|
||||
title: 'CORS Errors',
|
||||
content: <CorsSection />
|
||||
}
|
||||
]}
|
||||
/>
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Admin Configuration](./configuration.md)
|
||||
- [Admin widgets](./widgets.md)
|
||||
- [Admin UI routes](./routes.md)
|
||||
368
www/apps/docs/content/admin/routes.md
Normal file
368
www/apps/docs/content/admin/routes.md
Normal file
@@ -0,0 +1,368 @@
|
||||
---
|
||||
title: 'How to Create an Admin UI Route'
|
||||
description: 'Learn how to create a new route in the admin dashboard.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
In this document, you’ll learn how to create a new route in the admin dashboard.
|
||||
|
||||
## Overview
|
||||
|
||||
You can customize the admin dashboard that Medusa provides to add new routes. This is useful if you want to add new subpages to the admin dashboard, or you want to add new pages that appear in the sidebar as well.
|
||||
|
||||
An admin UI route is essentially a React Component created under the `src/admin/routes` directory.
|
||||
|
||||
This guide explains how to create a new route in the admin dashboard with some examples.
|
||||
|
||||
:::note
|
||||
|
||||
If you want to create a page under the Settings page, please refer to [this documentation](./setting-pages.md) instead.
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
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.
|
||||
|
||||
### (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.
|
||||
|
||||
This section provides recommended configurations to avoid any TypeScript errors.
|
||||
|
||||
:::note
|
||||
|
||||
These changes may already be available in your Medusa project. They're included here for reference purposes.
|
||||
|
||||
:::
|
||||
|
||||
First, update your `tsconfig.json` with the following configurations:
|
||||
|
||||
```json title=tsconfig.json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "es2019",
|
||||
"module": "commonjs",
|
||||
"allowJs": true,
|
||||
"checkJs": false,
|
||||
"jsx": "react-jsx",
|
||||
"declaration": true,
|
||||
"outDir": "./dist",
|
||||
"rootDir": "./src",
|
||||
"experimentalDecorators": true,
|
||||
"emitDecoratorMetadata": true,
|
||||
"noEmit": false,
|
||||
"strict": false,
|
||||
"moduleResolution": "node",
|
||||
"esModuleInterop": true,
|
||||
"resolveJsonModule": true,
|
||||
"skipLibCheck": true,
|
||||
"forceConsistentCasingInFileNames": true
|
||||
},
|
||||
"include": ["src/"],
|
||||
"exclude": [
|
||||
"dist",
|
||||
"build",
|
||||
".cache",
|
||||
"tests",
|
||||
"**/*.spec.js",
|
||||
"**/*.spec.ts",
|
||||
"node_modules",
|
||||
".eslintrc.js"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The important changes to note here are the inclusion of the field `"jsx": "react-jsx"` and the addition of `"build"` and `“.cache”` to `exclude`.
|
||||
|
||||
The addition of `"jsx": "react-jsx"` specified how should TypeScript transform JSX, and excluding `build` and `.cache` ensures that TypeScript ignores build and development files.
|
||||
|
||||
Next, create the file `tsconfig.server.json` with the following content:
|
||||
|
||||
```json title=tsconfig.server.json
|
||||
{
|
||||
"extends": "./tsconfig.json",
|
||||
"compilerOptions": {
|
||||
/* Emit a single file with source maps instead of having a separate file. */
|
||||
"inlineSourceMap": true
|
||||
},
|
||||
"exclude": ["src/admin", "**/*.spec.js"]
|
||||
}
|
||||
```
|
||||
|
||||
This is the configuration that will be used to transpile your custom backend code, such as services or entities. The important part is that it excludes `src/admin` as that is where your Admin code will live.
|
||||
|
||||
Finally, create the file `tsconfig.admin.json` with the following content:
|
||||
|
||||
```json title=tsconfig.admin.json
|
||||
{
|
||||
"extends": "./tsconfig.json",
|
||||
"compilerOptions": {
|
||||
"module": "esnext"
|
||||
},
|
||||
"include": ["src/admin"],
|
||||
"exclude": ["**/*.spec.js"]
|
||||
}
|
||||
```
|
||||
|
||||
This is the configuration that will be used when transpiling your admin code.
|
||||
|
||||
---
|
||||
|
||||
## Create the Admin UI Route
|
||||
|
||||
In this section, you’ll learn the basics of creating an admin UI route.
|
||||
|
||||
### Step 1: Create File
|
||||
|
||||
Custom admin UI routes are added under the `src/admin/routes` directory of your Medusa project. The path of the file depends on the path you want the route to be available under. It is based on [Next.js 13’s App Router](https://nextjs.org/docs/app/building-your-application/routing/defining-routes).
|
||||
|
||||
For example, if you want the route to be available in the admin dashboard under the path `/a/custom` you should create your admin route under the path `src/admin/routes/custom/page.tsx`.
|
||||
|
||||
:::tip
|
||||
|
||||
All admin routes are prefixed with `/a` by default.
|
||||
|
||||
:::
|
||||
|
||||
You can also create [dynamic routes](https://nextjs.org/docs/app/building-your-application/routing/dynamic-routes). For example, you can create the route `/a/custom/[id]` by creating an admin router under the path `src/admin/routes/custom/[id]/page.tsx`.
|
||||
|
||||
### Step 2: Create React Component in File
|
||||
|
||||
For an admin route to be valid, it must default export a React component. There are no restrictions on the content of the React component.
|
||||
|
||||
For example, you can create the file `src/admin/routes/custom/page.tsx` with the following content:
|
||||
|
||||
```tsx title=src/admin/routes/custom/page.tsx
|
||||
const CustomPage = () => {
|
||||
return (
|
||||
<div>
|
||||
This is my custom route
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export default CustomPage
|
||||
```
|
||||
|
||||
This will create an admin UI route at the path `/a/custom`, with its content being the content of the React component.
|
||||
|
||||
### Step 3: Test it Out
|
||||
|
||||
To test your admin UI route, run the following command in the root directory of the Medusa backend project:
|
||||
|
||||
```bash npm2yarn
|
||||
npx medusa develop
|
||||
```
|
||||
|
||||
This will build your admin and opens a window in your default browser to `localhost:7001`. After you log in, if you go to `localhost:7001/a/custom`, you’ll find the page you just created.
|
||||
|
||||
:::note
|
||||
|
||||
When using the `develop` command, the admin dashboard will run in development mode and will restart whenever you make changes to your admin customizations. This allows you to see changes in the dashboard instantly during your development.
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Route Props
|
||||
|
||||
Every route receives props of the type `RouteProps`, which includes the `notify` prop. The `notify` prop is an object that includes the following attributes:
|
||||
|
||||
- `success`: a function that can be used to show a success message.
|
||||
- `error`: a function that can be used to show an error message.
|
||||
- `warn`: a function that can be used to show a warning message.
|
||||
- `info`: a function that can be used to show an info message.
|
||||
|
||||
For example:
|
||||
|
||||
```tsx
|
||||
import { Post } from "../../../../../models/post"
|
||||
import PostForm from "../../../../components/post/form"
|
||||
import { RouteProps } from "@medusajs/admin"
|
||||
|
||||
const BlogPostCreatePage = ({
|
||||
notify,
|
||||
}: RouteProps) => {
|
||||
const onSuccess = (post: Post) => {
|
||||
notify.success(
|
||||
"Success",
|
||||
`Post ${post.title} created successfully`
|
||||
)
|
||||
}
|
||||
|
||||
return (
|
||||
<div>
|
||||
<h1 className="text-xl mb-2">Create Post</h1>
|
||||
<PostForm onSuccess={onSuccess} />
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export default BlogPostCreatePage
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Show Route in Sidebar
|
||||
|
||||
You can add your routes into the admin dashboard sidebar by exporting an object of type `RouteConfig` import from `@medusajs/admin` in the same route file.
|
||||
|
||||
The object has one property `link`, which is an object having the following properties:
|
||||
|
||||
- `label`: a string indicating the sidebar item’s label of your custom route.
|
||||
- `icon`: an optional React component that acts as an icon in the sidebar. If none provided, a default icon is used.
|
||||
|
||||
For example, you can change the content of the previous route you created to export a config object:
|
||||
|
||||
```tsx title=src/admin/routes/custom/page.tsx
|
||||
import { RouteConfig } from "@medusajs/admin"
|
||||
import { CustomIcon } from "../../icons/custom"
|
||||
|
||||
const CustomPage = () => {
|
||||
return (
|
||||
<div>
|
||||
This is my custom route
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export const config: RouteConfig = {
|
||||
link: {
|
||||
label: "Custom Route",
|
||||
icon: CustomIcon,
|
||||
},
|
||||
}
|
||||
|
||||
export default CustomPage
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Retrieve Path Parameters
|
||||
|
||||
As mentioned earlier, you can create dynamic routes like `/a/custom/[id]` by creating a route file at the path `src/admin/routes/custom/[id]/page.tsx`.
|
||||
|
||||
To retrieve the path parameter, you can use the [useParams hook](https://reactrouter.com/en/main/hooks/use-params) retrieved from the [react-router-dom](https://reactrouter.com/en/main) package.
|
||||
|
||||
:::note
|
||||
|
||||
`react-router-dom` is available as one of the `@medusajs/admin` dependencies. You can also install it within your project using the following command:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install react-router-dom
|
||||
```
|
||||
|
||||
If you're installing it in a plugin with admin customizations, make sure to include it in `peerDependencies`.
|
||||
|
||||
:::
|
||||
|
||||
For example:
|
||||
|
||||
```tsx title=src/admin/routes/custom/[id]/page.tsx
|
||||
import { useParams } from "react-router-dom"
|
||||
|
||||
const CustomPage = () => {
|
||||
const { id } = useParams()
|
||||
|
||||
return (
|
||||
<div>
|
||||
Passed ID: {id}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export default CustomPage
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Routing Functionalities
|
||||
|
||||
If you want to use routing functionalities such as linking to another page or navigating between pages, you can use `react-router-dom`'s utility hooks and functions.
|
||||
|
||||
For example, to add a link to another page:
|
||||
|
||||
```tsx title=src/admin/routes/custom/page.tsx
|
||||
import { Link } from "react-router-dom"
|
||||
|
||||
const CustomPage = () => {
|
||||
|
||||
return (
|
||||
<div>
|
||||
<Link to={"/a/products"}>
|
||||
View Products
|
||||
</Link>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export default CustomPage
|
||||
```
|
||||
|
||||
View [react-router-dom’s documentation](https://reactrouter.com/en/main) for other available components and hooks.
|
||||
|
||||
---
|
||||
|
||||
## Styling Route
|
||||
|
||||
Admin UI routes support [Tailwind CSS](https://tailwindcss.com/) by default.
|
||||
|
||||
For example, to customize your custom route:
|
||||
|
||||
<!-- eslint-disable max-len -->
|
||||
|
||||
```tsx title=src/admin/routes/custom/page.tsx
|
||||
const CustomPage = () => {
|
||||
return (
|
||||
<div
|
||||
className="bg-white p-8 border border-gray-200 rounded-lg">
|
||||
This is my custom route
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export default CustomPage
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Querying and Mutating Data
|
||||
|
||||
You might need to interact with the Medusa backend from your admin route. To do so, you can utilize the [Medusa React package](../medusa-react/overview.mdx). It contains a collection of queries and mutation built on `@tanstack/react-query` that lets you interact with the Medusa backend.
|
||||
|
||||
:::note
|
||||
|
||||
Make sure to also install the Medusa React package first if you’re intending to use it, as explained in the [Medusa React guide](../medusa-react/overview.mdx).
|
||||
|
||||
:::
|
||||
|
||||
For example, you can retrieve available products and display them in your route:
|
||||
|
||||
```tsx title=src/admin/routes/custom/page.tsx
|
||||
import { useAdminProducts } from "medusa-react"
|
||||
|
||||
const CustomPage = () => {
|
||||
const { products } = useAdminProducts()
|
||||
return (
|
||||
<div className="bg-white">
|
||||
{products?.map((product) => product.title)}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export default CustomPage
|
||||
```
|
||||
|
||||
### Custom Endpoints
|
||||
|
||||
You can also use `medusa-react` to interact with custom endpoints using [Custom Hooks utility functions](../medusa-react/overview.mdx#custom-hooks).
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Admin widgets](./widgets.md)
|
||||
- [Create a plugin for your admin customizations](../development/plugins/create.mdx)
|
||||
349
www/apps/docs/content/admin/setting-pages.md
Normal file
349
www/apps/docs/content/admin/setting-pages.md
Normal file
@@ -0,0 +1,349 @@
|
||||
---
|
||||
title: 'How to Create an Admin Setting Page'
|
||||
description: 'Learn how to create a new setting page in the admin dashboard.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
In this document, you’ll learn how to create a setting page in the admin.
|
||||
|
||||
## Overview
|
||||
|
||||
The [admin UI routes](./routes.md) allow you to add new pages to the admin dashboard. However, they can’t be used to add a new tab under the Setting page.
|
||||
|
||||
To do that, you need to create an Admin setting page. The page will automatically be shown as a tab under the Setting page in the admin. The tab leads to the content of your custom page.
|
||||
|
||||
A setting page is essentially a React Component created under the `src/admin/settings` directory.
|
||||
|
||||
This guide explains how to create a new setting page in the admin dashboard with some examples.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
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.
|
||||
|
||||
### (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.
|
||||
|
||||
This section provides recommended configurations to avoid any TypeScript errors.
|
||||
|
||||
:::note
|
||||
|
||||
These changes may already be available in your Medusa project. They're included here for reference purposes.
|
||||
|
||||
:::
|
||||
|
||||
First, update your `tsconfig.json` with the following configurations:
|
||||
|
||||
```json title=tsconfig.json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "es2019",
|
||||
"module": "commonjs",
|
||||
"allowJs": true,
|
||||
"checkJs": false,
|
||||
"jsx": "react-jsx",
|
||||
"declaration": true,
|
||||
"outDir": "./dist",
|
||||
"rootDir": "./src",
|
||||
"experimentalDecorators": true,
|
||||
"emitDecoratorMetadata": true,
|
||||
"noEmit": false,
|
||||
"strict": false,
|
||||
"moduleResolution": "node",
|
||||
"esModuleInterop": true,
|
||||
"resolveJsonModule": true,
|
||||
"skipLibCheck": true,
|
||||
"forceConsistentCasingInFileNames": true
|
||||
},
|
||||
"include": ["src/"],
|
||||
"exclude": [
|
||||
"dist",
|
||||
"build",
|
||||
".cache",
|
||||
"tests",
|
||||
"**/*.spec.js",
|
||||
"**/*.spec.ts",
|
||||
"node_modules",
|
||||
".eslintrc.js"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The important changes to note here are the inclusion of the field `"jsx": "react-jsx"` and the addition of `"build"` and `“.cache”` to `exclude`.
|
||||
|
||||
The addition of `"jsx": "react-jsx"` specified how should TypeScript transform JSX, and excluding `build` and `.cache` ensures that TypeScript ignores build and development files.
|
||||
|
||||
Next, create the file `tsconfig.server.json` with the following content:
|
||||
|
||||
```json title=tsconfig.server.json
|
||||
{
|
||||
"extends": "./tsconfig.json",
|
||||
"compilerOptions": {
|
||||
/* Emit a single file with source maps instead of having a separate file. */
|
||||
"inlineSourceMap": true
|
||||
},
|
||||
"exclude": ["src/admin", "**/*.spec.js"]
|
||||
}
|
||||
```
|
||||
|
||||
This is the configuration that will be used to transpile your custom backend code, such as services or entities. The important part is that it excludes `src/admin` as that is where your Admin code will live.
|
||||
|
||||
Finally, create the file `tsconfig.admin.json` with the following content:
|
||||
|
||||
```json title=tsconfig.admin.json
|
||||
{
|
||||
"extends": "./tsconfig.json",
|
||||
"compilerOptions": {
|
||||
"module": "esnext"
|
||||
},
|
||||
"include": ["src/admin"],
|
||||
"exclude": ["**/*.spec.js"]
|
||||
}
|
||||
```
|
||||
|
||||
This is the configuration that will be used when transpiling your admin code.
|
||||
|
||||
---
|
||||
|
||||
## Create the Setting Page
|
||||
|
||||
In this section, you’ll learn the basics of creating an admin UI route.
|
||||
|
||||
### Step 1: Create File
|
||||
|
||||
Custom admin setting pages are added under the `src/admin/settings` directory of your Medusa project. The path of the file depends on the path you want the setting page to be available under. It is based on [Next.js 13’s App Router](https://nextjs.org/docs/app/building-your-application/routing/defining-routes).
|
||||
|
||||
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.
|
||||
|
||||
For example, you can create the file `src/admin/settings/custom/page.tsx` with the following content:
|
||||
|
||||
```tsx title=src/admin/settings/custom/page.tsx
|
||||
import type { SettingConfig } from "@medusajs/admin"
|
||||
import { CustomIcon } from "../../icons/custom"
|
||||
|
||||
const CustomSettingPage = () => {
|
||||
return (
|
||||
<div>
|
||||
<h1>Custom Setting Page</h1>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export const config: SettingConfig = {
|
||||
card: {
|
||||
label: "Custom",
|
||||
description: "Manage your custom settings",
|
||||
// optional
|
||||
icon: CustomIcon,
|
||||
},
|
||||
}
|
||||
|
||||
export default CustomSettingPage
|
||||
```
|
||||
|
||||
This creates a setting page that will be available at `/a/settings/custom`. The content of the page is defined in the exported React component.
|
||||
|
||||
The exported configuration also indicates the details of the tab that will be added to the Setting page. You must specify a label and description, and you can optionally specify an icon. The icon is a React component.
|
||||
|
||||
### Step 3: Test it Out
|
||||
|
||||
To test your admin setting page, run the following command in the root directory of the Medusa backend project:
|
||||
|
||||
```bash
|
||||
npx medusa develop
|
||||
```
|
||||
|
||||
This will build your admin and opens a window in your default browser to `localhost:7001`. After you log in, go to `localhost:7001/a/settings`. You’ll find a new tab available under a new Extensions section.
|
||||
|
||||
If you click on the tab, a new page will open with the content as defined in your React component.
|
||||
|
||||
---
|
||||
|
||||
## Setting Page Props
|
||||
|
||||
Every route receives props of the type `RouteProps`, which includes the `notify` prop. The `notify` prop is an object that includes the following attributes:
|
||||
|
||||
- `success`: a function that can be used to show a success message.
|
||||
- `error`: a function that can be used to show an error message.
|
||||
- `warn`: a function that can be used to show a warning message.
|
||||
- `info`: a function that can be used to show an info message.
|
||||
|
||||
For example:
|
||||
|
||||
```tsx title=src/admin/settings/custom/page.tsx
|
||||
import type { SettingConfig } from "@medusajs/admin"
|
||||
import type { SettingProps } from "@medusajs/admin"
|
||||
|
||||
const CustomSettingPage = ({
|
||||
notify,
|
||||
}: SettingProps) => {
|
||||
|
||||
const handleClick = () => {
|
||||
notify.success("Success", "You clicked the button")
|
||||
}
|
||||
|
||||
return (
|
||||
<div>
|
||||
<h1>Custom Setting Page</h1>
|
||||
<button onClick={handleClick}>
|
||||
Click Me
|
||||
</button>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export const config: SettingConfig = {
|
||||
card: {
|
||||
label: "Custom",
|
||||
description: "Manage your custom settings",
|
||||
},
|
||||
}
|
||||
|
||||
export default CustomSettingPage
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Styling Setting Page
|
||||
|
||||
Admin setting pages support [Tailwind CSS](https://tailwindcss.com/) by default.
|
||||
|
||||
For example, to customize the style of your custom setting page:
|
||||
|
||||
<!-- eslint-disable max-len -->
|
||||
|
||||
```tsx title=src/admin/settings/custom/page.tsx
|
||||
import type { SettingConfig } from "@medusajs/admin"
|
||||
|
||||
const CustomSettingPage = () => {
|
||||
return (
|
||||
<div
|
||||
className="bg-white p-8 border border-gray-200 rounded-lg"
|
||||
>
|
||||
<h1>Custom Setting Page</h1>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export const config: SettingConfig = {
|
||||
card: {
|
||||
label: "Custom",
|
||||
description: "Manage your custom settings",
|
||||
},
|
||||
}
|
||||
|
||||
export default CustomSettingPage
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Use Routing Functionalities
|
||||
|
||||
If you want to use routing functionalities such as linking to another page or navigating between pages, you can use `react-router-dom`'s utility hooks and functions.
|
||||
|
||||
:::note
|
||||
|
||||
💡 `react-router-dom` is available as one of the `@medusajs/admin` dependencies. You can also install it within your project using the following command:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install react-router-dom
|
||||
```
|
||||
|
||||
If you're installing it in a plugin with admin customizations, make sure to include it in `peerDependencies`.
|
||||
|
||||
:::
|
||||
|
||||
For example, to add a link to another page:
|
||||
|
||||
```tsx title=src/admin/settings/custom/page.tsx
|
||||
import type { SettingConfig } from "@medusajs/admin"
|
||||
import { Link } from "react-router-dom"
|
||||
|
||||
const CustomSettingPage = () => {
|
||||
return (
|
||||
<div>
|
||||
<h1>Custom Setting Page</h1>
|
||||
<Link to={"/a/products"}>
|
||||
View Products
|
||||
</Link>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export const config: SettingConfig = {
|
||||
card: {
|
||||
label: "Custom",
|
||||
description: "Manage your custom settings",
|
||||
},
|
||||
}
|
||||
|
||||
export default CustomSettingPage
|
||||
```
|
||||
|
||||
View [react-router-dom’s documentation](https://reactrouter.com/en/main) for other available components and hooks.
|
||||
|
||||
---
|
||||
|
||||
## Querying and Mutating Data
|
||||
|
||||
You might need to interact with the Medusa backend from your admin setting page. To do so, you can utilize the Medusa React package. It contains a collection of queries and mutations built on `@tanstack/react-query` that lets you interact with the Medusa backend.
|
||||
|
||||
:::note
|
||||
|
||||
Make sure to also install the Medusa React package first if you’re intending to use it, as explained in the Medusa React guide.
|
||||
|
||||
:::
|
||||
|
||||
For example, you can retrieve available products and display them in your route:
|
||||
|
||||
```tsx title=src/admin/settings/custom/page.tsx
|
||||
import type { SettingConfig } from "@medusajs/admin"
|
||||
import { useAdminProducts } from "medusa-react"
|
||||
|
||||
const CustomSettingPage = () => {
|
||||
const { products } = useAdminProducts()
|
||||
|
||||
return (
|
||||
<div>
|
||||
<h1>Custom Setting Page</h1>
|
||||
<div className="bg-white">
|
||||
{products?.map((product) => product.title)}
|
||||
</div>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export const config: SettingConfig = {
|
||||
card: {
|
||||
label: "Custom",
|
||||
description: "Manage your custom settings",
|
||||
},
|
||||
}
|
||||
|
||||
export default CustomSettingPage
|
||||
```
|
||||
|
||||
### Custom Endpoints
|
||||
|
||||
You can also use `medusa-react` to interact with custom endpoints using [Custom Hooks utility functions](../medusa-react/overview.mdx#custom-hooks).
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Admin widgets](./widgets.md)
|
||||
- [Create a plugin for your admin customizations](../development/plugins/create.mdx)
|
||||
1282
www/apps/docs/content/admin/widgets.md
Normal file
1282
www/apps/docs/content/admin/widgets.md
Normal file
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user