upng-js

library2.1.0jsnpmunverified

UPNG.js is a small, fast, and advanced PNG/APNG encoder and decoder, used as the core PNG engine in the Photopea image editor (current stable: 2.1.0). It supports encoding single PNGs and APNG animations with optional lossy color quantization (k-means) for file size reduction, decoding all color types, bit depths (1–16), interlaced images, and additional PNG chunks. Key differentiators include handling PNGs that other libraries cannot open, lossy compression akin to TinyPNG, and a lightweight footprint.

storage testing

npm install upng-js

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · UPNG-JS

upng-js

storagejavascriptv2.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

UPNG

✓ import UPNG from 'upng-js'

✗ const UPNG = require('upng-js')

The package does not export a default CommonJS object; use ESM import for proper module resolution.

UPNG.encode

✓ import UPNG from 'upng-js'; UPNG.encode(imgs, w, h, cnum, dels)

✗ const { encode } = require('upng-js')

encode is not a named export; access it as UPNG.encode.

UPNG.decode

✓ import UPNG from 'upng-js'; UPNG.decode(buffer)

✗ const { decode } = require('upng-js')

decode is not a named export; access it as UPNG.decode.

UPNG.toRGBA8

✓ import UPNG from 'upng-js'; UPNG.toRGBA8(img)

Converts decoded image to RGBA frames. Always call after UPNG.decode().

Demonstrates decoding a PNG file to get metadata and RGBA data, and encoding a 2x2 red image as a PNG. Includes reading/writing via Node.js fs.

import UPNG from 'upng-js'; import fs from 'fs'; // Read a PNG file as ArrayBuffer const data = fs.readFileSync('image.png').buffer; const img = UPNG.decode(data); console.log(`Width: ${img.width}, Height: ${img.height}`); // Convert to RGBA (first frame) const rgba = new Uint8Array(UPNG.toRGBA8(img)[0]); // Encode a simple 2x2 red image const width = 2, height = 2; const pixelData = new Uint8Array(width * height * 4); pixelData[0] = 255; pixelData[1] = 0; pixelData[2] = 0; pixelData[3] = 255; // top-left red pixelData[4] = 255; pixelData[5] = 0; pixelData[6] = 0; pixelData[7] = 255; // top-right red pixelData[8] = 255; pixelData[9] = 0; pixelData[10] = 0; pixelData[11] = 255; // bottom-left red pixelData[12] = 255; pixelData[13] = 0; pixelData[14] = 0; pixelData[15] = 255; // bottom-right red const pngBuffer = UPNG.encode([pixelData.buffer], width, height, 0); fs.writeFileSync('output.png', Buffer.from(pngBuffer));

Debug

Known issues

breakingUPNG.js v2.1.0 requires the pako library as a dependency; earlier versions bundled pako internally. Ensure pako is installed or update your import.

fix

Run 'npm install pako' or 'npm install upng-js' (will auto-install pako).

affects: >=2.0.0

gotchaThe image data passed to UPNG.encode must be ArrayBuffer objects, not Uint8Array or Buffer. Failure to provide ArrayBuffer will cause silent errors or corrupt output.

fix

Use .buffer property on typed arrays: e.g., UPNG.encode([uint8array.buffer], w, h, cnum).

affects: *

gotchaUPNG.toRGBA8 returns an array of frames; for single PNGs, always access the first element with [0] to get the RGBA data. Forgetting the index results in an array, not a buffer.

fix

Use const rgba = UPNG.toRGBA8(img)[0]; to obtain the first frame's data.

affects: *

gotchaLossy compression with cnum > 0 may produce banding or quality loss. Setting cnum too low (e.g., 2) on a complex image can result in poor quality.

fix

Use cnum=0 for lossless, or cnum=256 for typical lossy; test with your own images.

affects: *

deprecatedThe npm package 'upng-js' has not received updates since 2018; it is considered stable but may not support modern PNG features or security patches.

fix

Consider forking or using alternative libraries like sharp or lwip for active development.

affects: *

Errors

Common errors & fixes

TypeError: UPNG.encode is not a function

Using a named import like 'import { encode } from 'upng-js''. UPNG.encode is a method on the default export.

fix

Use 'import UPNG from 'upng-js'' then call UPNG.encode(...).

Error: Cannot find module 'pako'

UPNG.js v2+ requires pako as an external dependency; if not installed, the module cannot be resolved.

fix

Run 'npm install pako' or reinstall upng-js to ensure pako is present.

Invalid PNG signature or corrupted image data

Passing a Buffer object directly to UPNG.decode instead of an ArrayBuffer.

fix

Convert Buffer to ArrayBuffer: e.g., UPNG.decode(data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength)).

UPNG.toRGBA8(img) returns an array of arrays instead of array of ArrayBuffers

The return is effectively an array of ArrayBuffers; treating it as a single buffer causes confusion.

fix

Access the first frame with [0]: const frame = UPNG.toRGBA8(img)[0];

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

pakorequiredRequired for Inflate and Deflate (zlib) operations in PNG CRC and compression.

Agent activity

38 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/photopea/UPNG.js ↗

packageupng-js ↗

homepagehttps://github.com/photopea/UPNG.js ↗