Admin Dashboard Overview

Learn about the Medusa admin dashboard, its features, and architecture

The Medusa admin dashboard is a React-based web application that provides a user interface for managing your commerce operations. Built with modern technologies like React, TypeScript, and Vite, it offers a fast, extensible, and customizable admin experience.

Features

The admin dashboard provides comprehensive tools for managing your commerce platform:

Core Commerce Features

• Order Management: View, update, and manage orders, including refunds, returns, and fulfillment
• Product Catalog: Create and manage products, variants, collections, categories, and tags
• Customer Management: Manage customer accounts, groups, and profiles
• Inventory: Track inventory levels, manage stock locations, and handle reservations
• Pricing: Configure price lists, promotions, and campaigns
• Sales Channels: Manage multiple sales channels and their configurations
• Regions & Shipping: Configure regions, shipping profiles, and options
• Tax Management: Set up tax regions and configure tax rules

Developer Features

• Extensibility: Add custom routes, widgets, and UI components
• Custom Fields: Extend forms and display custom data
• Theming: Customize colors, branding, and visual appearance
• Internationalization: Built-in support for multiple languages
• API Integration: Seamless integration with Medusa backend via the Admin SDK

Architecture

The admin dashboard is built on a modular, plugin-based architecture that allows for extensive customization.

Technology Stack

• React 18: UI framework with concurrent rendering
• TypeScript: Type-safe development
• Vite: Fast build tool and development server
• React Router 6: Client-side routing
• TanStack Query: Data fetching and caching
• React Hook Form: Form management and validation
• Zod: Schema validation
• Medusa UI: Design system components

Package Structure

The admin dashboard consists of several packages:

packages/admin/
├── dashboard/           # Main React application
├── admin-sdk/          # SDK for extensions and configuration
├── admin-shared/       # Shared types and utilities
├── admin-vite-plugin/  # Vite plugin for bundling extensions
└── admin-bundler/      # Build tooling

Core Architecture

DashboardApp Class

The DashboardApp class (packages/admin/dashboard/src/dashboard-app/dashboard-app.tsx) is the core orchestrator that:

• Registers and manages plugins
• Populates routes, widgets, menus, and custom fields
• Provides an API for accessing registered extensions
• Renders the application with all providers

import { DashboardApp } from "@medusajs/dashboard"

const app = new DashboardApp({
  plugins: [
    // Your plugins here
  ]
})

app.render()

Plugin System

Plugins extend the dashboard by providing:

• Routes: Custom pages and navigation
• Widgets: Injectable UI components
• Menu Items: Sidebar navigation entries
• Custom Fields: Form extensions and data displays
• i18n: Translations and localization

Each plugin conforms to the DashboardPlugin interface:

type DashboardPlugin = {
  formModule: FormModule
  displayModule: DisplayModule
  menuItemModule: MenuItemModule
  widgetModule: WidgetModule
  routeModule: RouteModule
  i18nModule?: I18nModule
}

Injection Zones

The dashboard uses injection zones to allow extensions to insert custom UI at specific locations. Available zones include:

• order.details.before / order.details.after
• product.details.before / product.details.after
• customer.details.before / customer.details.after
• And many more for all major entities

See the full list in packages/admin/admin-shared/src/extensions/widgets/constants.ts:210

Providers

The dashboard wraps the application in several context providers:

• ExtensionProvider: Provides access to registered extensions
• ThemeProvider: Manages light/dark theme switching
• i18nProvider: Handles internationalization
• KeybindProvider: Manages keyboard shortcuts
• SearchProvider: Global search functionality
• SidebarProvider: Sidebar state management

Data Flow

1. API Calls: The dashboard uses the Medusa JS SDK to communicate with the backend
2. TanStack Query: Manages data fetching, caching, and synchronization
3. React Hook Form: Handles form state and validation
4. Optimistic Updates: UI updates immediately while background requests process

Getting Started

To start customizing the admin dashboard:

1. Install Dependencies

   The admin dashboard is included with Medusa by default. No additional installation required.

2. Start Development Server

   npx medusa develop
   

   The admin dashboard will be available at http://localhost:9000/app

3. Create Extensions

   Create custom routes, widgets, or customize the UI to fit your needs.

   See the following guides:

   • Customization - Theming and branding
   • UI Routes - Custom pages and navigation
   • Widgets - Injectable components

Next Steps

• Learn how to customize the admin UI
• Add custom routes to create new pages
• Create widgets to extend existing pages
• Review the JavaScript SDK for API integration