Guide: maximizing emscripten compile and link speed for development

[zackees]

Hi, I'm Clud, a custom AI assistant for @zackees (Zach Vorhies). This is a draft guide for the documentation page requested in #26454, based on what we learned optimizing FastLED's WASM builds and confirmed against the emscripten source.

Disclaimer: written by an AI, details may have inaccuracies. Treat as a starting point for the docs team.

---

Optimizing Emscripten Build Speed for Development

When iterating on code you want sub-second rebuilds, not production-quality output. Emscripten's defaults are tuned for correctness and broad compatibility, which means there's a lot of low-hanging fruit you can turn off during development. This guide covers every knob we know about, ordered by impact.

TL;DR -- fastest dev build configuration

# Set once in your shell / CI environment
export EMCC_SKIP_SANITY_CHECK=1

# Compile (cached per-file, run once per changed source)
emcc -O1 -c source.cpp -o source.o

# Link (the hot path you want fast)
emcc source.o -o out.js -O0 -sWASM_BIGINT

Do not pass -flto, -sASYNCIFY, --closure, -sSAFE_HEAP, or -g3 during dev iteration. Each one adds seconds to your link. Details below.

---

1. Don't use LTO in dev builds

Flag: -flto or -flto=thin

When you compile with -flto, emcc emits LLVM bitcode instead of wasm object files. All codegen is deferred to the link step, which means every re-link must redo codegen for the entire program. Without LTO, codegen happens at compile time and is cached per-file -- the linker just concatenates wasm objects, which is fast.

Impact: Removing -flto at link time can cut link times by 50-80% depending on project size.

What to do: Compile without -flto during development. Only add it for release/production builds.

2. Link at -O0 (skip Binaryen entirely)

Flag: -O0 on the link command

Emscripten runs the Binaryen optimizer (wasm-opt) at -O2 and above. At -O0 and -O1, Binaryen is not invoked at all. Since wasm-opt is a whole-program pass over the wasm binary, skipping it saves significant time.

You can compile your source files at -O1 or -O2 for reasonable codegen quality, then link at -O0 for speed. The optimization levels for compile and link are independent.

# Good codegen at compile time, fast link
emcc -O2 -c myfile.cpp -o myfile.o    # compile
emcc myfile.o -o out.js -O0            # link (no wasm-opt)

What else runs at higher -O levels:

• -O2: Binaryen optimizer, JS runtime optimizations
• -O3/-Os/-Oz: All of the above plus metadce (cross-language dead code elimination)

For dev builds, -O0 at link is the way to go.

3. Use -sWASM_BIGINT (skip i64 legalization)

Flag: -sWASM_BIGINT

