Skip to content

Repository files navigation

ImageScript: Pure TypeScript image processing that runs everywhere

Documentation Playground

Github Discord Server


ImageScript decodes, edits and encodes images in pure TypeScript: no WebAssembly, no native binaries, and no runtime dependencies. It runs in Node.js 22.13+, Deno, Bun, browsers and edge runtimes (Cloudflare Workers, Vercel's Edge Runtime, Deno Deploy), works with import and, on supported Node.js versions, require(), and ships with type definitions (TypeScript 5.7 or newer; CommonJS projects need module: nodenext and 5.8 or newer to import it (module: node16 can't). With older versions and skipLibCheck, the encoders' return types become any). Large AVIF and JPEG XL operations, and lossless WebP encoding, can use multiple CPU cores when the runtime supports it.

npm install imagescript              # Node.js, Bun and bundlers
deno add jsr:@matmen/imagescript     # Deno

Upgrading from 3.x? Read Migrating to 4.0 first.

Without a bundler, import it from jsDelivr in the browser:

<script type="module">
  import { Image } from 'https://cdn.jsdelivr.net/npm/imagescript@4/+esm';

  const image = await Image.decode(await fetch('photo.jpg').then(r => r.arrayBuffer()));
  image.resize({ width: 256 });
  const url = URL.createObjectURL(new Blob([await image.encodePNG()], { type: 'image/png' }));
  document.body.append(Object.assign(document.createElement('img'), { src: url }));
</script>

The codecs that can use worker threads (large AVIF and JPEG XL images, lossless WebP; the threads option) do so in Node.js, Deno and Bun, and in browsers on cross-origin isolated pages. Where workers can't start, the work runs on the calling thread: the output is the same, only slower, and nothing warns about it. Browsers refuse workers from another origin, so the jsDelivr example above runs single-threaded; serve the package from your own origin (on a cross-origin isolated page) to get threads.

Bundlers that write one file (esbuild, Rollup, bun build) don't copy the worker's module: serve dist/util/worker.js next to the bundle, or the same single-threaded fallback is used. webpack and Vite emit it.


Example

import { Image } from 'imagescript';
import { readFile, writeFile } from 'node:fs/promises';

const image = await Image.decode(await readFile('input.jpg'));
image.resize({ width: 256 }).roundCorners({ radius: 16 });
await writeFile('output.png', await image.encodePNG());

Try ImageScript in the Playground

Example


Features

Format Decode Encode
PNG ✓ ✓
JPEG ✓ ✓
WebP ✓ ✓ (lossless and lossy)
AVIF ✓ ✓ (lossless and lossy)
JPEG XL ✓ ✓ (lossless and lossy)
GIF, APNG (animations) ✓ ✓
BMP, QOI, TGA, Netpbm ✓ ✓
TIFF, ICO/CUR, Radiance HDR ✓
HDR gain maps (brighter highlights on HDR displays; JPEG, AVIF, JPEG XL) ✓ ✓

Animations can be decoded from GIF, APNG, WebP and JPEG XL, and encoded as GIF, APNG or WebP, all at once or frame by frame. Lossless encoding keeps every pixel exactly; lossy encoding makes smaller files by approximating some image detail. quality: 100 is lossless for WebP, AVIF and JPEG XL (JPEG has no lossless mode). Without a quality, WebP and JPEG XL are lossless and AVIF is lossy.

Not supported (decoding them throws an error): CCITT-compressed TIFF and arithmetic-coded JPEG. Lossless JPEG XL is fast but not small: for small lossless files, PNG or WebP are the better choice.

Embedded color profiles are converted to sRGB, the standard color format for most screens, where supported. CMYK and lookup-table profiles are left unchanged.

Supported image operations preserve gain maps; editing pixels directly with image.bitmap or setPixelAt() does not.

The documentation covers the full API. When upgrading from an older major version, see the changelog. bench/ compares ImageScript's speed and file sizes with Jimp, sharp and other libraries.


Credits

ImageScript builds on fflate, libjpeg, pdf.js, font-rs, libwebp, HarfBuzz, dav1d, libavif, libaom, jxl-oxide and libjxl. The TrueType hinting follows FreeType: portions of this software are copyright © 2026 The FreeType Project (www.freetype.org). All rights reserved. See THIRD_PARTY_NOTICES.md for the licenses.


Questions? Join the Discord server.