Local development setup for contributors is confusing, undocumented, and lacks hot reload for plugins

What Medusa version and documentation are you using?

v2

Preliminary Checks

• This issue is not a duplicate. Before opening a new issue, please search existing issues: https://github.com/medusajs/medusa/issues

Issue Summary

Getting started with contributing code to Medusa is unnecessarily hard. The CONTRIBUTING.md gives a rough outline, but the actual experience of linking a fork to a test project and iterating on code is full of undocumented pitfalls and a painfully slow feedback loop.

There is also no dedicated page on docs.medusajs.com covering this - the only contribution guide there is about writing docs, not code.

---

1. The overall process is confusing to reason about

CONTRIBUTING.md mentions file: references and pnpm overrides, but doesn't explain the mental model: which packages need to be linked where, why some changes require a full reinstall while others don't, or what the difference is between editing the dashboard vs editing a plugin vs editing core packages. A contributor following the guide as written will spend hours debugging before anything works.

---

2. Critical pnpm details are missing from the docs

Two things that are required but not documented anywhere:

a) public-hoist-pattern[]=@medusajs/* in .npmrc

Without this, @medusajs/* packages stay inside the .pnpm store and are invisible to Medusa's internal dynamic require() calls. Result: cryptic module-not-found errors at runtime with no indication of what's wrong.

b) Vite alias ordering for Dashboard HMR

The CSS subpath alias (@medusajs/dashboard/css) must be declared before the catch-all alias (@medusajs/dashboard) in the Vite config - otherwise styles silently break. Both are only discoverable by trial and error.

---

3. Plugins have no hot reload - the feedback loop is terrible

Editing the admin dashboard gets you instant HMR thanks to Vite. Editing a plugin (draft-order, loyalty, etc.) requires:

1. yarn build (full rebuild, no watch mode)
2. pnpm install --force in the test project
3. Restart the dev server

Every. Single. Change.

medusa plugin:build uses esbuild under the hood, which natively supports --watch. There's no technical reason plugins can't have a watch mode - it's just not wired up. This makes plugin development feel like a second-class experience compared to dashboard development.

---

4. There is no docs.medusajs.com page for code contributors

A contributor looking for guidance on how to set up a local fork and iterate on code will find nothing on the official documentation site. The contribution guide on docs.medusajs.com covers only documentation writing. Code contributors are left with just the CONTRIBUTING.md, which is incomplete.

How can this issue be resolved?

1. Add a "Contributing code - local development" page to docs.medusajs.com that covers the full workflow end to end (fork setup, file: references, pnpm.overrides, .npmrc, Vite aliases, what to rebuild and when)

2. Update CONTRIBUTING.md with the missing details:

   • Required .npmrc entry: public-hoist-pattern[]=@medusajs/*
   • Vite alias ordering for Dashboard HMR (CSS alias must come first)
   • A clear table: "what you changed → what you need to do"

3. Add watch mode to plugin packages - wire up esbuild --watch as a yarn watch script in plugin package.json so contributors get the same fast feedback loop as dashboard development

Are you interested in working on this issue?

• I would like to fix this issue