Registry / serialization / pngquant

pngquant

JSON →
library3.0.3jsnpmunverified

The `pngquant` package provides a Node.js readable/writable stream wrapper for the `pngquant` command-line utility. It allows developers to optimize PNG images by reducing their color palette directly within a Node.js stream pipeline, making it suitable for processing images from HTTP requests, file uploads, or other stream sources without requiring temporary files. Currently at version 4.2.0, its release cadence is not explicitly stated in the provided information, but it appears actively maintained given recent version bumps and project activity. Key differentiators include its efficient stream-based API, direct integration with the powerful `pngquant` CLI for high-quality optimization, and robust TypeScript type definitions for enhanced developer experience. This design simplifies image optimization workflows in server-side applications and microservices.

npm install pngquant
INSTALL
IMPORT
SIG · PNGQUANT
P
pngquant
serializationjavascriptv3.0.3
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

PngQuant
import PngQuant from 'pngquant';
import { PngQuant } from 'pngquant';
The primary class is a default export, representing the stream transformer.
PngQuant (CommonJS)
const PngQuant = require('pngquant');
CommonJS import for environments that do not support ES modules natively.
PngQuantOptions
import type { PngQuantOptions } from 'pngquant';
import { PngQuantOptions } from 'pngquant';
Import the TypeScript type definition for configuring the PngQuant constructor options. It's a type-only import.

Demonstrates how to optimize a PNG file from a read stream to a write stream using custom `pngquant` command-line options within a Node.js pipeline.

import PngQuant from 'pngquant'; import { createReadStream, createWriteStream, promises as fsPromises } from 'fs'; import { pipeline } from 'stream/promises'; import path from 'path'; // Ensure a dummy input.png exists for this example to run. // In a real application, 'input.png' would be provided by user upload or file system. const inputFilePath = path.resolve(__dirname, 'input.png'); const outputFilePath = path.resolve(__dirname, 'output.png'); async function createDummyPng() { const dummyPngContent = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=', 'base64'); await fsPromises.writeFile(inputFilePath, dummyPngContent); console.log(`Created dummy PNG at ${inputFilePath}`); } async function optimizeImage() { await createDummyPng(); // Create a dummy PNG for the example try { // Initialize PngQuant with specific command-line arguments for the pngquant binary. // Here: reduce to 192 colors, target quality 60-80, disable dithering, read from stdin ('-'). const myPngQuanter = new PngQuant([192, '--quality', '60-80', '--nofs', '-']); console.log(`Optimizing ${inputFilePath} to ${outputFilePath}...`); await pipeline( createReadStream(inputFilePath), // Source stream: reads the input PNG myPngQuanter, // Transform stream: optimizes the PNG createWriteStream(outputFilePath) // Destination stream: writes the optimized PNG ); console.log(`Optimization complete! Optimized PNG saved to ${outputFilePath}`); } catch (error) { console.error('Image optimization failed:', error); } finally { // Clean up the dummy file await fsPromises.unlink(inputFilePath).catch(() => {}); } } optimizeImage();
Debug
Known issues
gotchaThe `pngquant` binary is a required runtime dependency and must be installed separately and available in the system's PATH. This package does not bundle the native executable.
fix
Install the `pngquant` command-line utility via your system's package manager (e.g., `brew install pngquant` on macOS, `sudo apt install pngquant` on Debian/Ubuntu, or download from the official `pngquant` website).
affects: >=1.0.0
gotchaIncorrectly passing options to the `PngQuant` constructor can lead to unexpected optimization results or errors from the underlying `pngquant` binary. The options array is passed directly as command-line arguments.
fix
Refer to the official `pngquant` command-line documentation for valid arguments and their syntax (e.g., run `pngquant --help` in your terminal). Test options thoroughly to ensure desired behavior.
affects: >=1.0.0
gotchaStream errors from either the input, output, or the `PngQuant` transform stream itself might not always be propagated or handled gracefully if not explicitly listened for. The `pipeline` utility from `stream/promises` is recommended for robust error handling in stream chains.
fix
Use `stream/promises.pipeline` for robust error handling and proper cleanup of streams in a chain. Alternatively, attach `error` event listeners to all individual streams in the pipeline (input, `PngQuant`, output) and handle errors appropriately.
affects: >=1.0.0
Errors
Common errors & fixes
spawn pngquant ENOENT
The `pngquant` executable is not found in the system's PATH environment variable.
fix
Ensure the `pngquant` command-line utility is installed and its location is included in your system's PATH. Verify installation by running `pngquant --version` in your terminal.
Error: PngQuant exited with code 98
The underlying `pngquant` binary encountered an error during image processing, often due to invalid input (e.g., corrupted PNG) or incompatible command-line options.
fix
Verify that the input stream provides a valid PNG image. Check the options array passed to the `PngQuant` constructor for correctness and compatibility with the `pngquant` CLI version and the input image (e.g., valid quality ranges, color counts).
Upgrade
Version history
3.0.3latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
2 hits · last 30 days
node
2
Resources
pngquant — npm install pngquant · libregistry