From medusa-commerce
Build Medusa v2 admin extensions: widgets in injection zones, custom UI routes, Medusa UI components, Admin API calls for dashboard customization.
npx claudepluginhub orcaqubits/agentic-commerce-skills-plugins --plugin medusa-commerceThis skill is limited to using the following tools:
**Fetch live docs**:
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
Fetch live docs:
https://docs.medusajs.com/learn/fundamentals/admin/widgets for widget developmentsite:docs.medusajs.com admin UI routes for custom admin pagessite:docs.medusajs.com admin widget injection zones for available zonessite:docs.medusajs.com medusa UI components for component librarysite:docs.medusajs.com admin API client for making API calls from adminMedusa v2 admin is a React-based SPA that supports two extension types:
Extensions live in src/admin/ and are automatically discovered and bundled.
| 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 |
| 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.
// 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
| 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.
| 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 |
// 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
The defineRouteConfig with a label property automatically adds the page to the admin sidebar. Pages under routes/settings/ appear in the Settings section.
| 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 componentsfor the full component catalog and prop APIs.
// 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()
Admin extensions run within the authenticated admin session. Use the built-in fetch wrapper or the JS SDK which automatically includes session credentials.
| 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.
| 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 |
@medusajs/ui components for visual consistency with the core admindata prop for type safetysrc/admin/lib/ for reuse across widgets and routes| 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.