How to Contribute to SWC: Setting Up the Development Environment and Running Tests

Contributing to SWC requires forking the repository, installing Rust and pnpm, initializing git submodules, and running the test suite with specific feature flags like swc_v1 or swc_v2 to validate your changes.

SWC (Speedy Web Compiler) is a high-performance TypeScript/JavaScript compiler written in Rust and hosted at swc-project/swc. Setting up a local development environment involves configuring the Rust toolchain, managing JavaScript dependencies, and understanding the workspace structure defined in the root Cargo.toml. This guide walks you through the exact steps required to build the project, run tests, and validate changes against downstream JavaScript projects.

Fork and Clone the Repository

SWC follows a standard fork-and-pull-request workflow. Start by forking the repository on GitHub, then clone your fork locally and create a feature branch off main.

git clone https://github.com/YOUR_USERNAME/swc.git
cd swc
git checkout -b feature/your-change-name

Install Required Development Tools

The SWC codebase requires both Rust and Node.js ecosystem tools to build and test properly.

Rust Toolchain

You need the stable Rust compiler to build the core crates. Install it via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://rustup.rs | sh

You must also add the WebAssembly target for running certain tests:

rustup target add wasm32-wasip1

System Dependencies

• make: Required for build helper scripts (pre-installed on most Unix systems; Windows users should install MinGW/MSYS2)
• C/C++ compiler: gcc or clang on Linux/macOS, MSVC on Windows, needed for building native crates

JavaScript Package Manager

Install pnpm to manage JavaScript dependencies in the bindings/ directory:

npm install -g pnpm

Optional Tools

• fd: A fast file finder used by git hooks, installable via cargo install fd-find
• deno: Required only for running Deno-specific test fixtures

Initialize the Repository

After cloning, you must pull the ECMAScript test suites and install JavaScript dependencies:

git submodule update --init --recursive
pnpm install

This populates the test fixtures and prepares the @swc/core package bindings.

Configure Environment Variables

Set these variables in your shell to ensure full stack traces and proper binary discovery:

export RUST_BACKTRACE=full
export PATH="$PATH:$PWD/node_modules/.bin"
export RUST_MIN_STACK=16777216

The RUST_MIN_STACK variable prevents stack overflow errors during deep recursive parsing, while updating PATH makes the locally built @swc/core binary discoverable by the test harness.

Build and Run Tests

SWC maintains two parser implementations selectable via feature flags. You must choose which feature set matches your code changes when running tests.

Running the Full Test Suite

For the original parser implementation:

cargo test --all --no-default-features --features swc_v1 --features filesystem_cache

For the newer parser implementation:

cargo test --all --no-default-features --features swc_v2 --features filesystem_cache

Testing Individual Crates

If the full suite is too heavy for rapid iteration, run tests for a specific crate. For example, to test only the ECMAScript transforms:

cargo test -p swc_ecma_transforms --all-features

The test harness uses helper utilities from crates/testing/src/lib.rs to compare input and output fixtures.

Test Changes Against Downstream Projects

To validate your Rust changes in a real JavaScript project that consumes @swc/core, use the provided patch script at scripts/patch-project.sh:

./scripts/patch-project.sh /path/to/your/js/project

This script performs three actions:

1. Patches bindings/Cargo.toml to point to your local build
2. Rebuilds the Rust bindings
3. Updates the downstream project's package.json to reference the locally built package

To revert the changes after testing:

git restore bindings/Cargo.toml bindings/Cargo.lock

Then restore the original @swc/core entry in your downstream project's package.json.

Submit Your Contribution

Push your branch to your fork and open a pull request against swc-project/swc:main. The CI system will run the full test suite on your branch before merging. For architectural guidance, consult ARCHITECTURE.md in the repository root, which details the module layout and data flow between the parser, transformer, and code generator.

Contribute to Documentation

Documentation fixes for https://swc.rs do not belong in the main repository. Each page on the website contains an "Edit this page on GitHub" link that points to the separate website repository. Edit the Markdown files there and submit your PR to the documentation repo instead.

Summary

• Fork the swc-project/swc repository and create a feature branch off main
• Install Rust (stable), pnpm, make, and a C/C++ compiler, plus the wasm32-wasip1 target
• Initialize submodules with git submodule update --init --recursive and run pnpm install
• Export required environment variables including RUST_BACKTRACE=full and RUST_MIN_STACK=16777216
• Test using cargo test with --features swc_v1 or --features swc_v2 depending on which parser you are modifying
• Validate locally against JavaScript projects using ./scripts/patch-project.sh
• Reference CONTRIBUTING.md and ARCHITECTURE.md for detailed contribution guidelines

Frequently Asked Questions

Do I need to install Deno to contribute to SWC?

No, Deno is only required for running Deno-specific test fixtures. You can contribute to the core Rust compiler and JavaScript bindings without installing Deno, though you should install it if you are modifying code that affects Deno compatibility.

How do I test my local SWC changes in a JavaScript project?

Use the scripts/patch-project.sh script to temporarily replace the npm package @swc/core in your target project with your local build. The script modifies bindings/Cargo.toml, rebuilds the native bindings, and updates the downstream package.json to point to your local build artifacts.

What is the difference between the swc_v1 and swc_v2 test features?

swc_v1 enables the original SWC parser, while swc_v2 activates the newer parser implementation. You must pass the corresponding feature flag to cargo test depending on which parser code your changes affect. Both require the filesystem_cache feature for full test suite compatibility.

Where should I submit documentation fixes?

Documentation for the SWC website lives in a separate repository from the main compiler. Click the "Edit this page on GitHub" link on any page at https://swc.rs to navigate directly to the source file in the website repository, then submit your pull request there.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}