Standalone Approach
Learn how to customize the Medusa Admin UI and use it as a standalone app
Introduction
The new version of Medusa has brought big changes to its admin interface, new design, new pages, new menus and a completely new user experience, it must be said that the team has spent a lot of time designing this little gem that is the new dashboard and continues to improve it with each new version with new features and improvements. Since the latest versions of Medusa V1 we are used to having this interface in the form of a plugin injected by default in the Medusa backend, but this poses a problem, what should I do if I want to make changes to this interface to add new features or new pages? The team was able to set up a system of Widgets and pages, which will attach themselves by default to the plugin, but for some, these widgets can be limited and are therefore looking for a much more extensive solution.
The standalone approach
The idea of this guide is to show you how to fork the dashboard and use it as a standalone application, at the end of this guide you’ll have a dashboard that you can use as a standalone app. If you plan to implement significant changes to the Admin UI and its native components, it is important to note that future updates to the Admin UI may become more challenging to integrate and maintain.
Disable the Admin from your backend
Before we start, we need to disable the Admin from your backend, this will prevent the Medusa backend from automatically injecting the Admin UI into your project.
Forking the Medusa project
First we will fork the Medusa project in order to retrieve the package that interests us, I advise you to select a version tag at the time of your fork in order to be sure to have either the same version as your backend or a version that was released without development in progress.
This will create a new folder called medusa
in your current working directory, we will now navigate into the folder and select the tag that we want to use.
Copying the dashboard package
Now that you’re on the right version in the repo, you can get the dashboard
package from the packages/admin
folder and copy it somewhere else than in the Medusa project, this will be your standalone app folder.
Alright once you have your dashboard, I invite you to create a .yarnrc.yml
file in the root of the dashboard folder with the following content:
This will allow you to use the yarn
command to install the dependencies of the dashboard.
Now that you have your dependencies installed, you can start the dashboard in development mode.
The dashboard is a Vite app that will be served at http://localhost:5173
by default
Environment variables
There is some good defaults that are set in the vite.config.mts
file, allowing you to start the development mode without any issues, but just in case you need to override them, you can do so by creating a .env
file in the root of the dashboard folder and use
the different variables that are available inside the vite.config.mts
file.
Making changes to the dashboard
Now that you have your dashboard running, you can start making changes to it and then build when you’re done like you would with any other Vite app.
The vite build
action is available in the package.json
file under the build:preview
script.
Here is a quick example on how I’ve managed to make some changes to the login page 👇🏼
Troubleshooting
I’m getting a CORS error
If you’re getting a CORS error, please follow the documentation from the Medusa V2 docs, to adapt your backend to your port.
Was this page helpful?