Back to all posts

Customize the Medusa Admin UI

Adil Basri

The new Admin UI in Medusa got a full redesign : new layout, new menus, better UX. But what if you need more than widgets or small tweaks? Let’s walk through running the Admin UI as a standalone app so you can really customize it.

Customize the Medusa Admin UI

Step 1 - Disable the built-in Admin

First, tell your backend not to inject the Admin automatically:

typescript
1// ...
2
3module.exports = defineConfig({
4  admin: { disable: true },
5  // ...rest of config
6})
7

Step 2 - Fork the Dashboard

Grab the Medusa repo and checkout the tag that matches your backend:

bash
git clone https://github.com/medusajs/medusa.git
cd medusa
git checkout tags/v2.5.0 # replace with your version

Inside packages/admin you will find the dashboard. Copy that folder somewhere outside the Medusa repo. This will be your standalone Admin app.

Step 3 - Boot it locally

In the dashboard folder, add a .yarnrc.yml:

yaml
nodeLinker: node-modules

Then install and run:

bash
yarn install
yarn dev

By default, the Admin UI will be available at "http://localhost:5173" (Default Vite port)

Step 4 - Configure and Customize

You can override defaults from vite.config.mts using environment variables. Create a .env file in your dashboard folder if needed:

env
VITE_MEDUSA_BASE="<string>"
VITE_MEDUSA_BACKEND_URL="<string>"
VITE_MEDUSA_STOREFRONT_URL="<string>"

Now you can start making changes to pages, components, or anything else. When finished, build the dashboard just like any other Vite app:

bash
yarn build

Keep in mind that upgrades from future Medusa releases might require manual effort to bring your changes along. If you need deep customization, this is the way to go.

Troubleshooting

  • CORS errors
    Update your Medusa backend configuration to allow requests from your Admin port.
Tagged:
Guide