import { Prerequisites } from "docs-ui"

export const metadata = { title: Code Contribution Guidelines, }

{metadata.title}

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.

This guide is specific to contributing to Medusa's codebase. If you're interested in contributing to the documentation, check out the Docs Contribution Guidelines.

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.

Before writing code, make sure there's an issue for your change. This lets others weigh in before you invest time. See Issues before PRs.

Prerequisites

<Prerequisites items={[ { text: "Forked Medusa repository cloned locally.", link: "https://github.com/medusajs/medusa" }, { text: "A local Medusa application for testing.", link: "https://docs.medusajs.com/learn/installation" } ]} />

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

|
|__ 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:

"dependencies": {
  "@medusajs/cli": "file:../medusa/packages/cli/medusa-cli",
  "@medusajs/framework": "file:../medusa/packages/core/framework",
  "@medusajs/medusa": "file:../medusa/packages/medusa"
}

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:

# 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.