PNGQuant Stream Wrapper

Common errors

• spawn pngquant ENOENT

  cause 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

  cause 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).

Warnings

• gotcha The `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).
• gotcha Incorrectly 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.
• gotcha Stream 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.

Install

• npm install pngquant npm
• yarn add pngquant yarn
• pnpm add pngquant pnpm

Imports

• PngQuant
  wrong:

  import { PngQuant } from 'pngquant';

  correct:

  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
  wrong:

  import { PngQuantOptions } from 'pngquant';

  correct:

  import type { PngQuantOptions } from 'pngquant';

  Import the TypeScript type definition for configuring the PngQuant constructor options. It's a type-only import.

Quickstart

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();