Standalone Approach

​

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.

// medusa-config.ts
module.exports = defineConfig({
  admin: {
    disable: true // ℹ️ This will not serve the Admin UI
  },
  // ... rest of your config
})

​

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.

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

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.

cd medusa
git checkout tags/v2.5.0 # ℹ️ At the moment of writing this guide this is the latest stable version, feel free to replace it with the version you 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:

nodeLinker: node-modules

This will allow you to use the yarn command to install the dependencies of the dashboard.

yarn install

Now that you have your dependencies installed, you can start the dashboard in development mode.

yarn dev

​

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.

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

​

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.

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.