fastled 2.0.12

FastLED Wasm Compiler

FastLED WASM Compiler

	Build	Lint	Unit Test	Integration Test
Linux x86
Linux ARM
Windows x86
Windows ARM
macOS x86
macOS ARM

Compile your FastLED sketch and run it on the browser!

Demo

https://zackees.github.io/fastled-wasm/

About

Compile FastLED sketches to browser-ready html/js/wasm output using a native Emscripten toolchain.

Compile times are extremely fast thanks to aggressive object caching and sketch fingerprinting. Recompilation of sketch files with minimal changes completes in under a second.

Tutorial Video

Note: This video predates the Rust CLI migration. Install with pip install fastled and run with fastled mysketchfolder.

https://github.com/user-attachments/assets/64ae0e6c-5f8b-4830-ab87-dcc25bc61218

Install

pip install fastled

Alternative installers:

• uv pip install fastled --system
• pipx install fastled

Executables

Pre-built binaries are published on each GitHub release:

• Windows x64
• macOS ARM (M1+)
• macOS x86
• Linux x64

Ubuntu Install Script

curl -L https://raw.githubusercontent.com/zackees/fastled-wasm/refs/heads/main/install_linux.sh | /bin/bash

Run

Change into a sketch directory and run:

fastled

Useful flags:

Flag	Description
--just-compile	Compile and exit without opening a browser or watching files
--debug	Build with debug-friendly compiler settings
--quick	Default build mode
--release	Optimized build (~1/3 smaller binary)
--fastled-path <path>	Point the build at a local FastLED checkout
--purge	Clear cached FastLED downloads and stale WASM build artifacts
--serve-dir <dir>	Serve an existing directory without compiling

Set FASTLED_VIEWER_LOGS=1 to forward the viewer window's browser console output (console.*, uncaught errors, failed fetches) to the terminal's stderr, prefixed with [viewer] — useful when diagnosing a blank or broken viewer.

Features

Hot Reload

Once launched, the compiler remains open and watches for file changes. Edits to your sketch are automatically recompiled and the browser reloads with the updated output. Build output is streamed to the browser in real time via SSE.

Hot Reload FastLED Source

If you launch fastled inside the FastLED repo with --fastled-path, changes to the library source code are detected and trigger recompilation. Unlike sketch-only rebuilds, modifying a header file may produce a longer recompile.

Big Data in /data Directory

Large files (e.g. video) in a sketch's data/ directory are handled specially to avoid round-tripping blobs. The WASM compiler generates a files.json manifest for an emulated SD card system mounted at /data/. Files named *.json, *.csv, *.txt are injected before setup() runs; all others are streamed asynchronously at runtime.

For an example see examples/SdCard in the FastLED repo.

Compile Speed

Three compile modes are available: --quick (default), --release (optimized for size, ~1/3 smaller binary), and --debug (debug-friendly compiler settings). Aggressive object caching means incremental rebuilds are near-instant.

Arduino Compatibility

Most simple Arduino sketches compile out of the box. Common functions like digitalWrite(), Serial.println(), and others are stubbed. digitalRead() returns 0 and analogRead() returns random numbers.

HTTPS

The local preview server supports HTTPS using the bundled localhost certificate pair. HTTPS is required for browser features such as microphone access. See HTTPS_SSL.md.

Python Package

The fastled Python package is a compatibility launcher for the native Rust CLI. Internal build, project discovery, and fuzzy matching behavior lives in Rust and is tested there.

FAQs

Q: Why does FastLED become choppy when the browser tab is in the background? A: FastLED WASM currently runs on the main thread. Chrome throttles the event loop for background tabs. Moving to a Web Worker would solve this.

Q: Why does a long delay() freeze the browser? A: delay() blocks loop() which blocks the main thread. A Web Worker would decouple FastLED from the browser's UI thread.

Q: How can I reduce the compiled size of my sketch? A: A significant portion of the binary is Emscripten JS bundling overhead. The wasm_compiler_settings.py in the FastLED repo can tune this. Using --release produces a ~1/3 smaller binary than --quick.

Development

./install
./test
./lint