Announcing Admin Extensions

Medusa is introducing Admin Extensibility in public beta to enable easy customization of Medusa's Admin dashboard. With Admin Extensibility, developers can create Widgets with custom React components that enrich the merchant experience through additional context and tailored workflows.

Admin Extensibility is a big addition to Medusa's capabilities for supporting rich digital commerce applications. With the launch of our public beta, we hope to give developers more power when solving commerce problems, and we would love to hear your feedback on further improving the feature.

How Widgets work

Widgets allow developers to add custom React components in injection zones spread across existing pages in the Admin Dashboard. For example, you can add a button on the order details page that links to the order in an integrated ERP system.

Widgets are easy to build, and Medusa automatically registers them when exporting a React component and its configuration from files placed in the Copy to clipboardsrc/admin/widgets directory in your project or plugins.

For example, you can add a link to an ERP system in your order details page with the following widget:

12345678910111213141516
// my-plugin/src/admin/widgets/erp-button.tsx

import type { WidgetConfig } from "@medusajs/admin"

export default ({ order }) => {
  const link = `https://myerp.com/orders/${order.id}`
  return (
    <a href={link}>
        View in MyERP
    </a>
  )
}

export const config: WidgetConfig = {
  zone: "order.details.after"
}

Widgets can be placed on most existing pages in the Admin Dashboard, and often there are multiple zones within each page.

You can learn more about widgets in our documentation.

Admin UI Routes

Another aspect of admin extensions that we’re introducing is Admin UI Routes. You’ll be able to add new routes into your admin dashboard in routes similar to Next.js 13 routes.

Similar to Widgets, Admin UI Routes are simply exported React components created in files under the Copy to clipboardsrc/admin/routes directory. You can also specify that these routes can be added into the sidebar.

For example, you can add a new “Custom Route” link into the sidebar by creating the following component:

123456789101112131415161718192021
// 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

You can learn more about Admin UI Routes in our documentation.

Enhanced Developer Experience

An important constraint for our work when building Admin Extensibility was ensuring a great development workflow.

As mentioned, we are therefore introducing the Copy to clipboardsrc/admin/widgets and Copy to clipboardsrc/admin/routes directories as new special directories in Medusa plugins and projects. The Medusa core automatically scans for valid Widgets and Admin UI Routes during build time, ensuring that you don’t have to battle with configuration files and can get straight to solving the important problems you are working on.

Additionally, we extended the Copy to clipboardmedusa develop command used to start your development server. We now listen for changes in the Copy to clipboardsrc/admin folder and hot reload your dashboard, so you can instantly view your changes as you build new Widgets and Admin UI Routes.

Shipping admin extensions in plugins

Widgets and UI Routes can ship together with plugins, adding a new dimension to their capabilities. For example, we have added a Widget to the Stripe plugin that shows additional data like fraud evaluation on your order details page when the plugin is installed.

To ship Admin extensions with plugins, plugin developers need to run the bundle command from Copy to clipboard@medusajs/admin and Medusa will then automatically pick up the customization upon installation:

1
medusa-admin bundle

When installing plugins you can specify in your Copy to clipboardmedusa-config.js file whether you want a plugin’s Admin extensions injected in your dashboard or not to ensure you are always in control of the merchant experience. Opting in to admin extensions is done with the Copy to clipboardenableUI option:

1234567891011121314
// medusa-config.js

module.export = {
  ...,
  plugins: [
    {
       resolve: "medusa-payment-stripe",
       options: {
         ...,
         enableUI: true,
       }
    }
  ]
}

You can learn more about creating plugins including admin extensions in our documentation.

What’s Next?

Admin extensions are still in beta, so we will continue on improving this feature to make it stable and provide a better developer experience.

We are also excited to see what you will build with the new Admin Extensibility feature and as we continue improving the feature, we would love to hear your feedback.

If you want to learn more about Admin Extensibility, check out the docs here.

You can also visit our Discord or GitHub Discussions to provide feedback on the feature.