5.1. Admin Development

In this chapter, you'll learn about the Medusa Admin dashboard and the possible ways to customize it.

Tip: To explore the Medusa Admin's commerce features, check out the User Guide. These user guides are designed for merchants and provide the steps to perform any task within the Medusa Admin.

What is the Medusa Admin?#

The Medusa Admin is an intuitive dashboard that allows merchants to manage their ecommerce store. It provides management features related to products, orders, customers, and more.

The Medusa Admin is built with Vite v7. When you install the Medusa application, you also install the Medusa Admin. Then, when you start the Medusa application, you can access the Medusa Admin at http://localhost:9000/app.

Tip: If you don't have an admin user, use the Medusa CLI to create one.
Version Changes: 
  • Since Medusa v2.23.0, the Medusa Admin uses Vite v8 and supports Chrome v111+, Edge v111+, Firefox v114+, and Safari v16.4+. If you need to support older browsers, change the build.target option in the admin.vite configuration.
  • Since Medusa v2.23.0, the Medusa Admin and the Medusa UI package use React v19, and the @medusajs/medusa package requires react-dom v19.3.1 or later as a peer dependency. If your project or plugin installs react, react-dom, @types/react, or @types/react-dom, update them to v19 and make sure your admin customizations are compatible with React v19. For example, useRef now requires an initial value, and refs created with useRef<HTMLDivElement>(null) have the type RefObject<HTMLDivElement | null>. Learn more in the React 19 Upgrade Guide.
  • Since Medusa v2.23.0, the Medusa Admin and your admin customizations compile with Tailwind CSS v4. The admin build scans your project's and plugins' admin files for Tailwind classes, so you don't need a tailwind.config file in your project or plugin. The admin build also doesn't load PostCSS configuration files. Make sure your admin customizations use Tailwind CSS v4 class names. For example, use outline-hidden instead of outline-none, and rounded-sm instead of rounded. Learn more in the Tailwind CSS v4 Upgrade Guide.
  • Since Medusa v2.19.0, the Medusa Admin uses react-router-dom v7. If your project installs react-router-dom directly, update it to v7. Learn more in the Admin Routing Customizations chapter.

How to Customize the Medusa Admin?#

You can customize the Medusa Admin dashboard by:

  • Adding new sections to existing pages using Widgets.
  • Adding new pages using UI Routes.

The next chapters will cover these two topics in detail.

What You Can't Customize in the Medusa Admin#

You can't customize the admin dashboard's layout, design, or the content of the existing pages (aside from injecting widgets). You also can't change the Medusa logo used in the admin dashboard.

If your use case requires heavy customization of the admin dashboard, you can build a custom admin dashboard using Medusa's Admin API routes.


Medusa UI Package#

Medusa provides a Medusa UI package to facilitate your admin development through ready-made components and ensure a consistent design between your customizations and the dashboard’s design.

Refer to the Medusa UI documentation to learn how to install it and use its components.


Admin How-to Guides#

The Admin How-to Guides provides guides that walk you through common admin customizations, such as building common admin components, or adding third-party authentication to the admin.

Refer to these guides for practical examples of customizing the Medusa Admin dashboard.

Was this chapter helpful?
Ask Bloom
For assistance in your development, use Claude Code Plugins or Docs MCP server in Cursor, VSCode, etc...FAQ
What is Medusa?
How can I create a module?
How can I create a data model?
How do I create a workflow?
How can I extend a data model in the Product Module?
Recipes
How do I build a marketplace with Medusa?
How do I build digital products with Medusa?
How do I build subscription-based purchases with Medusa?
What other recipes are available in the Medusa documentation?
Chat is cleared on refresh
Line break
⇧↵