Customize the Admin UI

Widgets and custom pages not enough? You want full control over the Admin UI: custom components, modified layouts, and deep design changes.

The solution: fork the dashboard and run it as a standalone app.

Warning: Forking means you own maintenance. Future Medusa updates won't merge automatically.

1. Disable the Built-in Admin

First, stop Medusa from serving its bundled admin:

1// medusa-config.ts
2module.exports = defineConfig({
3  admin: {
4    disable: true,
5  },
6  // ...
7})

2. Clone the Medusa Repo

git clone https://github.com/medusajs/medusa.git
cd medusa

Check out a stable version tag matching your backend:

git checkout tags/v2.13.0

Replace v2.13.0 with your Medusa version. Check releases at github.com/medusajs/medusa/releases

3. Extract the Dashboard

Copy the dashboard package to your project:

cp -r packages/admin/dashboard /path/to/your/admin-standalone

4. Setup Dependencies

Create .yarnrc.yml in your dashboard folder:

nodeLinker: node-modules

Install and run:

yarn install
yarn dev

The dashboard runs at http://localhost:5173

5. Configure Environment

Create .env if you need to override defaults:

VITE_MEDUSA_BACKEND_URL="http://localhost:9000"
VITE_MEDUSA_STOREFRONT_URL="http://localhost:8000"
VITE_MEDUSA_BASE="/"

Edit any file. It's a standard Vite + React app.

Troubleshooting

CORS Error

Your backend rejects requests from localhost:5173. Add it to allowed origins:

1// medusa-config.ts
2module.exports = defineConfig({
3  projectConfig: {
4    http: {
5      adminCors: "http://localhost:5173,http://localhost:9000",
6    },
7  },
8// ...
9})

See the Medusa CORS docs for details.

API Connection Issues

Verify VITE_MEDUSA_BACKEND_URL points to your running Medusa server and that the server is accessible.