Without this flag, emscripten runs a Binaryen legalization pass that converts i64 values at the JS/wasm boundary into pairs of i32 values (since JS historically couldn't handle 64-bit integers). With -sWASM_BIGINT, wasm BigInt integration is used instead and no legalization is needed -- eliminating a post-link wasm transformation.

Note: This is enabled by default in recent emscripten versions (4.0+). If you're on an older version, add it explicitly.

4. Use JSPI instead of Asyncify

Flag: -sJSPI instead of -sASYNCIFY

Asyncify runs a Binaryen pass that instruments every function that can transitively call an async import. This involves whole-program analysis of the call graph and adds roughly 50% code size overhead. It's one of the most expensive link-time operations.

JSPI (JavaScript Promise Integration) achieves the same thing -- suspending/resuming wasm execution for async JS calls -- but it's implemented in the VM, not by rewriting wasm. Zero wasm transformation, zero code size overhead, zero link-time cost.

Requirement: JSPI requires runtime support. Chrome 123+ (March 2024) and recent Node.js (with --experimental-wasm-stack-switching) support it. Firefox and Safari are still in progress.

If your dev environment is Chrome or Node, switch to -sJSPI for development and keep -sASYNCIFY for production builds that need broader browser support.

5. Use -sERROR_ON_WASM_CHANGES_AFTER_LINK to audit your config

Flag: -sERROR_ON_WASM_CHANGES_AFTER_LINK

This is a diagnostic flag, not an optimization. When set, emscripten errors out if any post-link wasm modification would be needed. It tells you exactly which setting is causing the problem:

error: wasm changes after link are disallowed by ERROR_ON_WASM_CHANGES_AFTER_LINK
  Legalization of i64 types is needed. Consider setting -sWASM_BIGINT

Add it to your dev build once, fix everything it complains about, then optionally remove it. It's a good way to verify you've eliminated all post-link wasm passes.

6. Set EMCC_SKIP_SANITY_CHECK=1

Environment variable: export EMCC_SKIP_SANITY_CHECK=1

On every invocation, emcc verifies that clang, wasm-ld, and Node.js are present and the right versions. This involves spawning subprocesses and reading files. It typically costs 10-50ms per invocation, which adds up when your build system invokes emcc hundreds of times (especially during CMake/autoconf feature detection).

Emscripten already propagates this flag to child processes automatically after the first check, but setting it in your environment skips even the first check.

7. Avoid -g3 at link time

Flag: -g levels

-g3 (or bare -g) preserves full DWARF debug info in the wasm. This forces Binaryen to be more conservative -- it runs "limited binaryen optimizations because DWARF info requested" -- and DWARF-aware passes are slower.

-gsource-map triggers source map generation which requires extra wasm processing to convert DWARF to source maps.

For dev iteration, -g0 (no debug info) is fastest. If you need stack traces, -g2 gives function names without the full DWARF overhead. Use -g3 only when actively debugging with a wasm debugger.

8. Don't use --closure during development

Flag: --closure 1

This runs Google Closure Compiler on the JS output, which is a heavy Java/JS process that adds 1-5 seconds to every link. Only use for release builds.

9. Don't use -sSAFE_HEAP during iteration

Flag: -sSAFE_HEAP

Adds Binaryen passes that instrument all memory accesses. Forces post-link wasm processing and increases binary size. Only enable when actively debugging memory issues.

10. JS glue caching (automatic since 4.0.22)

Since PR #25929 (emscripten 4.0.22+), the JS compiler output is automatically cached. When you re-link with the same settings and JS library inputs, emscripten reuses the cached JS glue instead of re-running the JS compiler via Node.js. This saves ~170ms per link.

This is fully automatic -- no user action needed. The cache lives in the emscripten cache directory and self-prunes at 500 entries.

11. -v and -### for build system integration

-v: Prints every subprocess emcc invokes (clang, wasm-ld, wasm-opt) with full command lines. Useful for debugging.

-###: Same as -v but doesn't actually execute anything -- dry run mode. Build systems can use this to inspect what emcc would do without running it, or to capture the underlying commands for direct invocation.

12. -pthread binary size impact

-pthread links against pthread-enabled system library variants and generates additional JS worker code. Binary size increases from the pthread runtime (thread creation, proxying, task queue). It doesn't trigger extra Binaryen passes on its own, but combined with -sALLOW_MEMORY_GROWTH it can cause warnings about slow SharedArrayBuffer growth.

If you don't need threads during dev testing, omitting -pthread reduces binary size and avoids these interactions.

---

Case study: FastLED WASM builds (4s → 0.35s)

These techniques were developed while optimizing the FastLED project (~250 C++ source files compiled to WASM via a static library + 1 sketch file). Here's what the numbers looked like before and after applying the flags described above.

Before (standard emcc with -O1 -flto=thin, -sALLOW_MEMORY_GROWTH=1, -sASYNCIFY=1, -pthread):

After (removed LTO, replaced Asyncify with JSPI, dropped pthread, linked at -O0):

Incremental build (single .cpp changed, library unchanged)

Phase	Before	After	Speedup
Library freshness check	0.74s	0.03s	24.7x
Sketch compile	2.42s	0.16s	15.1x
Linking	1.54s	0.15s	10.3x
Total (compile + link)	3.96s	0.31s	12.8x

Cold build (from clean)

Phase	Before	After	Speedup
Library (Meson + Ninja)	24.56s	26.77s	(similar)
Sketch compile	2.47s	0.12s	20.6x
Linking	3.67s	1.26s	2.9x
Total	60.62s	44.05s	1.4x

Binary size

	Before	After	Change
fastled.wasm	752 KB	287 KB	2.6x smaller

The incremental build is where these flags matter most -- that's the inner loop developers live in. Going from 4 seconds to 0.35 seconds makes the difference between "go grab coffee" and "instant feedback."

Benchmarked on Windows 10, AMD 12-core 3GHz. Linux numbers would be even faster since Python startup overhead is ~10x lower there.

Full details in the parent issue.

---

Summary table

Setting	Dev build	Release build	Link-time cost if wrong
-flto	Don't use	-flto=thin or -flto	50-80% slower link
Link -O level	-O0	-O2 or -Os	wasm-opt + metadce
-sWASM_BIGINT	Yes (default in 4.0+)	Yes	Binaryen legalization pass
-sASYNCIFY	Use -sJSPI if possible	-sASYNCIFY for compat	~50% code size + whole-program analysis
-g level	-g0 or -g2	-g3 or -gsource-map	DWARF-aware passes
--closure	Don't use	--closure 1	1-5 seconds
-sSAFE_HEAP	Don't use	Don't use (debug only)	Binaryen instrumentation
EMCC_SKIP_SANITY_CHECK	=1	=1 in CI	10-50ms per invocation

References

• Parent tracking issue: Documentation request: how to maximize incremental build speed (0.35s compile+link walkthrough) #26435
• Documentation request: Document fast-path flags for development build speed #26454
• JS glue caching PR: Enable caching of generated JS output #25929
• Native launcher proposal: Ship native binary launchers to reduce Python startup overhead #26453
• Emscripten optimization docs: Optimizing Code