Admin Extensibility

[kasperkristensen]

Preface

This feature is still under development and will likely change as we continue to work on it over the coming weeks. It should not be seen as a finalized feature in any way. We are sharing this early stage preview because we are very interested in getting feedback from users. We want to hear about your potential use cases for admin extensibility and what you would like to see as part of this feature.

Please note that the first iteration will have limited extension capabilities. This means that developers will not be able to fully extend, customize, or replace all parts of the existing admin. Instead, the first iteration will be limited to injecting Widgets into the edit pages, list pages, and the login page.

This document will be updated if changes are made to the feature.

Abstract

This feature aims to enable developers to extend the admin dashboard both through local extensions written in their server directory, and through plugins. Developers should be able to hook into predetermined parts of the admin, such as adding a widget to the product details page or creating an entirely new page.

Motivation

Currently, developers have to either fork and customize their admin dashboard or create a separate dashboard to manage any custom logic they have introduced to their Medusa server. However, this is not a very scalable solution because it is difficult to maintain these customizations while also pulling upstream changes to the admin dashboard.

To address this issue, we are introducing admin extensibility. Our goal is to provide developers with a clear and streamlined way to add support for their custom logic in the admin dashboard, without the added burden of maintaining a fork or separate dashboards.

Goals

1. Developers should be able to extend the admin dashboard.
2. Extensions can be added either directly in the backend directory or by using plugins.
3. Extensions should be contained to prevent them from breaking the existing admin UI.
4. Developers should have a simple DX with no requirement for knowledge of build tooling when creating extensions.

Proposal

Widgets

A widget is a section that can be injected into an existing page of the current dashboard, where these widgets can be injected is determined by a list of valid injectionZones. Some examples of these zones are product.details, order.list, customer.details, login.

Based on the injectionZone the Widget will be rendered in the correct place in the dashboard.

Widgets with the InjectionZone customer.details will be rendered in the outlined area.

List of supported InjectionZones, note that these zones are preliminary and may change:

• product.details (/a/products/:id)
• product.list (/a/products)
• product_collection.details (/a/collections/:id)
• product_collection.list (/a/products collection view)
• customer.details (/a/customers/:id)
• customer.list (/a/customers)
• customer_group.details (/a/customers/:id)
• customer_group.list (/a/customers/groups/:id)
• discount.details (/a/discounts/:id)
• discount.list (/a/discounts)
• order.details (/a/orders/:id)
• order.list (/a/orders)
• draft_order.details (/a/draft-orders/:id)
• draft_order.list (/a/draft-orders)
• price_list.details (/a/pricing/:id)
• price_list.list (/a/pricing)
• gift_card.details (/a/gift-cards/manage)
• gift_card.list (/a/gift-cards)
• custom_gift_card (/a/gift-cards/:id)
• login.before (/login above inputs)
• login.after (/login below inputs)

Creating a Widget

Widgets can be defined in any .{tsx|jsx} file located within the src/admin folder. For the widget to be registered correctly, it needs to be passed to a special helper function called extend. This function must be the default export of the src/admin/index.{ts|js} file.

// src/admin/product-restock-widget.tsx
import { ProductWidgetProps } "@medusajs/admin-sdk"
import { createCustomAdminHooks } from "medusa-react"
import {
  AdminListRestockNotificationQuery,
  AdminListRestockNotificationRes,
} from "../../types";

export const ProductRestockWidget = ({ product }: ProductWidgetProps) => {
	const {
	  useAdminEntities,
	} = createCustomAdminHooks(
	  "restock-notifications",
	  "admin_restock_notifications"
	);

	const { data } = useAdminEntities<
	    AdminListRestockNotificationQuery,
	    AdminListRestockNotificationRes
	  > ({
	    product_id: product.id,
	    expand: "variant,variant.product",
  });
	

  return (
		<div>
			{/* Render data */}
		</div>
  )
}

// src/admin/index.ts
import { extend } from "@medusajs/admin-sdk";
import { ProductRestockWidget } from "./product-restock-widget";

export default extend({
  identifier: "medusa-restock-notification",
  widgets: {
    product: {
      details: [
        {
          Component: ProductRestockWidget,
          name: "product-restock-widget",
        },
      ],
    },
  },
});

The extend function has a identifier parameter that indicates the origin of the extension. For local extensions, we recommend using an identifier like "local" to clearly indicate that the extension(s) come from the local server directory. Plugins should pass the same value as what is written in the name field of the package's package.json.

When adding a widget, it should be placed under the injection zone where you want the plugin to be rendered. In the example above, the widget should be rendered at product.details, so it is added to widgets.product.details. Injection zones accept an array of widgets, consisting of a Component and a name. The name should be unique so that it is easy to identify. This, combined with the identifier, is used to render an error message if a widget crashes during development.

Building an extension

To build extensions, use the @medusajs/admin-sdk CLI tool. This tool bundles the extension using Rollup, allowing it to be used within the admin dashboard. Our goal is to integrate this tool into the medusa-cli so that the workflow for working on local extensions remains the same as it is today when extending server logic. However, plugin maintainers will still need to run the command separately before releasing their plugin.

