{"id":11569,"library":"png-js","title":"PNG Decoder for Node.js and Browser","description":"png-js is a JavaScript-based PNG decoder designed for both Node.js and browser environments. The package's latest version, 2.0.0, was released over a decade ago (tagged in 2013, with the last npm publish for version 1.0.0 being over six years ago), indicating it is an abandoned project with no active maintenance or release cadence. While it provides basic functionality for decoding PNG files into raw pixel data, its age means it does not support modern JavaScript module systems like ESM, lacks official TypeScript definitions, and likely misses performance optimizations or features found in contemporary image processing libraries. Developers requiring a robust, actively maintained, or high-performance PNG solution should consider modern alternatives such as 'pngjs' (note the lowercase 'js'), 'sharp', or 'jimp'. Its key differentiator was being a pure JavaScript decoder for both environments at a time when fewer options existed.","status":"abandoned","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/devongovett/png.js","tags":["javascript"],"install":[{"cmd":"npm install png-js","lang":"bash","label":"npm"},{"cmd":"yarn add png-js","lang":"bash","label":"yarn"},{"cmd":"pnpm add png-js","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"png-js is a CommonJS module and does not support ESM import syntax directly. For browser usage, PNG is exposed globally if `png.js` is included via a <script> tag.","wrong":"import PNG from 'png-js';\nimport { PNG } from 'png-js';","symbol":"PNG","correct":"const PNG = require('png-js');"},{"note":"The primary decoding method is `PNG.decode` which uses a callback. No named export 'decode' exists. The method is asynchronous and expects a callback for results.","wrong":"import { decode } from 'png-js';\nPNG.decodeAsync(...);","symbol":"decode","correct":"const PNG = require('png-js');\nPNG.decode('some.png', callback);"},{"note":"To decode from an existing buffer, instantiate PNG directly. Be careful not to confuse this 'png-js' with the similarly named but different 'pngjs' package.","wrong":"new pngjs.PNG(buffer);","symbol":"PNG instance","correct":"const PNG = require('png-js');\nconst pngInstance = new PNG(buffer);"}],"quickstart":{"code":"import { readFileSync } from 'fs';\nimport { join } from 'path';\n\n// Simulate loading png-js in a CommonJS-like environment\n// In a real Node.js CJS project, this would be: const PNG = require('png-js');\n// For this example, we'll manually 'import' it as if it were a default export from a CJS wrapper.\n// In a modern ESM project, you would need a CJS interop or a bundler.\n\n// To make this runnable, we'll assume a simplified shim for `require('png-js')`\n// In a real project, ensure `png-js` is properly required.\n// For demonstration purposes, we'll mock the module structure based on README:\nconst createPngJsMock = () => {\n  return {\n    decode: (filePath, callback) => {\n      console.log(`Decoding ${filePath} using png-js...`);\n      try {\n        // In a real scenario, this would read the file and parse PNG data\n        // For this mock, we'll just return dummy pixel data\n        // The actual `png-js` would read the file system.\n        const dummyPixels = Buffer.from([255, 0, 0, 255, 0, 255, 0, 255, 0, 0, 255, 255]); // R,G,B,A for 3 pixels\n        process.nextTick(() => callback(dummyPixels));\n      } catch (error) {\n        console.error('Error in PNG.decode mock:', error);\n        process.nextTick(() => callback(null, error));\n      }\n    },\n    load: (filePath, canvas) => {\n        console.log(`Loading ${filePath} into canvas (browser-only feature, mocked here)...`);\n        // Browser-side PNG.load implementation would handle canvas rendering.\n    },\n    // Add a constructor for buffer-based decoding as described in the README\n    PNG: class PngBufferDecoder {\n      constructor(buffer) {\n        console.log('New PNG instance created from buffer.');\n        this.buffer = buffer;\n      }\n      decode(callback) {\n        console.log('Decoding PNG buffer...');\n        // Simulate decoding buffer data\n        const dummyPixels = Buffer.from([128, 128, 0, 255, 0, 128, 128, 255]); // 2 pixels\n        process.nextTick(() => callback(dummyPixels));\n      }\n    }\n  };\n};\n\nconst PNG = createPngJsMock(); // Simulate require('png-js');\n\n// Example 1: Decode a file (mocked path)\nconst imagePath = join(process.cwd(), 'test.png'); // Placeholder, file won't actually exist\nPNG.decode(imagePath, function(pixels) {\n    if (!pixels) {\n        console.error('Failed to decode image.');\n        return;\n    }\n    console.log(`Decoded pixels (from file): ${pixels.length} bytes.`);\n    // pixels is a 1d array (in rgba order) of decoded pixel data\n    // console.log(pixels);\n});\n\n// Example 2: Decode from an existing buffer\nconst dummyPngBuffer = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYGD4DwABSgCB3yA4JgAAAABJRU5ErkJggg==', 'base64');\nconst pngInstance = new PNG.PNG(dummyPngBuffer);\npngInstance.decode(function(pixels) {\n    if (!pixels) {\n        console.error('Failed to decode buffer.');\n        return;\n    }\n    console.log(`Decoded pixels (from buffer): ${pixels.length} bytes.`);\n    // console.log(pixels);\n});","lang":"javascript","description":"This quickstart demonstrates how to use `png-js` in a Node.js-like environment to decode PNG files either by path or from a buffer, showing its callback-based asynchronous API. It mocks the actual file operations for runnable demonstration, as the library is old and CJS-only."},"warnings":[{"fix":"Migrate to actively maintained alternatives like `pngjs` (note the lowercase 'js'), `sharp`, or `jimp` for better security, performance, and modern feature support.","message":"The `png-js` package is effectively abandoned, with its last significant update (version 2.0.0 tag) dating back to 2013, and the latest npm publish (version 1.0.0) over six years ago. This means it is unlikely to receive security patches, bug fixes, or feature updates.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"For Node.js ESM projects, you might need to use `import { createRequire } from 'module'; const require = createRequire(import.meta.url); const PNG = require('png-js');` or use a build step with a bundler like Webpack or Rollup that handles CJS modules. Consider using a modern ESM-compatible library instead.","message":"This library uses CommonJS `require()` syntax exclusively for Node.js. It does not support ES Modules (`import/export`) natively. Using it in a pure ESM project will require a CommonJS interoperability layer or a bundler.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Manually create a declaration file (`png-js.d.ts`) with `declare module 'png-js' { ... }` or switch to a library that ships with its own types or has community-maintained `@types` packages.","message":"The package does not provide TypeScript type definitions, making it harder to use in TypeScript projects without manually declaring types or relying on `@ts-ignore`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For performance-critical applications, especially in Node.js, evaluate libraries like `sharp` which utilize native code for speed. For browser, consider native browser APIs or newer JavaScript libraries optimized for performance (e.g., `UPNG.js`).","message":"Performance may be significantly lower compared to native C++ based image processing libraries (like `sharp`) or more modern, optimized pure JavaScript decoders. Being an older pure JavaScript implementation, it might not leverage recent V8 engine optimizations or WebAssembly.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Use CommonJS `require()` syntax for Node.js: `const PNG = require('png-js');`. If in an ESM file, you may need `import { createRequire } from 'module'; const require = createRequire(import.meta.url); const PNG = require('png-js');`.","cause":"Attempting to import `png-js` using ESM default import syntax in a TypeScript or ESM Node.js project.","error":"TypeError: (0 , png_js_1.default) is not a function"},{"fix":"For browsers, ensure `<script src=\"png.js\"></script>` and `<script src=\"zlib.js\"></script>` are present before your script. For Node.js, ensure `const PNG = require('png-js');` is at the top of your file.","cause":"Trying to use `PNG.load()` or `new PNG()` in a browser environment without including the `png.js` script tag, or in a Node.js ESM context without proper CommonJS interop.","error":"ReferenceError: PNG is not defined"},{"fix":"Verify the integrity of the PNG file. If the file is valid and still causes issues, this library might not support that specific PNG variant. Consider using a more robust and actively maintained PNG decoding library like `pngjs` (lowercase) or `sharp`.","cause":"The PNG file is corrupted, malformed, or uses features (e.g., specific interlace methods, bit depths) that this older library might not fully support or correctly parse.","error":"Error: Invalid PNG"}],"ecosystem":"npm"}