Medusa v2 Admin Dashboard Extensions
Before writing code
Fetch live docs:
- Fetch
https://docs.medusajs.com/learn/fundamentals/admin/widgets for widget development
- Web-search
site:docs.medusajs.com admin UI routes for custom admin pages
- Web-search
site:docs.medusajs.com admin widget injection zones for available zones
- Web-search
site:docs.medusajs.com medusa UI components for component library
- 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.
1---2name: medusa-admin3description: 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.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/medusa-admin7---89# Medusa v2 Admin Dashboard Extensions1011## Before writing code1213**Fetch live docs**:141. Fetch `https://docs.medusajs.com/learn/fundamentals/admin/widgets` for widget development152. Web-search `site:docs.medusajs.com admin UI routes` for custom admin pages163. Web-search `site:docs.medusajs.com admin widget injection zones` for available zones174. Web-search `site:docs.medusajs.com medusa UI components` for component library185. Web-search `site:docs.medusajs.com admin API client` for making API calls from admin1920## Admin Extension Concept2122Medusa v2 admin is a React-based SPA that supports two extension types:23- **Widgets** -- injected into predefined zones on existing admin pages24- **UI Routes** -- entirely new pages accessible via the admin sidebar or navigation2526Extensions live in `src/admin/` and are automatically discovered and bundled.2728## Admin Extension Directory Structure2930| Directory | Purpose |31|-----------|---------|32| `src/admin/widgets/` | Widget components (e.g., `product-custom-widget.tsx`) |33| `src/admin/routes/custom-page/page.tsx` | Custom admin page |34| `src/admin/routes/custom-page/[id]/page.tsx` | Dynamic route page |35| `src/admin/lib/` | Shared API utilities |3637## Widgets3839### Widget Injection Zones4041| Zone | Location | Use Case |42|------|----------|----------|43| `product.details.before` | Product detail, top | Custom product fields |44| `product.details.after` | Product detail, bottom | Related data display |45| `product.details.side.before` | Product detail sidebar, top | Quick actions |46| `product.details.side.after` | Product detail sidebar, bottom | Metadata display |47| `order.details.before` | Order detail, top | Custom order info |48| `order.details.after` | Order detail, bottom | Fulfillment tracking |49| `order.details.side.before` | Order sidebar, top | Order tags |50| `order.details.side.after` | Order sidebar, bottom | Order notes |51| `customer.details.before` | Customer detail, top | Loyalty info |52| `customer.details.after` | Customer detail, bottom | Purchase history |5354> **Fetch live docs** for the complete zone list -- zones are added with each Medusa release.5556### Widget Definition Skeleton5758```typescript59// src/admin/widgets/product-custom-widget.tsx60// Fetch live docs for defineWidgetConfig and zone types61import { defineWidgetConfig } from "@medusajs/admin-sdk"62import { Container, Heading } from "@medusajs/ui"6364const ProductCustomWidget = ({ data }) => (65 <Container><Heading level="h2">Custom</Heading></Container>66)67```6869```typescript70export const config = defineWidgetConfig({ zone: "product.details.after" })71export default ProductCustomWidget72```7374### Widget Props7576| Prop | Type | Description |77|------|------|-------------|78| `data` | Entity object | The entity displayed on the page (product, order, etc.) |7980The `data` prop shape depends on the zone -- a `product.details.*` zone receives the product object.8182## Custom UI Routes8384### Route File Convention8586| File Path | Admin URL |87|-----------|-----------|88| `src/admin/routes/custom-page/page.tsx` | `/app/custom-page` |89| `src/admin/routes/custom-page/[id]/page.tsx` | `/app/custom-page/:id` |90| `src/admin/routes/settings/my-setting/page.tsx` | `/app/settings/my-setting` |9192### Route Page Skeleton9394```typescript95// src/admin/routes/custom-page/page.tsx96// Fetch live docs for defineRouteConfig97import { defineRouteConfig } from "@medusajs/admin-sdk"98import { Container, Heading } from "@medusajs/ui"99100const CustomPage = () => (101 <Container><Heading level="h1">Custom Page</Heading></Container>102)103```104105```typescript106export const config = defineRouteConfig({ label: "Custom Page" })107export default CustomPage108// Fetch live docs for icon options in defineRouteConfig109```110111### Adding Sidebar Navigation112113The `defineRouteConfig` with a `label` property automatically adds the page to the admin sidebar. Pages under `routes/settings/` appear in the Settings section.114115## Medusa UI Component Library116117| Category | Key Components |118|----------|---------------|119| Layout | `Container`, `Drawer`, `FocusModal`, `Prompt` |120| Typography | `Heading`, `Text`, `Label`, `Code` |121| Forms | `Input`, `Select`, `Checkbox`, `RadioGroup`, `Switch`, `Textarea`, `DatePicker` |122| Data | `Table`, `Badge`, `StatusBadge`, `Avatar`, `Copy` |123| Actions | `Button`, `IconButton`, `DropdownMenu`, `CommandBar` |124| Feedback | `Toast`, `Alert`, `ProgressBar`, `Spinner` |125| Navigation | `Tabs`, `Breadcrumbs` |126127> **Fetch live docs**: Web-search `site:docs.medusajs.com @medusajs/ui components` for the full component catalog and prop APIs.128129## Making Admin API Calls130131### Using the Medusa JS SDK132133```typescript134// Fetch live docs for admin SDK client setup135// Use the SDK or fetch wrapper provided by Medusa admin136// Fetch live docs for createAdminClient or useAdminXxx hooks137const { data } = await sdk.admin.product.list()138```139140### Using fetch with Admin Auth141142Admin extensions run within the authenticated admin session. Use the built-in `fetch` wrapper or the JS SDK which automatically includes session credentials.143144## Admin API Scopes145146| Scope | Endpoints | Requires |147|-------|-----------|----------|148| Store API (`/store/*`) | Storefront operations | Optional customer auth |149| Admin API (`/admin/*`) | Back-office operations | Admin user session |150| Custom (`/admin/custom/*`) | Custom admin endpoints | Admin auth middleware |151152Custom admin pages typically call `/admin/*` endpoints which require the admin session token.153154## Limitations155156| Limitation | Workaround |157|-----------|-----------|158| Cannot modify core admin pages | Use widgets injected at zones |159| Cannot override core admin routes | Create new routes with custom functionality |160| Limited styling control | Use `@medusajs/ui` components for consistency |161| No server-side rendering | Admin is a client-side SPA |162| Bundle size | Keep widget dependencies minimal |163164## Best Practices165166- Use `@medusajs/ui` components for visual consistency with the core admin167- Keep widgets focused on a single concern -- use multiple widgets for multiple features168- Use custom UI routes for complex multi-step interfaces169- Call the Admin API through the JS SDK or built-in fetch wrapper -- do not hardcode URLs170- Type your widget `data` prop for type safety171- Place shared utilities in `src/admin/lib/` for reuse across widgets and routes172173## Testing Admin Extensions174175| Approach | Description |176|----------|-------------|177| Storybook | Render components in isolation with `@medusajs/ui` |178| Browser testing | Run `npx medusa develop` and manually verify |179| Unit tests | Test logic functions separately from React rendering |180181Fetch the Medusa admin extension documentation for exact injection zone names, component props, and route configuration options before implementing.