api-ref: custom API reference (#4770)
* initialized next.js project * finished markdown sections * added operation schema component * change page metadata * eslint fixes * fixes related to deployment * added response schema * resolve max stack issue * support for different property types * added support for property types * added loading for components * added more loading * type fixes * added oneOf type * removed console * fix replace with push * refactored everything * use static content for description * fixes and improvements * added code examples section * fix path name * optimizations * fixed tag navigation * add support for admin and store references * general enhancements * optimizations and fixes * fixes and enhancements * added search bar * loading enhancements * added loading * added code blocks * added margin top * add empty response text * fixed oneOf parameters * added path and query parameters * general fixes * added base path env variable * small fix for arrays * enhancements * design enhancements * general enhancements * fix isRequired * added enum values * enhancements * general fixes * general fixes * changed oas generation script * additions to the introduction section * added copy button for code + other enhancements * fix response code block * fix metadata * formatted store introduction * move sidebar logic to Tags component * added test env variables * fix code block bug * added loading animation * added expand param + loading * enhance operation loading * made responsive + improvements * added loading provider * fixed loading * adjustments for small devices * added sidebar label for endpoints * added feedback component * fixed analytics * general fixes * listen to scroll for other headings * added sample env file * update api ref files + support new fields * fix for external docs link * added new sections * fix last item in sidebar not showing * move docs content to www/docs * change redirect url * revert change * resolve build errors * configure rewrites * changed to environment variable url * revert changing environment variable name * add environment variable for API path * fix links * fix tailwind settings * remove vercel file * reconfigured api route * move api page under api * fix page metadata * fix external link in navigation bar * update api spec * updated api specs * fixed google lint error * add max-height on request samples * add padding before loading * fix for one of name * fix undefined types * general fixes * remove response schema example * redesigned navigation bar * redesigned sidebar * fixed up paddings * added feedback component + report issue * fixed up typography, padding, and general styling * redesigned code blocks * optimization * added error timeout * fixes * added indexing with algolia + fixes * fix errors with algolia script * redesign operation sections * fix heading scroll * design fixes * fix padding * fix padding + scroll issues * fix scroll issues * improve scroll performance * fixes for safari * optimization and fixes * fixes to docs + details animation * padding fixes for code block * added tab animation * fixed incorrect link * added selection styling * fix lint errors * redesigned details component * added detailed feedback form * api reference fixes * fix tabs * upgrade + fixes * updated documentation links * optimizations to sidebar items * fix spacing in sidebar item * optimizations and fixes * fix endpoint path styling * remove margin * final fixes * change margin on small devices * generated OAS * fixes for mobile * added feedback modal * optimize dark mode button * fixed color mode useeffect * minimize dom size * use new style system * radius and spacing design system * design fixes * fix eslint errors * added meta files * change cron schedule * fix docusaurus configurations * added operating system to feedback data * change content directory name * fixes to contribution guidelines * revert renaming content * added api-reference to documentation workflow * fixes for search * added dark mode + fixes * oas fixes * handle bugs * added code examples for clients * changed tooltip text * change authentication to card * change page title based on selected section * redesigned mobile navbar * fix icon colors * fix key colors * fix medusa-js installation command * change external regex in algolia * change changeset * fix padding on mobile * fix hydration error * update depedencies
This commit is contained in:
Shahed Nasser authored and 
GitHub committed
1 parent
16249ec280
commit
914d773d3a
3270 files changed
+22075
-192064
No files matched your search
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,225 @@
|
||||
---
|
||||
description: "Learn how to install Medusa's admin dashboard. The admin dashboard gives merchants an easy-to-use interface to manage their data such as orders, products, regions, and more."
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
import Feedback from '@site/src/components/Feedback';
|
||||
import Troubleshooting from '@site/src/components/Troubleshooting'
|
||||
import AdminLoginSection from '../troubleshooting/signing-in-to-admin.md'
|
||||
import CorsSection from '../troubleshooting/cors-issues.md'
|
||||
|
||||
# Admin Dashboard Quickstart
|
||||
|
||||
This document will guide you through setting up the admin dashboard in the Medusa backend.
|
||||
|
||||
## Overview
|
||||
|
||||
The admin dashboard is installed on the Medusa backend. The admin dashboard starts when you start the Medusa backend. This also means you can later deploy the Medusa backend along with the admin dashboard on the same hosting.
|
||||
|
||||
This guide will explain the steps and configurations required to set up the admin dashboard.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Medusa Backend
|
||||
|
||||
As the admin dashboard is a plugin installed on the Medusa Backend, you must have a Medusa Backend installed first. You can learn how to install it in [this documentation](../development/backend/install.mdx).
|
||||
|
||||
### Node.js
|
||||
|
||||
The Admin uses [Vite v4.1.4](https://vitejs.dev/guide/#scaffolding-your-first-vite-project) which requires v14.8+ or v16+ of Node.js, and as Medusa requires v16 or greater it's recommended you use v16+ of Node.js.
|
||||
|
||||
You can check which version of Node you have by running the following command:
|
||||
|
||||
```bash noReport
|
||||
node -v
|
||||
```
|
||||
|
||||
You can install Node from the [official website](https://nodejs.org/en/).
|
||||
|
||||
---
|
||||
|
||||
## Install and Serve Admin with the Backend
|
||||
|
||||
This section explains how to install the admin to be served with the Medusa Backend and later deployed together.
|
||||
|
||||
### Step 1: Install the Package
|
||||
|
||||
In the directory of your Medusa backend, run the following command to install admin dashboard:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/admin
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
Installing the `@beta` version of the admin and Medusa core allows you to perform customizations such as creating [Admin Widgets](./widgets.md) or [Admin Dashboard Routes](./routes.md). You can install the `beta` version with the following command:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/admin@beta @medusajs/medusa@beta
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### Step 2: Add Admin to Medusa Configurations
|
||||
|
||||
In `medusa-config.js`, add the admin plugin into the array of `plugins`:
|
||||
|
||||
```js title=medusa-config.js
|
||||
const plugins = [
|
||||
// ...
|
||||
{
|
||||
resolve: "@medusajs/admin",
|
||||
/** @type {import('@medusajs/admin').PluginOptions} */
|
||||
options: {
|
||||
// ...
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
The plugin accepts the following options:
|
||||
|
||||
1. `serve`: (default: `true`) a boolean indicating whether to serve the admin dashboard when the Medusa backend starts. If set to `false`, you can serve the admin dashboard using the [dev command](#dev-command-options).
|
||||
2. `path`: (default: `app`) a string indicating the path the admin server should run on when [running the Medusa backend in production](#note-on-admin-path). It shouldn't be prefixed or suffixed with a slash `/`, and it can't be one of the reserved paths: "admin" and "store".
|
||||
3. `outDir`: Optional path for where to output the admin build files.
|
||||
4. `autoRebuild`: (default: `false`) a boolean indicating whether the admin UI should be rebuilt if there are any changes or if a missing build is detected when the backend starts. If not set, you must [manually build the admin dashboard](#build-command-options).
|
||||
|
||||
### Optional: Manually Building Admin Dashboard
|
||||
|
||||
If you have `autoRebuild` disabled, you must build your admin dashboard before starting the Medusa backend. Refer to the [build command](#build-command-options) for more details.
|
||||
|
||||
### Step 3: Test the Admin Dashboard
|
||||
|
||||
:::tip
|
||||
|
||||
If you disabled the `serve` option, you need to run the admin dashboard separately using the [dev command](#dev-command-options)
|
||||
|
||||
:::
|
||||
|
||||
You can test the admin dashboard by running the following command in the directory of the Medusa backend:
|
||||
|
||||
```bash
|
||||
npx medusa develop
|
||||
```
|
||||
|
||||
This starts the Medusa Backend and the admin dashboard. By default, the admin will be available on the URL `localhost:9000/app`. If you set the path option, then the admin will be available on `localhost:9000/<PATH>` with `<PATH>` being the value of the path option.
|
||||
|
||||
:::note
|
||||
|
||||
If you're using the `@beta` version of the admin plugin, the admin dashboard will run on `localhost:7001` when you run the `develop` command.
|
||||
|
||||
:::
|
||||
|
||||
<Feedback
|
||||
event="survey_admin_quickstart"
|
||||
question="Did you set up the admin successfully?"
|
||||
positiveQuestion="Is there anything that should improved?"
|
||||
negativeQuestion="Please describe the issue you faced."
|
||||
/>
|
||||
|
||||
---
|
||||
|
||||
## Demo Credentials
|
||||
|
||||
If you installed the demo data when you installed the Medusa backend by running:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run seed
|
||||
```
|
||||
|
||||
You can use the email `admin@medusa-test.com` and password `supersecret` to log in.
|
||||
|
||||
:::info
|
||||
|
||||
Passwords in Medusa are hashed using the [scrypt-kdf](https://www.npmjs.com/package/scrypt-kdf). The password hash is then stored in the database.
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Create a New Admin User
|
||||
|
||||
To create a new admin user from the command line, run the following command in the directory holding your Medusa backend:
|
||||
|
||||
```bash
|
||||
npx medusa user -e some@email.com -p some-password
|
||||
```
|
||||
|
||||
This will create a new user that you can use to log into your admin panel.
|
||||
|
||||
---
|
||||
|
||||
## Build Command Options
|
||||
|
||||
The `build` command in the admin CLI allows you to manually build the admin dashboard. If you intend to use it, you should typically add it to the `package.json` of the Medusa backend:
|
||||
|
||||
```json title=package.json
|
||||
{
|
||||
"scripts": {
|
||||
// other scripts...
|
||||
"build:admin": "medusa-admin build"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can add the following options to the `medusa-admin build` command:
|
||||
|
||||
- `--deployment`: a boolean value indicating that the build should be ready for deployment. When this option is added, options are not loaded from `medusa-config.js` anymore, and it means the admin will be built to be hosted on an external host. For example, `medusa-admin build --deployment`.
|
||||
- `--backend` or `-b`: a string specifying the URL of the Medusa backend. This can be useful with the `--deployment` option. The default here is the value of the environment variable `MEDUSA_BACKEND_URL`. For example, `medusa-admin build --deployment --backend example.com`
|
||||
- `--out-dir` or `-o`: a string specifying a custom path to output the build files to. By default, it will be the `build` directory. For example, `medusa-admin --deployment --out-dir public`.
|
||||
- `--include` or `-i`: a list of strings of paths to files you want to include in the build output. It can be useful if you want to inject files that are relevant to your external hosting, such as adding a `200.html` file that is needed for redirects on Surge. For example, `medusa-admin --deployment --include 200.html`
|
||||
- `--include-dist` or `-d`: a string specifying the path to copy the files specified in `--include` to. By default, the files are copied to the root of the build directory. You can use this option to change that. For example, `medusa-admin --deployment --include 200.html --include-dist static`.
|
||||
|
||||
---
|
||||
|
||||
## Dev Command Options
|
||||
|
||||
The `dev` command in the admin CLI allows you to run the admin dashboard in development separately from the Medusa backend. If you intend to use it, you should typically add it to the `package.json` of the Medusa backend:
|
||||
|
||||
```json title=package.json
|
||||
{
|
||||
"scripts": {
|
||||
// other scripts...
|
||||
"dev:admin": "medusa-admin dev"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can add the following options to the `medusa-admin dev` command:
|
||||
|
||||
- `--backend` or `-b`: a string specifying the URL of the Medusa backend. By default, it's the value of the environment variable `MEDUSA_BACKEND_URL`. For example, `medusa-admin dev --backend example.com`.
|
||||
- `--port` or `-p`: the port to run the admin on. By default, it's `7001`. For example, `medusa-admin dev --port 8000`.
|
||||
|
||||
---
|
||||
|
||||
## Admin User Guide
|
||||
|
||||
The admin dashboard provides a lot of ecommerce features including managing Return Merchandise Authorization (RMA) flows, store settings, products, orders, and much more.
|
||||
|
||||
You can learn more about the admin dashboard and its features in the [User Guide](../user-guide.mdx).
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Installation
|
||||
|
||||
<Troubleshooting
|
||||
sections={[
|
||||
{
|
||||
title: 'Signing into Admin',
|
||||
content: <AdminLoginSection />
|
||||
},
|
||||
{
|
||||
title: 'CORS Errors',
|
||||
content: <CorsSection />
|
||||
}
|
||||
]}
|
||||
/>
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Admin widgets](./widgets.md)
|
||||
- [Admin UI routes](./routes.md)
|
||||
@@ -0,0 +1,377 @@
|
||||
---
|
||||
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.
|
||||
|
||||
## 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.
|
||||
|
||||
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.
|
||||
|
||||
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-ui"
|
||||
|
||||
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)
|
||||
@@ -0,0 +1,352 @@
|
||||
---
|
||||
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.
|
||||
|
||||
## 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.
|
||||
|
||||
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.
|
||||
|
||||
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`.
|
||||
|
||||
### 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-ui"
|
||||
|
||||
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)
|
||||
File diff suppressed because it is too large.
Load diff
Reference in new issue
Block a user