The build command is extensions build, and also supports building the extensions in watch mode by passing the flag -w.

How extensions are loaded

Extensions are loaded during the build step of the admin project. To find extensions, the admin build command searches for dist/admin/index.js in the developer's server directory and for node_modules/<plugin>/dist/admin/index.js for each plugin registered in the project's medusa-config.js file. Whether a developer works on local or plugin extensions, the folder structure is the same.

When the admin build command finds an extension, it writes the import path to a file that is then used to import all extensions into the dashboard. From here, the extensions are passed on to a context that is called at the various injection zones to render the extensions in their correct place.

const INJECTION_ZONE = "order.details"

const OrderDetails = () => {
	// ...
	const { order } = useAdminOrder("id")

	const { getWidgets } = useInjectionZones()

	const widgets = getWidgets(INJECTION_ZONE)

	return (
	<div>
		// ...
		{widgets.map((w, index) => {
			return (
				<WidgetContainer key={index} widget={w} entity={order} injectionZone={INJECTION_ZONE} />
			)
		})}
	</div>		
	)
}

Widgets are rendered within a WidgetContainer that serves two functions. First, it passes the appropriate props to the Widget, such as OrderWidgetProps in the example above. Second, it acts as an error boundary, preventing errors in an injected widget from crashing the entire Admin application. If an unhandled error is thrown within a Widget, the WidgetContainer shows an error notification in the UI. The notification provides details on which Widget (using name) crashed and the origin (identifier passed to extend) of the faulty widget (local or plugin).

Demo

A video demonstration is available at →
https://www.loom.com/share/f46f163f670c4640bf4a2f1859439a25

Source code for the demo is available at →
https://github.com/kasperkristensen/admin-widget-demo/tree/main

Current limitations

• The admin dev command is currently bugged, preventing extensions from running in a dev environment. This means that hot-reloading changes is not supported. Instead, you will need to rebuild extensions and then the admin to see changes take effect. We have updated the yarn start command to include this process, as well as restarting your server for a more convenient experience, while we work on fixing the development flow.

• Currently, extensions only support styling using tailwind. For the best developer experience, we recommend creating a barebones tailwind.config.js file at the root of your project and installing the Tailwind CSS IntelliSense VS Code plugin.

  Our plan for later this year is to ship a UI library. This will make it easier to create extensions that fit seamlessly into the look and feel of the dashboard. Additionally, we plan to allow users to pass custom Rollup config options to the extension build tool to support their preferred styling approach.

• Widgets are currently not rendered at any of the <domain>.list and login injection zones. They will be added in a later snapshot.

Roadmap

Below is a roadmap of future iterations for this feature. The first iteration is currently being worked on and will add support for widgets in the details pages of all domain detail pages, domain overview pages, and login page.

The following iterations will add support for new types of extensions:

Second Iteration

Support pages that allow developers to add new settings pages and new domain pages. Settings pages will render as a card in the settings overview and create a new page in the dashboard. New domain pages will render as a link in the sidebar and create a new page in the dashboard.

Third Iteration
Support replacing existing domains, domain sections, domain create flows, and setting pages

Related projects

We are also planning on shipping a UI library later this year that will make it easier to build extensions that fit in seamlessly with the existing admin. The current plan is to begin working on it simultaneously with the second and third iterations of extensibility and roll it continuously as components are ready.

[pevey]

All of this looks awesome!

One topic I want to throw out for comment:

In combination with this more user-friendly way of installing plugins, there would be a log of benefit to revamping how Medusa handles (1) config variables and (2) which packages are loaded as plugins.

1. Right now, the only way I know of to load config variables in services and routes is via the config file, which can also pull from env vars. In many extensible platforms like what Medusa is becoming, settings can also be set in the db itself. That is more user-friendly for less tech-savvy store owners who might want to install a plugin but are not comfortable editing js or yaml files. An expanded config concept in Medusa could open up the ability for a plugin to have a settings page and store those and access those from the admin only, with a nice UI and guidance for the user as to what each setting does. Using Magento as a reference, they have one config table where settings go, rather than each extension having its own way of saving settings.

2. Right now, I think Medusa only knows what node packages to attempt to load as plugins based on the config file. Similar to above, an alternate way of specifying this could lead to a more "click to install this plugin" experience, where users could browse available plugins right from a section of the Admin if they want.

Edit: Looking at the roadmap, it seems like some work on (1) settings is already there. I got over-excited and jumped the gun!

[tsvetann]

@kasperkristensen Thanks for the extensive overview and early info. Would the first iteration allow us also to replace some of the native widgets, which come bundled with the admin, with custom ones?

[kasperkristensen]

Hi @tsvetann,

No, the first iteration will only support adding new widgets. We are mainly focusing on nailing the DX around creating extensions. The current plan is to support replacing existing parts in the third iteration. While we expect the second iteration to be released very quickly after the first one, the third iteration will properly take a while longer, as in order for us to allow replacing existing code, we will need to update the core admin project to make sure it won't break when things get removed/replaced. This will likely require a pretty substantial rewrite, so it will most likely be a couple of months before we get to that point, unfortunately.

