TypeScript library / CLI

PicoWebPJS

A WebP encoder written in TypeScript for Node.js and browsers. Converts PNGs, baseline JPEGs, BMPs and raw pixels without native bindings or WebAssembly, while preserving transparency and embedded colour profiles.

DownloadVersion 1.0.0
PicoWebPJS
PicoWebPJS

About PicoWebPJS

After building PicoWebP in PHP, I ported the encoder to TypeScript. The same work can now run in Node.js and in a browser, without a native binary or a WebAssembly module to ship alongside it.

PicoWebPJS includes its own PNG, baseline JPEG and BMP readers, plus the encoder that writes the VP8 WebP bitstream. The published package has zero runtime dependencies. Give it image bytes or raw RGB pixels and it handles the conversion in JavaScript.

That makes it useful for browser tools that process images on the user's device, or Node.js applications where native image tooling would complicate deployment. There is a Web Worker example for keeping the page responsive, a CLI for file conversion, and both ESM and CommonJS builds.

The less visible details matter too. Transparency is compressed losslessly, embedded ICC colour profiles are carried through, and files that are already WebP are skipped based on their contents. For longer Node.js jobs, the encoder can save its state and resume in another process.

There are limits. Colour compression is lossy, progressive JPEGs need an additional decoder, and native encoders are generally faster. Encoding is synchronous, so browser applications should move substantial work into a worker.

PicoWebPJS is available on npm under the MIT licence. The Node.js API and CLI require Node 18 or newer.

Installation

npm install picowebpjs

Notes & updates

Release history

Version 1.0.0

First public release of PicoWebPJS, a TypeScript port of PicoWebP.

Added

  • Encode PNG, baseline JPEG, BMP, or raw RGB pixels as lossy WebP, with no runtime dependencies, native bindings, or WebAssembly.
  • Preserve transparency with lossless alpha compression and carry ICC colour profiles into the output.
  • Provide browser and Node.js APIs, ESM and CommonJS builds, and TypeScript declarations. The Node.js API and CLI support Node 18 and later.
  • Include a CLI with quality settings, raw-pixel input, alpha handling, ICC options, and JSON reports. Existing WebP files are skipped by default.
  • Support staged, resumable encoding in Node.js, with image planes stored on disk.
  • Include file-conversion, queue, and browser-worker examples, plus a benchmark.
  • Verify output against PHP fixtures and, when installed, the independent libwebp decoder.

Fixed before release

  • Enforce decompression limits before growing the output buffer.
  • Reject invalid dimensions, quality values, quantiser indices, and alpha filters.
  • Report malformed CLI values and missing ICC files cleanly. Restore shared decoder settings after programmatic CLI calls.
  • Preserve custom decoder geometry and ICC profiles when staging images. Close staging files on failure, handle partial writes, and report missing or truncated alpha and ICC files.
  • Correct CommonJS type declarations and exclude compiled tests from the npm package. Build the library automatically before packing.
  • Fix example and benchmark commands on a clean checkout, correct benchmark columns, and remove the command for an unavailable fixture generator.
  • Make the test suite work on Node 18 as well as Node 20.

External download

Download 1.0.0