Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 33 ยท Admin Customization

Admin Dashboard Extensions

Customize the Medusa Admin with React: widgets in injection zones, custom UI routes, settings pages, the @medusajs/ui components, data fetching with the JS SDK.

The Medusa Admin is a React single-page app that ships with Medusa, and you can extend it from the same project as your backend. Staff often need things the default Admin does not know about: a "reviews" panel on the product page, a page for loyalty-point adjustments, a settings screen for your own integration. Medusa lets you add these as small React files in src/admin, and the Admin build picks them up.

This lesson covers the three extension types (widgets, UI routes, settings pages), the helper libraries, how to fetch data, and the rules for what extensions cannot do. Admin extensions are React code that runs inside the Admin's build, so every real example here is read-only. The runnable part is a plain-JavaScript stand-in for the idea behind widget zones, so you can see how a dashboard can render pieces it knew nothing about at build time.

What is in src/admin

Extensions are discovered by folder and file name, in the same file-based spirit as API routes (see Custom API Routes and Middleware):

TEXT
src/admin/
  widgets/
    product-reviews.tsx        -> widget injected into a page zone
  routes/
    loyalty/
      page.tsx                 -> a new page at /app/loyalty
    settings/
      shipping-sync/
        page.tsx               -> a new page under Settings
  lib/
    sdk.ts                     -> JS SDK instance for the Admin

Medusa scans these folders when the Admin is built (or served by medusa develop) and wires the pieces into the dashboard. You do not register anything by hand. A few packages are available in the Admin context: @medusajs/admin-sdk for the helper functions, @medusajs/ui for components and @medusajs/icons for icons. The Admin already includes React and React Query, so you should not bundle your own copies.

Widgets and injection zones

A widget is a React component placed into a predefined zone on an existing page. Zones have names that describe a place on a page, such as product.details.after (below the product details) or order.details.side.before. The list of zones grows with Medusa versions, so look it up for your release before choosing one.

A widget file exports a default component and a config created with defineWidgetConfig:

TSX
// src/admin/widgets/product-reviews.tsx
import { defineWidgetConfig } from "@medusajs/admin-sdk"
import { Container, Heading, Text } from "@medusajs/ui"
import type { DetailWidgetProps, AdminProduct } from "@medusajs/framework/types"

const ProductReviewsWidget = ({ data }: DetailWidgetProps<AdminProduct>) => {
  return (
    <Container className="divide-y p-0">
      <div className="px-6 py-4">
        <Heading level="h2">Reviews</Heading>
        <Text size="small" className="text-ui-fg-subtle">
          Product {data.title} has no reviews yet.
        </Text>
      </div>
    </Container>
  )
}

export const config = defineWidgetConfig({
  zone: "product.details.after",
})

export default ProductReviewsWidget

Detail-page widgets receive a data prop holding the entity that the page shows (here the product). List-page zones do not get one. The Container, Heading and Text components come from @medusajs/ui, the design system of the Admin; using them (and its Tailwind-based tokens such as text-ui-fg-subtle) keeps your widget visually consistent and correct in dark mode.

flowchart TD
    B["Admin build<br/>scans src/admin"] --> R["Registry<br/>zone to components"]
    P["Product details page"] -->|"renders zone product.details.after"| R
    R --> W1["Your reviews widget"]
    R --> W2["Another widget"]

The page does not know your widgets exist; it just renders whatever is registered for each zone it contains.

UI routes and settings pages

A UI route is a whole new page. A file named page.tsx under src/admin/routes/<path>/ becomes a page at /app/<path>. It exports a default component and, to appear in the sidebar, a config from defineRouteConfig:

TSX
// src/admin/routes/loyalty/page.tsx
import { defineRouteConfig } from "@medusajs/admin-sdk"
import { ChartBar } from "@medusajs/icons"
import { Container, Heading } from "@medusajs/ui"

const LoyaltyPage = () => (
  <Container className="p-6">
    <Heading>Loyalty points</Heading>
  </Container>
)

export const config = defineRouteConfig({
  label: "Loyalty",
  icon: ChartBar,
})

export default LoyaltyPage

A route under src/admin/routes/settings/... is shown inside the Settings area instead of the main sidebar, which suits configuration screens for an integration. Dynamic segments use folder names such as [id] like in API routes. Page files are the only files in routes that are treated as pages; other files there are helpers.

Fetching data

Admin code talks to your backend through the JS SDK and React Query. Create one SDK instance and reuse it:

