Admin Widget / UI Route Not Showing

This guide provides some troubleshooting step as to why your admin widget / UI route isn't showing in the Medusa Admin dashboard.

Incorrect Zone#

If you're adding an admin widget, make sure you're using a correct zone.

Refer to the Admin Widget Injection Zones list for reference.

Incorrect Function Definition#

Widget and UI routes must be defined as arrow functions. Any other type of declaration isn't accepted.

Refer to the Admin Development Constraints documentation for more details.

Incorrect Type of Zone Value#

A widget zone's value must be wrapped in double or single quotes:

Code
1export const config = defineWidgetConfig({2  zone: "product.details.before",3})

Any other usage leads to the widget not being shown.

Refer to the Admin Development Constraints documentation for more details.

Errors in Docker#

If you're using a Docker image to host your Medusa application, make sure that the image's root path is different than the Medusa Admin's path configuration.

For example, if your Docker image's root path is /app, make sure to change the path configuration in medusa-config.ts, as it's /app by default:

medusa-config.ts
1module.exports = defineConfig({2  admin: {3    path: `/dashboard`,4  },5  // ...6})

Uncaught SyntaxError: The request module does not provide an export named default#

If you're using a third-party library that isn't ESM compatible, you might encounter this error in the console when you access the admin.

To resolve it, add the third-party library to vite's optimizeDeps configuration in medusa-config.ts. For example:

medusa-config.ts
1module.exports = defineConfig({2  admin: {3    vite: () => {4      return {5        optimizeDeps: {6          include: ["qs"],7        },8      }9    },10  },11  // ...12})

Where qs would be the third-party library you're using.

Learn more about the optimizeDeps configuration in the Vite documentation. Also, learn more about Medusa's admin configurations in this documentation.