TypeScript library / CLI

PicoWebPJS

Convert images to WebP in Node.js or the browser without native bindings or WebAssembly. A TypeScript encoder with zero runtime dependencies.

DownloadVersion 1.0.0
PicoWebPJS
PicoWebPJS

About PicoWebPJS

PicoWebPJS adds WebP conversion to Node.js and browser applications without installing native image libraries or shipping a WebAssembly module. Its encoder and bundled image readers run in JavaScript, with zero runtime package dependencies.

It is useful when image-processing dependencies complicate deployment, or when conversion needs to happen on the user’s device.

Where PicoWebPJS fits

  • Node.js applications with deployment constraints. Add WebP encoding without packaging platform-specific native bindings or a separate command-line encoder.
  • Browser upload and export tools. Convert images locally before uploading them, or let users create and download WebP files without sending their images to a conversion service.
  • Applications with browser and server processing. Use the same encoding core for a browser tool and its Node.js background jobs.

Supported images

PicoWebPJS reads PNG, baseline JPEG and BMP files, and accepts raw RGB pixels. It preserves transparency and embedded ICC colour profiles, and recognises existing WebP files from their contents so they can be skipped.

The package includes a command-line interface, ESM and CommonJS builds, and TypeScript declarations.

Browser and background processing

The repository includes a Web Worker example for moving image decoding and encoding off the browser’s main thread. This lets the page remain responsive while conversion runs.

For longer Node.js jobs, staged encoding lets your application save progress and resume in another process. Your application controls scheduling and state storage.

Performance and limits

Decoding and encoding are synchronous. Use a worker for substantial browser processing and set image-size limits appropriate to your application.

Native encoders are generally faster. PicoWebPJS is useful when avoiding native dependencies matters more than maximum conversion throughput. Resumable processing lets you divide a job across runs; it does not make the encoding itself faster.

Colour compression is lossy, while transparency is compressed losslessly. Progressive JPEG input needs an additional decoder.

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

For PHP applications on restricted hosting, see PicoWebP.

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