Skip to content

Architecture

Dus Mamud edited this page Nov 9, 2026 · 1 revision

Architecture

The shape of it

your app
   │
   ▼
@dusrel/image            one-call API · fluent pipeline · plugins · batch
   │
   ├── @dusrel/image-core        zero-dependency Canvas engine (Layer A)
   │
   └── Layer B — install only what you use, each lazily loaded:
       ├── codecs    jpeg · webp · avif · png · oxipng · jxl · qoi · heic
       ├── tools     resize · quantize · gif
       ├── features  crop · transform · adjust · metadata · watermark
       │             batch · svg · placeholder
       └── bindings  react · vue · svelte

Design rules that hold across all 24 packages:

  • Layer B mirrors the sub-package model throughout — every codec and tool is separately installable, separately lazy-loaded (its own WASM), with separate encode/decode entries, ESM-only, worker-ready.
  • No codec WASM in the core, ever. The core stays a few KB.
  • Maximum features, maximum control. Defaults are easy; every step, codec and fallback is overridable.
  • Step order is fixed: crop → transform → resize → adjust → watermark → encode. Consecutive canvas ops merge into one pass.
  • Engines are reused, not rewritten. The proven native codecs (MozJPEG, libwebp, libavif, libjxl, libheif) and Rust crates (png, oxipng, resize, quantizr, qoi, gif) are compiled to WASM the way the Squoosh/jSquash family does it; everything around them — core, pipeline, API, packages, tests, docs — is original to this project.

Decision records (ADRs)

The reasoning lives in docs/adr/ in the repository. The ones people ask about most:

ADR Decision
0003 Licence-driven engine swaps: quantizr instead of libimagequant (GPL), Rust gif crate instead of gifsicle (GPL) — every package stays MIT
0004 WASM builds use plain cargo + the wasm-bindgen CLI (not wasm-pack), one pinned Docker image per codec family
0006 Single-threaded WASM by default — no SharedArrayBuffer, no COOP/COEP requirement; threaded builds are opt-in only
0007 Plugin API stabilised: plugins are never silently dropped; codecs are registrable as output formats; failures are typed errors
0008 HEIC decode ships as its own package with the LGPL-3.0 engine (libheif + libde265) fenced inside it; wrapper MIT
0009 Placeholders (ThumbHash + BlurHash) are implemented from spec in pure TypeScript — zero dependencies

Quality gates

A green build is not proof. Every codec build ends with a functional smoke gate (a real encode/decode inside the build), every package carries public-surface guard tests, and the full browser matrix (Chromium/Firefox/WebKit) must pass before a release. The published packages are additionally exercised from a separate consumer project before a release is called done.


Design documents: Architecture · API design · Performance

Clone this wiki locally