TypeScript
// src/admin/lib/sdk.ts
import Medusa from "@medusajs/js-sdk"

export const sdk = new Medusa({
  baseUrl: import.meta.env.VITE_BACKEND_URL || "/",
  debug: import.meta.env.DEV,
  auth: { type: "session" },
})

Inside a component, useQuery fetches and caches, and useMutation changes data:

TSX
import { useQuery } from "@tanstack/react-query"
import { sdk } from "../lib/sdk"

const { data, isLoading, error } = useQuery({
  queryFn: () => sdk.client.fetch<{ reviews: Review[] }>(`/admin/products/${id}/reviews`),
  queryKey: ["product-reviews", id],
})

sdk.client.fetch calls any route, including your own custom Admin routes from Custom API Routes and Middleware. With session auth the browser sends the Admin's cookie automatically, and your route is protected by the admin authentication middleware described in The Admin API and Authentication. After a mutation, invalidate the related query key so the widget refreshes:

TSX
const queryClient = useQueryClient()
const approve = useMutation({
  mutationFn: (reviewId: string) =>
    sdk.client.fetch(`/admin/reviews/${reviewId}/approve`, { method: "POST" }),
  onSuccess: () => queryClient.invalidateQueries({ queryKey: ["product-reviews", id] }),
})

Always handle three states, loading, error and empty, because staff will see all three. The @medusajs/ui package provides Toaster-style toasts (toast.success) for feedback after actions.

Internationalization

The Admin ships with translations for many languages. Your extension text can be translated too: you provide a translations file (in src/admin/i18n) with keys per language and read them with the useTranslation hook from react-i18next. Support for this in extensions has evolved, so check the documentation for your release before relying on it. If you only serve staff in one language, plain strings are a perfectly good start.

What extensions cannot do

Admin extensions are limited on purpose:

  • They run in the browser and have no access to the backend container. All data and actions go through API routes.
  • They cannot replace the Admin's built-in pages or alter their internals; you can only add into zones, add pages, and add settings screens.
  • They are built together with the Admin. Changing a widget means a rebuild; in development medusa develop reloads for you.
  • Because the Admin can be deployed apart from the backend (see Deploying Medusa), the backend URL is a build-time variable, and CORS must allow the Admin origin.

Protect data with API-side permissions, not by hiding buttons. A hidden button is not security.

Stand-in: a widget-zone renderer

The stand-in is not the Admin. It demonstrates the pattern behind zones: a registry maps zone names to components (here, functions returning HTML text), and a page renders every widget registered for each zone it contains. It also shows ordering and error isolation, so one broken widget does not take the page down.

Node.js A zone registry and page renderer

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The "broken" widget throws because the product has no supplier, yet the page still renders the other widgets. Real React gives you the same protection through error boundaries. The renderer also shows why widgets receive only a narrow data prop: they are plugins into somebody else's page, not owners of it.

A short checklist for a new extension

  1. Pick the zone (or route) and check its name against your Medusa version.
  2. Build the backend route first and test it with a plain request (The Admin API and Authentication).
  3. Create the SDK instance once and use useQuery with specific query keys.
  4. Handle loading, error and empty states; show feedback after mutations.
  5. Use @medusajs/ui components so styling and dark mode match.
  6. Keep authorization on the server.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does a file need to be to become a new Admin page at /app/loyalty?

    UI routes are discovered by file name. A page.tsx under src/admin/routes/<path> becomes the page at /app/<path>.
  2. 2. What does a widget's zone describe?

    Zones are named locations such as product.details.after. The page renders every widget registered for the zones it contains.
  3. 3. Why is hiding an Admin button not a security measure?

    Anything in the browser can be bypassed. Real permissions belong in the API routes and their authentication middleware.
  4. 4. Which tool should an extension use to load data from your custom route?

    Admin extensions have no access to the backend container. They call API routes, typically with sdk.client.fetch wrapped in useQuery or useMutation.

Summary

  • Admin extensions live in src/admin and are discovered by folder: widgets, routes (including Settings pages) and helper files.
  • Widgets are injected into named zones; detail zones pass the entity as data.
  • defineWidgetConfig and defineRouteConfig describe where a widget goes and how a route appears in the sidebar.
  • Fetch with the JS SDK and React Query, handle loading, error and empty states, and invalidate queries after mutations.
  • Extensions are browser code: authorization stays on the server, and they cannot rewrite built-in pages.

Next, move to the customer-facing side with The Next.js Starter Storefront.