medusa-admin

name	medusa-admin
description	Extend the Medusa v2 admin dashboard — widgets injected at zones, custom UI routes, Medusa UI components, and Admin API integration. Use when customizing the admin interface.
allowed-tools	Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch

Medusa v2 Admin Dashboard Extensions

Before writing code

Fetch live docs:

1. Fetch https://docs.medusajs.com/learn/fundamentals/admin/widgets for widget development
2. Web-search site:docs.medusajs.com admin UI routes for custom admin pages
3. Web-search site:docs.medusajs.com admin widget injection zones for available zones
4. Web-search site:docs.medusajs.com medusa UI components for component library
5. Web-search site:docs.medusajs.com admin API client for making API calls from admin

Admin Extension Concept

Medusa v2 admin is a React-based SPA that supports two extension types:

• Widgets -- injected into predefined zones on existing admin pages
• UI Routes -- entirely new pages accessible via the admin sidebar or navigation

Extensions live in src/admin/ and are automatically discovered and bundled.

Admin Extension Directory Structure

Directory	Purpose
src/admin/widgets/	Widget components (e.g., product-custom-widget.tsx)
src/admin/routes/custom-page/page.tsx	Custom admin page
src/admin/routes/custom-page/[id]/page.tsx	Dynamic route page
src/admin/lib/	Shared API utilities

Widgets

Widget Injection Zones

Zone	Location	Use Case
product.details.before	Product detail, top	Custom product fields
product.details.after	Product detail, bottom	Related data display
product.details.side.before	Product detail sidebar, top	Quick actions
product.details.side.after	Product detail sidebar, bottom	Metadata display
order.details.before	Order detail, top	Custom order info
order.details.after	Order detail, bottom	Fulfillment tracking
order.details.side.before	Order sidebar, top	Order tags
order.details.side.after	Order sidebar, bottom	Order notes
customer.details.before	Customer detail, top	Loyalty info
customer.details.after	Customer detail, bottom	Purchase history

Fetch live docs for the complete zone list -- zones are added with each Medusa release.

Widget Definition Skeleton

// src/admin/widgets/product-custom-widget.tsx
// Fetch live docs for defineWidgetConfig and zone types
import { defineWidgetConfig } from "@medusajs/admin-sdk"
import { Container, Heading } from "@medusajs/ui"

const ProductCustomWidget = ({ data }) => (
  <Container><Heading level="h2">Custom</Heading></Container>
)

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

Widget Props

Prop	Type	Description
data	Entity object	The entity displayed on the page (product, order, etc.)

The data prop shape depends on the zone -- a product.details.* zone receives the product object.

Custom UI Routes

Route File Convention

File Path	Admin URL
src/admin/routes/custom-page/page.tsx	/app/custom-page
src/admin/routes/custom-page/[id]/page.tsx	/app/custom-page/:id
src/admin/routes/settings/my-setting/page.tsx	/app/settings/my-setting

Route Page Skeleton

// src/admin/routes/custom-page/page.tsx
// Fetch live docs for defineRouteConfig
import { defineRouteConfig } from "@medusajs/admin-sdk"
import { Container, Heading } from "@medusajs/ui"

const CustomPage = () => (
  <Container><Heading level="h1">Custom Page</Heading></Container>
)

export const config = defineRouteConfig({ label: "Custom Page" })
export default CustomPage
// Fetch live docs for icon options in defineRouteConfig

Adding Sidebar Navigation

The defineRouteConfig with a label property automatically adds the page to the admin sidebar. Pages under routes/settings/ appear in the Settings section.

Medusa UI Component Library

Category	Key Components
Layout	Container, Drawer, FocusModal, Prompt
Typography	Heading, Text, Label, Code
Forms	Input, Select, Checkbox, RadioGroup, Switch, Textarea, DatePicker
Data	Table, Badge, StatusBadge, Avatar, Copy
Actions	Button, IconButton, DropdownMenu, CommandBar
Feedback	Toast, Alert, ProgressBar, Spinner
Navigation	Tabs, Breadcrumbs

Fetch live docs: Web-search site:docs.medusajs.com @medusajs/ui components for the full component catalog and prop APIs.

Making Admin API Calls

Using the Medusa JS SDK

// Fetch live docs for admin SDK client setup
// Use the SDK or fetch wrapper provided by Medusa admin
// Fetch live docs for createAdminClient or useAdminXxx hooks
const { data } = await sdk.admin.product.list()

Using fetch with Admin Auth

Admin extensions run within the authenticated admin session. Use the built-in fetch wrapper or the JS SDK which automatically includes session credentials.

Admin API Scopes

Scope	Endpoints	Requires
Store API (/store/*)	Storefront operations	Optional customer auth
Admin API (/admin/*)	Back-office operations	Admin user session
Custom (/admin/custom/*)	Custom admin endpoints	Admin auth middleware

Custom admin pages typically call /admin/* endpoints which require the admin session token.

Limitations

Limitation	Workaround
Cannot modify core admin pages	Use widgets injected at zones
Cannot override core admin routes	Create new routes with custom functionality
Limited styling control	Use @medusajs/ui components for consistency
No server-side rendering	Admin is a client-side SPA
Bundle size	Keep widget dependencies minimal

Best Practices

• Use @medusajs/ui components for visual consistency with the core admin
• Keep widgets focused on a single concern -- use multiple widgets for multiple features
• Use custom UI routes for complex multi-step interfaces
• Call the Admin API through the JS SDK or built-in fetch wrapper -- do not hardcode URLs
• Type your widget data prop for type safety
• Place shared utilities in src/admin/lib/ for reuse across widgets and routes

Testing Admin Extensions

Approach	Description
Storybook	Render components in isolation with @medusajs/ui
Browser testing	Run npx medusa develop and manually verify
Unit tests	Test logic functions separately from React rendering

Fetch the Medusa admin extension documentation for exact injection zone names, component props, and route configuration options before implementing.