Module Federation Contributing Guide

March 10, 2026 · View on GitHub

Thank you for your interest in contributing to Module Federation! Before starting your contribution, please take a moment to read the following guidelines.

Sending a Pull Request

  1. Fork the Module Federation repository into your own GitHub account.
  2. Clone the repository to your local machine.
  3. Checkout a new branch from main or canary.
  4. Set up the development environment. Refer to the "Setup Development Environment" section below for guidance.
  5. If you've fixed a bug or added code that should be tested, add some tests.
  6. Ensure all tests pass. See the "Testing" section below for more information.
  7. Run pnpm exec prettier --write . and pnpm exec turbo run lint to check and fix code style.
  8. If you've changed Node.js packages, run npm run commit for semantic versioning and commit.
  9. Submit the Pull Request, ensuring all CI runs pass.
  10. Your Pull Request will be reviewed by the maintainers soon.

Note:

  • Keep your PRs concise, addressing a single issue or feature.
  • Include a detailed description in your PR and link to related issues.

Setup Development Environment

Install Node.js

We recommend using Node.js 20 LTS. Check your Node.js version with node -v.

To install Node.js, use nvm or fnm:

# Install Node.js 20 LTS
nvm install 20 --lts
nvm alias default 20
nvm use 20

Install Dependencies

# Enable pnpm with corepack, only available on Node.js >= `v14.19.0`
corepack enable

pnpm install

What this will do:

  • Install all dependencies
  • Create symlinks between packages in the monorepo

Testing

Testing is a crucial part of the development process in Module Federation. Here's how you can run tests:

Running All Tests

To execute all test suites in the project, use:

pnpm exec turbo run test

This command runs every test across all projects in the repository.

Running Tests for Specific Projects

If you need to run tests for a specific project, use:

pnpm --filter PROJECT-NAME run test

Replace PROJECT-NAME with the actual package name (for example @module-federation/runtime-core).

Running Impacted Tests

To run tests only for the projects affected by recent changes, use:

pnpm run ci:local --only=build-and-test

This command ensures that only relevant tests are executed, saving time and resources.

Enhanced (packages/enhanced) Test Suites

The enhanced package uses Vitest with a custom runner that compiles webpack config cases and then executes their bundles in an isolated VM context.

  • Run all enhanced tests
pnpm --filter @module-federation/enhanced run test
  • Run a single enhanced case (by directory name)
# Example: only run the container/0-container-full case
npx vitest -c packages/enhanced/vitest.config.ts -t "0-container-full should compile"

# Or target a specific test file and group
npx vitest -c packages/enhanced/vitest.config.ts packages/enhanced/test/ConfigTestCases.basictest.vitest.ts -t "0-container-full should compile"
npx vitest -c packages/enhanced/vitest.config.ts packages/enhanced/test/ConfigTestCases.embedruntime.vitest.ts -t "0-container-full should compile"
  • Notes
    • Filters match the top-level test names created by the runner (e.g., <case-name> should compile).
    • Case-internal exported tests (the it(...) inside a case’s index.js) are aggregated and executed within that top-level test. Use the -t filter on the top-level name to run only that case.

Submitting Changes

Add a Changeset

Universe is using Changesets to manage the versioning and changelogs.

If you've changed some packages, you need add a new changeset for the changes. Please run changeset command to select the changed packages and add the changeset info.

pnpm run changeset

image

Committing your Changes

Commit your changes to your forked repo, and create a pull request.

Format of PR titles

The format of PR titles follow Conventional Commits.

An example:

feat(plugin-swc): Add `xxx` config
^    ^    ^
|    |    |__ Subject
|    |_______ Scope
|____________ Type

Releasing

Repository maintainers can publish a new version of changed packages to npm.

  1. Checkout a new release branch, for example release-v0.19.0.
  2. Run pnpm changeset version in the package directory to update the version of each package.
  3. Create a pull request, the title should be release v0.19.1.
  4. Run the release action to publish packages to npm.
  5. Select latest as the release version.
  6. Wait reviewers to approve.
  7. Merge the release pull request to main.
  8. Generate the release notes via GitHub, see Automatically generated release notes

Release preview version

  1. Make sure your branch has added changeset files before releasing the preview version.
  2. Run the release action to publish packages to npm.
  3. Select next as the release version.
  4. Wait reviewers to approve.

Release the official version

  1. Use the release pull request to release an official version
    • It will create a pull request that includes the changed version

image image

  1. If the version is normal, release it using release workflow and then a branch of pull request image

  2. Generate a release note based on the original tag after the release is complete

image