From 8a996a82a798e17d91e08da7dcdd6b43839fc8e0 Mon Sep 17 00:00:00 2001 From: Nicolas Gorga <62995075+NicolasGorga@users.noreply.github.com> Date: Fri, 3 Oct 2025 12:01:13 -0300 Subject: [PATCH] docs(): Add local development instructions in CONTRIBUTING.md (#13651) * Add local development instructions in CONTRIBUTING.md * Changes suggested by Shahed * Update CONTRIBUTING.md Co-authored-by: Shahed Nasser * Update CONTRIBUTING.md Co-authored-by: Shahed Nasser * Update CONTRIBUTING.md Co-authored-by: Shahed Nasser --------- Co-authored-by: Shahed Nasser Co-authored-by: William Bouchard <46496014+willbouch@users.noreply.github.com> --- CONTRIBUTING.md | 110 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c36bf1e386..ddcdd94bca 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,6 +23,116 @@ If you, as a community contributor, wish to work on more extensive features, ple 3. Make your changes. 4. [Open a pull request towards the develop branch in the Medusa repo](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork). Within a couple of days a Medusa team member will review, comment and eventually approve your PR. +## Local development + +> Prerequisites: +> 1. [Forked Medusa repository cloned locally](https://github.com/medusajs/medusa). +> 2. [A local Medusa application for testing](https://docs.medusajs.com/learn/installation). + + + +The code snippets in this section assume that your forked Medusa project and the test project are sibling directories, and you optionally setup the starter storefront as part of the installation. For example: + +``` +| +|__ medusa // forked repository +| +|__ test-project // medusa application for testing +| +|__ test-project_storefront // (optional) storefront to interact with medusa application +``` + + +1. Replace the @medusajs/* dependencies and devDependencies in you test project's `package.json` to point to the corresponding local packages in your forked Medusa repository. You will also need to add the medusa packages in the resolutions section of the `package.json`, so that every dependency is resolved locally. For example, assuming your forked Medusa project and the test project are sibling directories: + +```json +// test project package.json +"dependencies": { + // more deps + "@medusajs/admin-sdk": "file:../medusa/packages/admin/admin-sdk", + "@medusajs/cli": "file:../medusa/packages/cli/medusa-cli", + "@medusajs/framework": "file:../medusa/packages/core/framework", + "@medusajs/medusa": "file:../medusa/packages/medusa", +}, +"devDependencies": { + // more dev deps + "@medusajs/test-utils": "file:../medusa/packages/medusa-test-utils", +}, +"resolutions": { + // more resolutions + "@medusajs/test-utils": "file:../medusa/packages/medusa-test-utils", + "@medusajs/api-key": "file:../medusa/packages/modules/api-key", + "@medusajs/auth": "file:../medusa/packages/modules/auth", + "@medusajs/cache-inmemory": "file:../medusa/packages/modules/cache-inmemory", + "@medusajs/cache-redis": "file:../medusa/packages/modules/cache-redis", + "@medusajs/cart": "file:../medusa/packages/modules/cart", + "@medusajs/locking": "file:../medusa/packages/modules/locking", + "@medusajs/currency": "file:../medusa/packages/modules/currency", + "@medusajs/customer": "file:../medusa/packages/modules/customer", + "@medusajs/event-bus-local": "file:../medusa/packages/modules/event-bus-local", + "@medusajs/file": "file:../medusa/packages/modules/file", + "@medusajs/file-local": "file:../medusa/packages/modules/providers/file-local", + "@medusajs/fulfillment": "file:../medusa/packages/modules/fulfillment", + "@medusajs/fulfillment-manual": "file:../medusa/packages/modules/providers/fulfillment-manual", + "@medusajs/index": "file:../medusa/packages/modules/index", + "@medusajs/inventory": "file:../medusa/packages/modules/inventory", + "@medusajs/medusa": "file:../medusa/packages/medusa", + "@medusajs/notification": "file:../medusa/packages/modules/notification", + "@medusajs/notification-local": "file:../medusa/packages/modules/providers/notification-local", + "@medusajs/order": "file:../medusa/packages/modules/order", + "@medusajs/payment": "file:../medusa/packages/modules/payment", + "@medusajs/pricing": "file:../medusa/packages/modules/pricing", + "@medusajs/product": "file:../medusa/packages/modules/product", + "@medusajs/promotion": "file:../medusa/packages/modules/promotion", + "@medusajs/region": "file:../medusa/packages/modules/region", + "@medusajs/sales-channel": "file:../medusa/packages/modules/sales-channel", + "@medusajs/stock-location": "file:../medusa/packages/modules/stock-location", + "@medusajs/store": "file:../medusa/packages/modules/store", + "@medusajs/tax": "file:../medusa/packages/modules/tax", + "@medusajs/user": "file:../medusa/packages/modules/user", + "@medusajs/workflow-engine-inmemory": "file:../medusa/packages/modules/workflow-engine-inmemory", + "@medusajs/link-modules": "file:../medusa/packages/modules/link-modules", + "@medusajs/admin-bundler": "file:../medusa/packages/admin/admin-bundler", + "@medusajs/admin-sdk": "file:../medusa/packages/admin/admin-sdk", + "@medusajs/admin-shared": "file:../medusa/packages/admin/admin-shared", + "@medusajs/dashboard": "file:../medusa/packages/admin/dashboard", + "@medusajs/admin-vite-plugin": "file:../medusa/packages/admin/admin-vite-plugin", + "@medusajs/ui": "file:../medusa/packages/design-system/ui", + "@medusajs/icons": "file:../medusa/packages/design-system/icons", + "@medusajs/toolbox": "file:../medusa/packages/design-system/toolbox", + "@medusajs/ui-preset": "file:../medusa/packages/design-system/ui-preset", + "@medusajs/utils": "file:../medusa/packages/core/utils", + "@medusajs/types": "file:../medusa/packages/core/types", + "@medusajs/core-flows": "file:../medusa/packages/core/core-flows", + "@medusajs/orchestration": "file:../medusa/packages/core/orchestration", + "@medusajs/cli": "file:../medusa/packages/cli/medusa-cli", + "@medusajs/modules-sdk": "file:../medusa/packages/core/modules-sdk", + "@medusajs/workflows-sdk": "file:../medusa/packages/core/workflows-sdk", + "@medusajs/framework": "file:../medusa/packages/core/framework", + "@medusajs/auth-emailpass": "file:../medusa/packages/modules/providers/auth-emailpass", + "@medusajs/locking-redis": "file:../medusa/packages/modules/providers/locking-redis", + "@medusajs/locking-postgres": "file:../medusa/packages/modules/providers/locking-postgres", + "@medusajs/telemetry": "file:../medusa/packages/medusa-telemetry", + "@medusajs/settings": "file:../medusa/packages/modules/settings", + "@medusajs/draft-order": "file:../medusa/packages/plugins/draft-order", + "@medusajs/deps": "file:../medusa/packages/deps", + "@medusajs/caching-redis": "file:../medusa/packages/modules/providers/caching-redis", + "@medusajs/caching": "file:../medusa/packages/modules/caching" +} +``` + +2. Every time you make a change in the forked Medusa repository, you need to build the packages where the modifications took place with `yarn build`. Some packages have a watch script, so you can execute `yarn watch` once and it will automatically build on changes: + +```bash +yarn build # or yarn watch +``` + +3. After building changes in the forked medusa repository, run the following command in the test project to regenerate the `node_modules` directory with the newly built contents from the previous step: + +``` +rm -R node_modules && yarn && yarn dev +``` + ## Workflow ### Branches