Code Contribution Guidelines

Thank you for your interest in contributing to Medusa's codebase! This guide walks you through setting up a local development environment, linking your fork to a test project, and iterating on changes with hot reload.

What Can You Contribute?#

You can contribute to Medusa's codebase in the following ways:

• Bug fixes to packages, modules, or plugins.
• New features, after opening an issue to confirm the approach with the team.
• Improvements to tooling and the contributor developer experience.

Prerequisites#

The snippets below assume your forked Medusa project and your test project are sibling directories:

Terminal
❯|❯|__ medusa        // forked repository❯|❯|__ test-project  // Medusa application for testing

Linking Your Fork to a Test Project#

To test local changes, point your test project's @medusajs/* dependencies at your local packages and resolve every transitive dependency locally.

1. In your test project's package.json, replace the @medusajs/* entries in dependencies and devDependencies with file: references to your fork:

Code
1"dependencies": {2  "@medusajs/cli": "file:../medusa/packages/cli/medusa-cli",3  "@medusajs/framework": "file:../medusa/packages/core/framework",4  "@medusajs/medusa": "file:../medusa/packages/medusa"5}

2. Add the full set of packages under resolutions so transitive dependencies also resolve locally. See the complete list in CONTRIBUTING.md.

Iterating with Watch Mode#

After building your fork, you can iterate without a full rebuild on each change.

• For most packages, use the package's dev or watch script.
• For plugin packages (packages/plugins/*), use the watch flow:

Terminal
❯# inside the plugin package❯yarn watch       # swc watch + yalc publish on change (medusa plugin:develop)❯yarn link:watch  # publish once, then watch

Under the hood, medusa plugin:develop watches your source, transforms it with @swc/core, and republishes via yalc so your linked test project picks up changes automatically.

Opening a Pull Request#

Branch out from develop, make your changes, and open a pull request against develop. A team member will review within a few days.