{"id":10872,"library":"fast-png","title":"Fast PNG Encoder/Decoder","description":"fast-png is a performant JavaScript library for encoding and decoding PNG image data, built entirely in JavaScript without native dependencies. The current stable version is 8.0.0, released in December 2025. This package focuses on speed, demonstrated by its recent switch to the `fflate` library for compression in v8.0.0. Major versions are released periodically (roughly annually), often introducing significant breaking changes like the migration to ESM in v7.0.0. It differentiates itself by offering a pure JavaScript implementation suitable for both Node.js and browser environments, while providing granular control over encoding options and supporting various PNG features like `tEXt` chunks, `tRNS` fields, and `ICC` profiles.","status":"active","version":"8.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/image-js/fast-png","tags":["javascript","png","image","image-js","encoder","decoder"],"install":[{"cmd":"npm install fast-png","lang":"bash","label":"npm"},{"cmd":"yarn add fast-png","lang":"bash","label":"yarn"},{"cmd":"pnpm add fast-png","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Package migrated to ESM in v7.0.0. CommonJS `require` will result in an error.","wrong":"const { decode } = require('fast-png');","symbol":"decode","correct":"import { decode } from 'fast-png';"},{"note":"Package migrated to ESM in v7.0.0. CommonJS `require` will result in an error.","wrong":"const { encode } = require('fast-png');","symbol":"encode","correct":"import { encode } from 'fast-png';"},{"note":"Added in v6.3.0. Package migrated to ESM in v7.0.0.","wrong":"const { hasPngSignature } = require('fast-png');","symbol":"hasPngSignature","correct":"import { hasPngSignature } from 'fast-png';"}],"quickstart":{"code":"import { decode, encode } from 'fast-png';\n\nasync function runPngExample() {\n  // 1. Define a simple 2x2 red image in RGBA format\n  const width = 2;\n  const height = 2;\n  const data = new Uint8Array([\n    255, 0, 0, 255, // Red pixel 1\n    255, 0, 0, 255, // Red pixel 2\n    255, 0, 0, 255, // Red pixel 3\n    255, 0, 0, 255  // Red pixel 4\n  ]);\n\n  // 2. Encode the image into a PNG buffer\n  const encodedPngBuffer = encode({\n    width,\n    height,\n    data,\n    channels: 4, // RGBA\n    depth: 8,    // 8 bits per channel\n    text: { title: 'Test Image', author: 'AI' } // Optional tEXt chunks\n  });\n\n  console.log(`Encoded PNG buffer size: ${encodedPngBuffer.length} bytes`);\n\n  // 3. Decode the PNG buffer back into an image object\n  // For Node.js, the buffer output by encode is compatible with decode.\n  // For browser, you might get an ArrayBuffer and need to wrap in Uint8Array.\n  const decodedImage = decode(encodedPngBuffer, { checkCrc: true });\n\n  console.log(`\\n--- Decoded Image Information ---`);\n  console.log(`Width: ${decodedImage.width}`);\n  console.log(`Height: ${decodedImage.height}`);\n  console.log(`Channels: ${decodedImage.channels}`);\n  console.log(`Depth: ${decodedImage.depth}`);\n  console.log(`Data length: ${decodedImage.data.length}`);\n  console.log(`Text chunks:`, decodedImage.text);\n\n  // 4. Verify a pixel value from the decoded data\n  const firstPixelOffset = 0; // RGBA\n  const [r, g, b, a] = decodedImage.data.slice(firstPixelOffset, firstPixelOffset + 4);\n  console.log(`First pixel (R,G,B,A): (${r}, ${g}, ${b}, ${a})`);\n\n  if (r === 255 && g === 0 && b === 0 && a === 255) {\n    console.log('Successfully decoded the red pixel as expected!');\n  } else {\n    console.error('Decoded pixel color mismatch!');\n  }\n}\n\nrunPngExample().catch(console.error);","lang":"typescript","description":"This quickstart encodes a simple 2x2 red image with metadata and then decodes it, verifying the pixel data and metadata."},"warnings":[{"fix":"Review the `encode` function documentation for updated `zlib` related options. Old options will likely cause errors or be ignored.","message":"The options for zlib encoding have been changed due to a switch from `pako` to `fflate` for performance improvements.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Update all imports to use ESM `import` statements. Ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json` for Node.js).","message":"The package migrated to ECMAScript Modules (ESM) and no longer supports CommonJS `require()` syntax.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Upgrade your Node.js runtime to a supported version (e.g., Node.js 16 or higher).","message":"Support for Node.js versions 10 and 15 was removed. The library now targets more modern Node.js environments.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Review your code for any properties or methods that previously used uppercase acronyms (e.g., `CRCHash`) and update them to their camelCase equivalents (e.g., `crcHash`).","message":"Acronyms in certain properties and methods were changed to use camelCase for consistency.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"For robust error checking, always pass `{ checkCrc: true }` in the options object to the `decode` function.","message":"The `decode` function's `checkCrc` option is `false` by default, meaning the library will not verify the integrity of chunks. Corrupt PNG files may be processed without error.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure all text chunk keys are under 80 characters and both keys and values strictly adhere to the Latin-1 character set. Consider `iTXt` for full Unicode support if supported by the library.","message":"When using the `text` option in the `encode` function for `tEXt` chunks, both keys and values must only contain characters from the Latin-1 charset (maximum code point 255), and keys must be less than 80 characters long.","severity":"gotcha","affected_versions":">=6.3.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `const { decode, encode } = require('fast-png');` to `import { decode, encode } from 'fast-png';`. Ensure your `package.json` has `\"type\": \"module\"` if running in Node.js, or use a bundler that handles ESM.","cause":"Attempting to use `require()` to import `fast-png` in a CommonJS context after v7.0.0.","error":"ERR_REQUIRE_ESM"},{"fix":"Ensure the object passed to `encode` has at least `width`, `height`, `data`, `channels`, and `depth` properties, as specified in the API documentation.","cause":"The `encode` function received an `image` object that is missing required properties like `width`, `height`, or `data`.","error":"TypeError: Cannot read properties of undefined (reading 'width')"},{"fix":"Remove or update any `zlib` related options passed to `encode` as their structure or names may have changed with the switch to `fflate` in v8.0.0. Refer to the latest API documentation.","cause":"Using old or incompatible `zlib` encoding options with the `encode` function after the v8.0.0 breaking change.","error":"Error: Invalid zlib options provided"}],"ecosystem":"npm"}