Medusa Admin

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

Widgets

Widget Injection Zones

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

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

Custom UI Routes

Route File Convention

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

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

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

Limitations

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

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