Customize Medusa Admin Dashboard With Extensions

[habualoush]

Medusa Dashboard Fork Implementation Guide

Overview

This guide explains how to fork the Medusa dashboard for full customization while maintaining backend integration and extension compatibility.

Benefits

• ✅ Complete dashboard control and customization
• ✅ Admin extensions still work seamlessly
• ✅ Single build process for backend + dashboard
• ✅ Version control over dashboard changes
• ✅ Maintain Medusa ecosystem compatibility

Implementation Steps

1. Setup Yarn Workspaces

Add dashboard as a workspace in your root package.json:

{
  "workspaces": ["dashboard"]
}

2. Fork the Dashboard

1. Copy the entire Medusa dashboard source to your project's /dashboard/ directory
2. Keep the original package name "@medusajs/dashboard" in dashboard's package.json
3. Ensure version alignment with your Medusa backend version (e.g., 2.8.8)

3. Configure Build Scripts

Root package.json:

{
  "scripts": {
    "build": "medusa build && yarn workspace @medusajs/dashboard run build:preview",
    "build:dashboard": "yarn workspace @medusajs/dashboard run build:preview"
  }
}

Dashboard package.json:

{
  "scripts": {
    "build": "tsup && node ./scripts/generate-types.js",
    "build:preview": "vite build"
  }
}

4. Configure Admin Extensions Integration

Dashboard vite.config.mts:

import inject from "@medusajs/admin-vite-plugin"
import react from "@vitejs/plugin-react"
import { defineConfig, loadEnv } from "vite"
import path from "path"

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd())
  
  // Include your backend admin extensions
  const sources = [
    path.resolve(__dirname, "src/admin") // Your backend extensions
  ]

  return {
    plugins: [
      react(),
      inject({ sources }), // This bridges your extensions
    ],
    resolve: {
      alias: {
        "@admin": path.resolve(__dirname, "src/admin")
      },
    },
  }
})

5. Configure Medusa Backend

medusa-config.ts:

module.exports = defineConfig({
  admin: {
    disable: process.env.NODE_ENV === "development", // Use separate dev server
  },
  // ... rest of your config
})

6. Handle Version Conflicts

Root package.json resolutions:

{
  "resolutions": {
    "zod": "^3.25.0"
  }
}

7. Directory Structure

your-project/
├── package.json (workspaces: ["dashboard"])
├── medusa-config.ts
├── dashboard/ (forked dashboard)
│   ├── package.json (@medusajs/dashboard)
│   ├── vite.config.mts
│   ├── src/
│   └── dist/
└── src/
    └── admin/ (your extensions)
        ├── routes/
        ├── components/
        └── hooks/

Development Workflow

Development Mode

# Terminal 1: Run backend
yarn dev

# Terminal 2: Run dashboard separately  
cd dashboard && yarn dev

Production Build

yarn build  # Builds both backend and dashboard

Key Points

1. Extensions Bridge: The @medusajs/admin-vite-plugin with sources config connects your backend admin extensions to the forked dashboard

2. Workspace Benefits: Yarn workspaces allow treating the dashboard as a local dependency while maintaining separate build processes

3. Version Synchronization: Keep all @medusajs/* packages at the same version across root and dashboard

4. Admin Disable: Disable the built-in admin in development to avoid conflicts with your forked version

Troubleshooting

• Zod version conflicts: Use yarn resolutions to force consistent zod versions
• UI component issues: Ensure @medusajs/ui versions are compatible between root and dashboard
• Extension loading: Verify the vite plugin sources path points to your admin directory

Result

You get a fully customizable dashboard that:

• Builds alongside your backend
• Maintains all Medusa extension functionality
• Allows complete UI/UX control
• Stays in sync with your backend changes

[bansal-ashish-dev]

Great I was able to make it work following this. It's so easy now to work with plugins. I also extended it to support multiple plugins.
Attaching for reference.

[cokhane]

thanks! my question is for example i did use the version tag. 2.8.3 wouldnt i have any conflicts problems when i wanted to update my branch?

[virtualstoodeeoh-dev]

What if I want to keep up to date with what Medusa Admin Dashboard repo releases? Is that possible?