Skip to content

Contributing

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

Contributing

Dev setup

git clone https://github.com/dusmamud/dusrel-image.git
cd dusrel-image
pnpm install          # pnpm 10 workspaces + Turborepo
pnpm build            # builds all 24 packages (tsdown, ESM-only)
pnpm test             # vitest unit suites
pnpm typecheck
pnpm lint

Node 20+ works; the project is developed on Node 24.

Dependency changes: add them in package.json, run pnpm install, and make sure pnpm install --frozen-lockfile exits 0 before pushing — CI installs frozen.

Monorepo layout

packages/
  core/          @dusrel/image-core
  image/         @dusrel/image (flagship)
  codecs/        jpeg · webp · avif · png · oxipng · resize · quantize · qoi · jxl · heic
  features/      crop · transform · adjust · metadata · watermark · batch · gif · svg · placeholder
  frameworks/    react · vue · svelte
apps/
  docs-site/     VitePress documentation + the hosted playground assembler
  playground/    the live playground (import-map based)
native/          per-codec Docker builds + the Rust workspace
tests/browser/   Playwright specs (Chromium · Firefox · WebKit)
docs/            design docs and ADRs

Rules of the road

  • Every PR needs green CI. Branch protection requires the Lint, typecheck, test, build checks plus CodeQL, with the branch up to date — no force-pushes, no direct pushes to main.
  • Versioning is Changesets, lockstep. All 24 packages share one version. Any change that should ship needs a changeset (pnpm changeset) — see Release Process.
  • Public surface is guarded. Packages carry public-surface tests; if you add or rename an export, update them. publint and attw run in the pipeline — keep them quiet.
  • Size budgets are real. Core ≤ 10 KB, flagship ≤ 15 KB (brotlied). Codec WASM never goes in the core.
  • TypeScript strict, ESM-only. exactOptionalPropertyTypes and noUncheckedIndexedAccess are on; sources import with .js specifiers.
  • Formatting is oxfmt, lint is oxlint — pnpm format checks; generated codec glue under packages/**/codec/ is exempt and must never be reformatted.

Working on a codec

Each codec builds in its own pinned Docker image under native/ (emsdk 3.1.66 for the C/C++ engines; rust:1.99.1 + wasm-bindgen CLI 0.2.130 for the Rust crates). The non-negotiable rule:

A green WASM build is not proof. Every codec build ends with a functional smoke gate — a real encode and decode inside the build — and the artifacts are re-verified in Node before they are committed to packages/codecs/<name>/codec/.

New packages follow the same shape as existing ones: src/{types,module,encode,decode,index}.ts, a codec/ folder for the artifacts, setCodecAssets support, a browser spec under tests/browser/, and a README with a dated status line.

Licence hygiene

The project is MIT and intends to stay that way. Do not introduce GPL-licensed engines (that is why quantisation uses quantizr, not libimagequant, and GIF uses the Rust gif crate, not gifsicle). The single exception is @dusrel/image-heic, whose LGPL-3.0 engine ships unmodified and fenced inside that package only (ADR-0008) — do not copy its engine code elsewhere.

Where to ask

Open an issue on the repository, or start from the docs site.

Clone this wiki locally