wasm-opt: Optimize Wasm with Binaryen in CI
wasm-opt runs Binaryen optimization passes over a module to make it smaller and faster.
wasm-opt is the standard size and speed optimizer for wasm, run automatically by wasm-pack and often as an explicit CI step. The -O levels trade compile time for output quality.
What it does
wasm-opt reads a .wasm, applies optimization passes at the chosen level (-O, -O2, -O3, -Os, -Oz), and writes an optimized module. Proposal features the input uses must be enabled so the optimizer parses them.
Common usage
wasm-opt -O3 input.wasm -o output.wasm
wasm-opt -Oz input.wasm -o output.wasm
wasm-opt -O2 --enable-simd input.wasm -o output.wasm
wasm-opt --enable-bulk-memory -O input.wasm -o output.wasmOptions
| Flag | What it does |
|---|---|
| -O / -O2 / -O3 | Increasing optimization for speed |
| -Os / -Oz | Optimize for size (-Oz is the most aggressive) |
| -o <file> | Output path (required to write a file) |
| --enable-<feature> | Allow a proposal (e.g. --enable-simd, --enable-bulk-memory) |
| -g | Preserve the name/debug info section |
In CI
If the input uses a proposal (SIMD, bulk memory, reference types), pass the matching --enable- flag or wasm-opt refuses to parse it. Add -o explicitly; without it wasm-opt validates but writes no file. Cache the Binaryen install to avoid re-downloading each run.
Common errors in CI
"wasm-opt: command not found" means Binaryen is not installed; install it or pass the toolchain step --no-opt where the caller supports it. "Fatal: error parsing wasm ... br_table" or "unexpected true: ... requires <feature>" means a proposal feature needs --enable-. "Fatal: error in validating input" means the module fails Binaryen validation.