ImageScript: Pure TypeScript image processing that runs everywhere

Documentation Playground Discussions Discord

npm JSR Tests MIT license

--- **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 (such as Cloudflare Workers), 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. ```sh npm install imagescript # Node.js, Bun and bundlers deno add jsr:@matmen/imagescript # Deno ``` Upgrading from 3.x? Read [Migrating to 4.0](https://github.com/imagescript/ImageScript/blob/master/guides/Migrating%20to%204.0.md) first. --- ### Example ```js 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()); ``` [![Example](https://github.com/imagescript/ImageScript/raw/master/tests/targets/readme.png)](https://github.com/imagescript/ImageScript/blob/master/tests/readme.js) The same code runs everywhere, only reading and writing the bytes differs. `Image.decode()` takes any `ArrayBuffer` or typed array (`fetch(url).then(r => r.arrayBuffer())` in a browser or on an edge runtime, `Deno.readFile()`, `Bun.file().arrayBuffer()`), and the encoders return a `Uint8Array`. In a browser without a bundler, import it from jsDelivr: ```js import { Image } from 'https://cdn.jsdelivr.net/npm/imagescript@4/+esm'; ``` ### Threads and bundlers 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 import 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. --- ### 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](https://imagescript.dev/classes/GainMap.html) (brighter highlights on HDR displays; JPEG, AVIF, JPEG XL) | ✓ | ✓ | [Animations](https://imagescript.dev/classes/Animation.html) can be decoded from GIF, APNG, WebP and JPEG XL, and encoded as GIF, APNG or WebP, all at once or [frame by frame](https://imagescript.dev/classes/Animation.html#webpencoder). 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. - [Text rendering](https://imagescript.dev/classes/Image.html#rendertext) with TrueType, OpenType and WOFF fonts (not WOFF2; some OpenType outline formats are unsupported): right-to-left text and scripts where letters connect or combine, plus color emoji and variable TrueType fonts - [SVG rendering](https://imagescript.dev/classes/Image.html#rendersvg), including text (with fonts you pass or fonts embedded in the SVG); no automatic fetching of external images or fonts - [Resizing](https://imagescript.dev/classes/Image.html#resize), [cropping](https://imagescript.dev/classes/Image.html#crop), [rotating](https://imagescript.dev/classes/Image.html#rotate), [trimming](https://imagescript.dev/classes/Image.html#trim), [rounded corners](https://imagescript.dev/classes/Image.html#roundcorners), ... - [Compositing](https://imagescript.dev/classes/Image.html#composite) with opacity and blend modes - Filters and color adjustments: [blur](https://imagescript.dev/classes/Image.html#blur), [sharpen](https://imagescript.dev/classes/Image.html#sharpen), [brightness](https://imagescript.dev/classes/Image.html#brightness), [hueShift](https://imagescript.dev/classes/Image.html#hueshift), ... The [documentation](https://imagescript.dev/) covers the full API. When upgrading from an older major version, see the [changelog](https://github.com/imagescript/ImageScript/blob/master/CHANGELOG.md). [bench/](bench/README.md) compares ImageScript's speed and file sizes with Jimp, sharp and other libraries. --- ### Credits ImageScript builds on [fflate](https://github.com/101arrowz/fflate), libjpeg, [pdf.js](https://github.com/mozilla/pdf.js), [font-rs](https://github.com/raphlinus/font-rs), [libwebp](https://chromium.googlesource.com/webm/libwebp), [HarfBuzz](https://github.com/harfbuzz/harfbuzz), [dav1d](https://code.videolan.org/videolan/dav1d), [libavif](https://github.com/AOMediaCodec/libavif), libaom, [jxl-oxide](https://github.com/tirr-c/jxl-oxide) and [libjxl](https://github.com/libjxl/libjxl). The TrueType hinting follows [FreeType](https://freetype.org): portions of this software are copyright © 2026 The FreeType Project (www.freetype.org). All rights reserved. See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for the licenses.