building/wasm

15 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Turbopack WASM target: wasm32-wasip1-threads

Turbopack's napi bindings can be compiled for the wasm32-wasip1-threads target. This target allows Turbopack to run on unusual CPU architectures and operating systems where native bindings are not published.

Difference between Turbopack WASM and SWC WASM packages

Turbopack WASM (wasm32-wasip1-threads) is distinct from the @next/swc-wasm-* packages. The SWC WASM packages are built with wasm-pack from crates/wasm for wasm32-unknown-unknown and contain only SWC, not Turbopack.

WASM build prerequisites: WASI clang, sysroot, and emnapi

Building Turbopack for wasm32-wasip1-threads requires a WASI clang and sysroot (because several dependencies have C build scripts) and emnapi (needed by napi's build script). The setup-wasi-env.sh script provisions both.

Building Turbopack WASM on Linux: source setup script

On Linux, source the setup-wasi-env.sh script then run: cargo check -p next-napi-bindings --target wasm32-wasip1-threads. The script must be sourced from Bash (not run directly or in a subprocess) because it uses BASH_SOURCE and exports environment variables into the calling shell.

Building Turbopack WASM in zsh or alternative shells

On shells like zsh, explicitly invoke Bash: bash -c 'source scripts/setup-wasi-env.sh && cargo check -p next-napi-bindings --target wasm32-wasip1-threads'. The setup script cannot be sourced from alternative shells directly because it uses BASH_SOURCE.

setup-wasi-env.sh script behavior and caching

The setup-wasi-env.sh script downloads wasi-sdk matching your host architecture, verifies it against a pinned sha256, installs emnapi, and exports cross-compilation variables (WASI_SDK_PATH, EMNAPI_LINK_DIR, and *_wasm32_wasip1_threads compiler variables). Downloads are cached under ~/.cache/next-wasi-toolchain for fast re-sourcing. Set WASI_SETUP_CACHE_DIR to move the cache location.

Building Turbopack WASM with Docker

On macOS, Windows, or any Docker-capable host, use the Linux builder image with: docker build -t next-wasi-builder -f scripts/wasi-builder.Dockerfile . && docker run --rm -it -v "$PWD:/workspace" -v next-wasi-cache:/root/.cache/next-wasi-toolchain -w /workspace next-wasi-builder. Inside the container, source scripts/setup-wasi-env.sh and run cargo commands as on Linux.

Docker volume preservation for WASM builds

The named volume next-wasi-cache preserves wasi-sdk and emnapi downloads between Docker runs. Mount a second volume at /workspace/target to also preserve Rust build artifacts without writing them to the host checkout.

Running WASM tests for Turbopack

WASM test binaries cannot be run directly. Turbo-tasks gathers task registries at link time and needs the embedder to supply an env.read_custom_section import. The scripts/wasi-test-host/ directory contains a Node host that provides it, along with WASI preview1 and thread spawning. Sourcing setup-wasi-env.sh points Cargo's runner at that host, enabling tests with: cargo test -p turbo-tasks --lib --target wasm32-wasip1-threads

WASM test skipping and platform limitations

Some tests are skipped on WASM. Each carries a reason describing the specific platform limitation, such as no unwinding, no mmap, and so on.

Clippy linting for Turbopack WASM builds

Use --lib --tests rather than --all-targets when running clippy for WASM. --all-targets includes benchmark targets that depend on criterion (and rayon) and cannot build for WASI. Run: cargo clippy -p turbo-tasks --lib --tests --target wasm32-wasip1-threads -- -D warnings

emnapi version requirement and prerelease status

emnapi v2 is a prerelease. napi-build needs the emnapi_create_env and emnapi_delete_env exports, which exist only in v2. The setup script pins emnapi@2.0.0-alpha.4. Move to the stable release once it ships.

Turbopack WASM full napi build not yet wired up

A full napi build is not wired up yet for the same reason as the emnapi v2 prerelease requirement. CI currently compiles and runs tests rather than producing a publishable artifact.

JavaScript-side artifact loading not yet implemented

The JavaScript side cannot load the Turbopack WASM artifact yet. It needs a loader that supplies env.read_custom_section and runs the module's initialization, which does not exist.

Unavailable features on Turbopack WASM

Some features are unavailable on WASM and report an error when configured: SWC WASM plugins and anything requiring the child-process pool.

Give your agent this brain