Skip to main content

How to Create an Admin UI Routebeta

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/routesCopy to Clipboard directory.

This guide explains how to create a new route 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 to install a Medusa project.

Furthermore, Admin UI Routes are currently available as a beta feature. So, you must install the betaCopy to Clipboard version of the @medusajs/adminCopy to Clipboard and @medusajs/medusaCopy to Clipboard packages:

yarn add @medusajs/admin@beta @medusajs/medusa@beta
Report Incorrect CodeCopy to Clipboard

(Optional) TypeScript Preparations​

Since routes are React components, they should be written in .tsxCopy to Clipboard or .jsxCopy to Clipboard 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.

These changes may already be available in your Medusa project. They're included here for reference purposes.

First, update your tsconfig.jsonCopy to Clipboard with the following configurations:

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"
  ]
}
Report Incorrect CodeCopy to Clipboard

The important changes to note here are the inclusion of the field "jsx": "react-jsx"Copy to Clipboard and the addition of "build"Copy to Clipboard and “.cache”Copy to Clipboard to excludeCopy to Clipboard.

The addition of "jsx": "react-jsx"Copy to Clipboard specified how should TypeScript transform JSX, and excluding buildCopy to Clipboard and .cacheCopy to Clipboard ensures that TypeScript ignores build and development files.

Next, create the file tsconfig.server.jsonCopy to Clipboard with the following content:

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"]
}
Report Incorrect CodeCopy to Clipboard

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/adminCopy to Clipboard as that is where your Admin code will live.

Finally, create the file tsconfig.admin.jsonCopy to Clipboard with the following content:

tsconfig.admin.json
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "module": "esnext"
  },
  "include": ["src/admin"],
  "exclude": ["**/*.spec.js"]
}
Report Incorrect CodeCopy to Clipboard

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/routesCopy to Clipboard 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.

For example, if you want the route to be available in the admin dashboard under the path /a/customCopy to Clipboard you should create your admin route under the path src/admin/routes/custom/page.tsxCopy to Clipboard.

All admin routes are prefixed with /aCopy to Clipboard by default.

You can also create dynamic routes. For example, you can create the route /a/custom/[id]Copy to Clipboard by creating an admin router under the path src/admin/routes/custom/[id]/page.tsxCopy to Clipboard.

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.tsxCopy to Clipboard with the following content:

src/admin/routes/custom/page.tsx
const CustomPage = () => {
  return (
    <div>
      This is my custom route
    </div>
  )
}

export default CustomPage
Report Incorrect CodeCopy to Clipboard

Step 3: Test it Out​

To test your admin UI route, run the following command in the root directory of the Medusa backend project:

npx @medusajs/medusa-cli develop
Report Incorrect CodeCopy to Clipboard

This will build your admin and opens a window in your default browser to localhost:7001Copy to Clipboard. After you log in, if you go to localhost:7001/a/customCopy to Clipboard, you’ll find the page you just created.

When using the developCopy to Clipboard 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.

Show Route in Sidebar​

You can add your routes into the admin dashboard sidebar by exporting an object of type RouteConfigCopy to Clipboard import from @medusajs/adminCopy to Clipboard in the same route file.

The object has one property linkCopy to Clipboard, which is an object having the following properties:

  • labelCopy to Clipboard: a string indicating the sidebar item’s label of your custom route.
  • iconCopy to Clipboard: 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:

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
Report Incorrect CodeCopy to Clipboard

Retrieve Path Parameters​

As mentioned earlier, you can create dynamic routes like /a/custom/[id]Copy to Clipboard by creating a route file at the path src/admin/routes/custom/[id]/page.tsxCopy to Clipboard.

To retrieve the path parameter, you can use the useParams hook retrieved from the react-router-dom package.

react-router-domCopy to Clipboard is available as one of the @medusajs/adminCopy to Clipboard dependencies. You can also install it within your project using the following command:

yarn add react-router-dom
Report Incorrect CodeCopy to Clipboard

If you're installing it in a plugin with admin customizations, make sure to include it in peerDependenciesCopy to Clipboard.

For example:

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
Report Incorrect CodeCopy to Clipboard

Routing Functionalities​

If you want to use routing functionalities such as linking to another page or navigating between pages, you can use react-router-domCopy to Clipboard's utility hooks and functions.

For example, to add a link to another page:

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
Report Incorrect CodeCopy to Clipboard

View react-router-dom’s documentation for other available components and hooks.

Styling Route​

Admin UI routes support Tailwind CSS by default.

For example, to customize your custom route:

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
Report Incorrect CodeCopy to Clipboard

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. It contains a collection of queries and mutation built on @tanstack/react-queryCopy to Clipboard that lets you interact with the Medusa backend.

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:

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
Report Incorrect CodeCopy to Clipboard

You can also use medusa-reactCopy to Clipboard to interact with custom endpoints using the createCustomAdminHooks utility function.

See Also​

Was this page helpful?
© 2023 Medusa, Inc. All rights reserved.