[octalpixel]

Love the direction where this is headed. I believe you can take inspiration from headless CMS like Strapi, Keystone and Payload CMS which follow a similar pattern (These are the one I have used, pretty sure there are more). Strapi might server as greater inspiration.

Any thoughts on how something like https://medusa-plugins.vercel.app/sentry/admin-ui would look like in the new RFC ?

[kasperkristensen]

Hi @octalpixel

Adriens plugin would be an ideal case for a page extension (which will most likely be part of the second release of this feature), where you would add a config along the lines of:

const SentryIcon = () => {
  return (
    <svg>...</svg>
  )
}

const Page = () => {
  return (
    <div>{/* Sentry UI */}</div>
  )
}

// ... load config
{
  page: Page
  path: "/sentry",
  title: "Sentry",
  icon: SentryIcon
}

Which would result in a new link being added to the sidebar with the SentryIcon and a title of "Sentry". Clicking the link would then take you to /a/sentry, which will render the Page. All of this would just go into the /src/admin folder of the Sentry plugin, and then if the user also has @medusajs/admin installed, the admin code will get injected into the admin dashboard.

[octalpixel]

hey @kasperkristensen so we are trying the new beta out and was wondering what would be the best to replace existing element ? Like in that admin pages, if one want to remove the raw products section, how can that be done or modified the UI for adding variants to a custom one?

[Extazykeep]

Some useful case of extend is a possibility to add new fields for product, for example short description, or possibility to add metadata for options from admin dashboard( this is both real examples of our needs in project).
Example miss word "from" when imports admin sdk:

// src/admin/product-restock-widget.tsx
import { ProductWidgetProps } "@medusajs/admin-sdk"

[AbuHafsa]

@kasperkristensen Great initiative to bring such feature into Medusa but I had a question regarding the building of these widgets. Is there a plan for providing a design system that we can use or do we have to be familiar with the admin UI repository and the components built there?

[ruanb7]

Hi @kasperkristensen ,
Thank you for the great overview! I like this. May I ask when this will be released? And is it already available for testing in beta? Where may I access it today or this week to start using it? 🤩🥲

[kleenkanteen]

Would be nice if there was a plugin that let the global admin choose whether users can access the admin dashboard. Users can then add products and see everything regarding only their own products. This would make it easy to create a marketplace.

[herawais]

There is no InjectionZone for Categories ?

[srindom]

Would you be up for opening a PR to add it? We would happily help see that land :)

[herawais]

yes, will start working on it

[robodove]

Any ETA on hot reloading while developing?

[robodove]

For anyone landing here:
We accepted that the medusa admin as a starter project and while the medusa team has been working hard to make it extensible, it lacks in customization in many places (which is okay!)

So we've decided to fork off the base, converted it to a NextJS App (which took a lot of time) and will now diverge from the main app

Hopefully the changes upstream won't be too heavy in the long run, but for now it seemed like the only option if we want to actually customize the admin (not just extend small bits)

[herawais]

@robodove can you please share repository?

[robodove]

No, no cross-development here.
Medusa Team has done an amazing job to give people the basics to get things started. I don't feel good about simply avoiding their decision-making processes and forking things off - especially since they are very responsive and open to discuss things.

Since Medusa right now is going through a quite radical shift in modularization, chances are high these changes will trickle down to the admin app in the long run. And hopefully we'll go back to the upstream core, so providing a repo would create unnecessary tension.

I just left that note here so people see that it is possible to fork on your own and develop the stuff you want on your own.

[WalobwaD]

medusa-admin eject -o

Says the eject command does not exist

[robodove]

Where did you get the idea that an eject command existed

edit: found it in the docs upgrade guide

Docs state:

Use the medusa-admin eject -o <output_directory> command to eject the Admin UI from the plugin and use it as a separate project. This way, you can make your customizations and deploy them to a separate hosting platform.

[awkward-minion]

Is there any way to use this to hide some menu items in left nav of admin dashboard ?

[NicolasGorga]

Hello,

The current implementation allows for customization but forces to use the Admin dashboard as it is shipped at all times (no way to hide left vertical tabs or navigate to a custom route after login).

I am trying to build a marketplace, so the Admin for me also needs to support Role Based Access Control, which with the current extensibility features i am only able to do by hacking my way around and forking the Admin UI.

To avoid this and support marketplaces, i think we should be provided out-of-the-box with features:

• Define a strategy for showing / hiding dashboard left vertical menu items based in user's role or other custom logic. Example: in marketplace i would do a limited functionality admin dashboard for Vendors, while a full access dashboard for Admins of the system like me
• Allow to specify the route to navigate after login based on custom logic. For example, when a Vendor first registers, they have a property is_verified set to false, so would need to define this logic as: if !user.is_verified then navigate to a route like /waiting-verification and otherwise, navigate to the dashboard (or any other route i could define)

Is anything like this been worked on now / in the near future?

[nyctonio]

can you tell me the hack that you are using currently.