@bitruvius/turbo-jxl

JPEG XL tiles decoded in the browser. No plugin, no fork.

TurboJXL is an encode-first, memory-safe JPEG XL codec built for next-generation 256² and 512² tile pyramids: web maps, COG overviews, tile servers. This package is its decode side, a pure-Rust decoder compiled to sandboxed WebAssembly for browsers and Node/Bun (no emscripten, no C dependencies).

Turbocharged by Bitruvius TurboJXL.

What makes it different

Memory-safe by construction. The bitstream parser is pure Rust, which eliminates the buffer-overflow, use-after-free and out-of-bounds CVE class you inherit when you parse untrusted image data in C. It then runs inside the WebAssembly sandbox on top of that.

Zero C dependencies. No libjxl at runtime, no C compiler, no cmake. You install a package and decode.

Deterministic. Bytes in, bytes out. Bitruvius reports the codec as bit-exact with libjxl 0.11.2 in both directions, with 285 / 285 samples passing cross-codec round-trip at e=1 / e=3 / e=7 on AVX2 and NEON. Those figures are measured on the native builds; this package ships the WebAssembly decoder.

The encoder side of the codec

These are the results Bitruvius publishes for the native TurboJXL encoder. The encoder is not part of this npm package (see Install).

Bitruvius states the caveat this way: "Performance comparisons reflect our own measurements under the stated methodology; results vary by workload and hardware."

Use it

import { JxlDecoder } from '@bitruvius/turbo-jxl';

const bytes = new Uint8Array(await (await fetch('/tile.jxl')).arrayBuffer());
const img = await new JxlDecoder().decode(bytes);
// { width, height, hasAlpha, premultipliedAlpha, rgba: Uint8Array }
Copy

rgba is RGBA8, row-major from the top-left, so it goes straight to a canvas:

const pixels = new Uint8ClampedArray(img.rgba.buffer, img.rgba.byteOffset, img.rgba.length);
ctx.putImageData(new ImageData(pixels, img.width, img.height), 0, 0);
Copy

One decoder instance handles any number of images. The wasm loads lazily on your first decode() and is shared across decoders in the same mode.

What decodes

Measured against the ISO/IEC 18181-3 conformance corpus: VarDCT and modular, greyscale, 8- to 32-bit samples, straight and premultiplied alpha, patches, splines, noise, progressive, upsampling, JPEG-recompressed streams, and the first frame of an animation.

Coverage is broad but not complete. Streams built from multi-layer or blend-mode frame compositing, and streams carrying non-colour extra channels (CMYK Black, spot colour), reject. The package's conformance tests pin most of that matrix to real corpus bitstreams; the CMYK and spot-colour rejection cases are verified but not vendored, on file-size grounds.

Multithreaded decode (opt-in)

A second build parallelizes decode across Web Workers. Enable it per decoder:

import { JxlDecoder, canUseThreads } from '@bitruvius/turbo-jxl';

// canUseThreads() reports whether this page is eligible, before you ask for it.
const img = await new JxlDecoder({ threads: canUseThreads() ? 'auto' : false }).decode(bytes);
Copy

threads takes 'auto' (uses navigator.hardwareConcurrency, falling back to 4), an explicit thread count, or false. It is honored only on a cross-origin-isolated page, so the host must send Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp. Everywhere else, including Node and Bun, decode runs single-threaded rather than failing.

canUseThreads() reports page eligibility, meaning SharedArrayBuffer plus crossOriginIsolated. It does not report which build actually loaded. An eligible page can still fail to spawn the worker pool, most often when the SDK itself is served cross-origin from a CDN with no same-origin worker; decode logs a warning and continues single-threaded.

Install

npm i @bitruvius/turbo-jxl
Copy

The only runtime dependency is @bitruvius/foundation. There are no peer dependencies and no native build step. Single-threaded decode is the default and runs everywhere: browsers, Node 18+ and Bun.

Three wasm artifacts ship in the package and the right one is selected for you: a universal +simd128 build, a +relaxed-simd build used automatically on engines that validate the opcode (Chrome 114+, Firefox 120+, Safari 18+), and the opt-in threaded build. All three resolve relative to the package. To serve them from your own CDN, set the base URL once:

import { configure } from '@bitruvius/foundation';

configure({ wasmBaseUrl: 'https://cdn.example.com/bitruvius/wasm/' });
Copy

Node and Bun do not fetch the sibling asset, so hand the decoder the bytes:

import { readFile } from 'node:fs/promises';
import { createRequire } from 'node:module';
import { JxlDecoder } from '@bitruvius/turbo-jxl';

const resolve = createRequire(import.meta.url).resolve;
const wasmBytes = await readFile(resolve('@bitruvius/turbo-jxl/wasm/turbojxl_wasm_bg.wasm'));
const img = await new JxlDecoder({ wasmInit: { wasmBytes } }).decode(bytes);
Copy

A self-contained ESM bundle is published on the Bitruvius CDN if you would rather skip the bundler.

This package decodes. It does not encode. The encode-side results above come from the native TurboJXL codec, and the libjxl drop-in for cjxl and djxl is listed on bitruvius.com as coming soon. Install this expecting a decoder.

The SDK license is royalty-free for commercial and non-commercial applications. See LICENSE for the terms.

Learn more

• Live examples: running, with source
• Documentation: guides and the full API reference
• Support: questions and issues
• TurboJXL on bitruvius.com: benchmarks and format details

Trademarks

JPEG XL is a standard of the Joint Photographic Experts Group. libjxl is the reference JPEG XL implementation, and cjxl and djxl are its encoder and decoder tools, published by the libjxl project under the BSD-3-Clause license. Node.js is a trademark of the OpenJS Foundation. All other marks are the property of their respective owners.

These names are used solely to describe the data formats this software interoperates with. Bitruvius is not affiliated with, sponsored by, or endorsed by any of them, and no such relationship is implied.

License

Proprietary. The full terms ship as LICENSE inside this package, and are readable before installing at cdn.bitruvius.com/legal/sdk-license-v1.txt.

© Bitruvius, Inc.