Medusa Admin Dashboard Customizations

Build custom UI extensions for the Medusa Admin dashboard using the Admin SDK and Medusa UI components.

Note: "UI Routes" are custom admin pages, different from backend API routes (which use building-with-medusa skill).

When to Apply

Load this skill for ANY admin UI development task, including:

• Creating widgets for product/order/customer pages
• Building custom admin pages
• Implementing forms and modals
• Displaying data with tables or lists
• Adding navigation between pages

Also load these skills when:

• building-with-medusa: Building backend API routes that the admin UI calls
• building-storefronts: If working on storefront instead of admin dashboard

CRITICAL: Load Reference Files When Needed

The quick reference below is NOT sufficient for implementation. You MUST load relevant reference files before writing code for that component.

Load these references based on what you're implementing:

• Creating widgets? → MUST load references/data-loading.md first
• Building forms/modals? → MUST load references/forms.md first
• Displaying data in tables/lists? → MUST load references/display-patterns.md first
• Selecting from large datasets? → MUST load references/table-selection.md first
• Adding navigation? → MUST load references/navigation.md first
• Styling components? → MUST load references/typography.md first

Minimum requirement: Load at least 1-2 reference files relevant to your specific task before implementing.

When to Use This Skill vs MedusaDocs MCP Server

⚠️ CRITICAL: This skill should be consulted FIRST for planning and implementation.

Use this skill for (PRIMARY SOURCE):

• Planning - Understanding how to structure admin UI features
• Component patterns - Widgets, pages, forms, tables, modals
• Design system - Typography, colors, spacing, semantic classes
• Data loading - Critical separate query pattern, cache invalidation
• Best practices - Correct vs incorrect patterns (e.g., display queries on mount)
• Critical rules - What NOT to do (common mistakes like conditional display queries)

Use MedusaDocs MCP server for (SECONDARY SOURCE):

• Specific component prop signatures after you know which component to use
• Available widget zones list
• JS SDK method details
• Configuration options reference

Why skills come first:

• Skills contain critical patterns like separate display/modal queries that MCP doesn't emphasize
• Skills show correct vs incorrect patterns; MCP shows what's possible
• Planning requires understanding patterns, not just API reference

Critical Setup Rules

SDK Client Configuration

CRITICAL: Always use exact configuration - different values cause errors:

// src/admin/lib/client.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",
  },
})

pnpm Users ONLY

CRITICAL: Install peer dependencies BEFORE writing any code:

# Find exact version from dashboard
pnpm list @tanstack/react-query --depth=10 | grep @medusajs/dashboard
# Install that exact version
pnpm add @tanstack/react-query@[exact-version]

# If using navigation (Link component)
pnpm list react-router-dom --depth=10 | grep @medusajs/dashboard
pnpm add react-router-dom@[exact-version]

npm/yarn users: DO NOT install these packages - already available.

Rule Categories by Priority

Quick Reference

1. Data Loading (CRITICAL)

• data-sdk-always - ALWAYS use Medusa JS SDK for ALL API requests - NEVER use regular fetch() (missing auth headers causes errors)
• data-sdk-method-choice - Use existing SDK methods for built-in endpoints (sdk.admin.product.list()), use sdk.client.fetch() for custom routes
• data-display-on-mount - Display queries MUST load on mount (no enabled condition based on UI state)
• data-separate-queries - Separate display queries from modal/form queries
• data-invalidate-display - Invalidate display queries after mutations, not just modal queries
• data-loading-states - Always show loading states (Spinner), not empty states
• data-pnpm-install-first - pnpm users MUST install @tanstack/react-query BEFORE coding

2. Design System (CRITICAL)

• design-semantic-colors - Always use semantic color classes (bg-ui-bg-base, text-ui-fg-subtle), never hardcoded
• design-spacing - Use px-6 py-4 for section padding, gap-2 for lists, gap-3 for items
• design-button-size - Always use size="small" for buttons in widgets and tables
• design-medusa-components - Always use Medusa UI components (Container, Button, Text), not raw HTML

3. Data Display (HIGH)

• display-price-format - CRITICAL: Prices from Medusa are stored as-is ($49.99 = 49.99, NOT in cents). Display them directly - NEVER divide by 100

4. Typography (HIGH)

• typo-text-component - Always use Text component from @medusajs/ui, never plain span/p tags
• typo-labels - Use <Text size="small" leading="compact" weight="plus"> for labels/headings
• typo-descriptions - Use <Text size="small" leading="compact" className="text-ui-fg-subtle"> for descriptions
• typo-no-heading-widgets - Never use Heading for small sections in widgets (use Text instead)

5. Forms & Modals (MEDIUM)

• form-focusmodal-create - Use FocusModal for creating new entities
• form-drawer-edit - Use Drawer for editing existing entities
• form-disable-pending - Always disable actions during mutations (disabled={mutation.isPending})
• form-show-loading - Show loading state on submit button (isLoading={mutation.isPending})

6. Selection Patterns (MEDIUM)

• select-small-datasets - Use Select component for 2-10 options (statuses, types, etc.)
• select-large-datasets - Use DataTable with FocusModal for large datasets (products, categories, etc.)
• select-search-config - Must pass search configuration to useDataTable to avoid "search not enabled" error

Critical Data Loading Pattern

ALWAYS follow this pattern - never load display data conditionally:

// ✅ CORRECT - Separate queries with proper responsibilities
const RelatedProductsWidget = ({ data: product }) => {
  const [modalOpen, setModalOpen] = useState(false)

  // Display query - loads on mount
  const { data: displayProducts } = useQuery({
    queryFn: () => fetchSelectedProducts(selectedIds),
    queryKey: ["related-products-display", product.id],
    // No 'enabled' condition - loads immediately
  })

  // Modal query - loads when needed
  const { data: modalProducts } = useQuery({
    queryFn: () => sdk.admin.product.list({ limit: 10, offset: 0 }),
    queryKey: ["products-selection"],
    enabled: modalOpen, // OK for modal-only data
  })

  // Mutation with proper invalidation
  const updateProduct = useMutation({
    mutationFn: updateFunction,
    onSuccess: () => {
      // Invalidate display data query to refresh UI
      queryClient.invalidateQueries({ queryKey: ["related-products-display", product.id] })
      // Also invalidate the entity query
      queryClient.invalidateQueries({ queryKey: ["product", product.id] })
      // Note: No need to invalidate modal selection query
    },
  })

  return (
    <Container>
      {/* Display uses displayProducts */}
      {displayProducts?.map(p => <div key={p.id}>{p.title}</div>)}

      <FocusModal open={modalOpen} onOpenChange={setModalOpen}>
        {/* Modal uses modalProducts */}
      </FocusModal>
    </Container>
  )
}

// ❌ WRONG - Single query with conditional loading
const BrokenWidget = ({ data: product }) => {
  const [modalOpen, setModalOpen] = useState(false)

  const { data } = useQuery({