diff --git a/docs/content/admin/routes.md b/docs/content/admin/routes.md index 0479d4fed8..a1e5d715ca 100644 --- a/docs/content/admin/routes.md +++ b/docs/content/admin/routes.md @@ -17,6 +17,12 @@ An admin UI route is essentially a React Component created under the `src/admin/ 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 @@ -150,6 +156,8 @@ const CustomPage = () => { 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: @@ -239,7 +247,9 @@ const CustomPage = () => { export default CustomPage ``` -### Routing Functionalities +--- + +## 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. @@ -316,7 +326,7 @@ const CustomPage = () => { export default CustomPage ``` -You can also use `medusa-react` to interact with custom endpoints using the [createCustomAdminHooks utility function](../medusa-react/overview.mdx#custom-hooks). +You can also use `medusa-react` to interact with custom endpoints using [Custom Hooks utility functions](../medusa-react/overview.mdx#custom-hooks). --- diff --git a/docs/content/admin/setting-pages.md b/docs/content/admin/setting-pages.md new file mode 100644 index 0000000000..5a4ea085aa --- /dev/null +++ b/docs/content/admin/setting-pages.md @@ -0,0 +1,305 @@ +--- +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 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. + +An admin UI route 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 an admin route 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 ( +