node-zip: Legacy Zip/Unzip Utility

Common errors

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use `require()` in an ES Module context when `node-zip` is a CommonJS module.
  fix If your project is ES Module-based, you must use `import { createRequire } from 'module'; const require = createRequire(import.meta.url); const Zip = require('node-zip');`. However, migrating to a modern, ESM-compatible zip library is highly recommended.

• TypeError: Zip is not a constructor

  cause Calling `require('node-zip')` directly without the `new` keyword, or incorrectly trying to access named exports.
  fix The primary export of `node-zip` is a constructor function. It must be instantiated with `new`: `const Zip = require('node-zip'); const zipInstance = new Zip();`.

• Error: incorrect data size (decompression)

  cause This error typically occurs during decompression if the input ZIP data is corrupted or if the data was written to disk using an incorrect encoding (e.g., UTF-8 instead of binary).
  fix Ensure that when writing the ZIP buffer to a file, `fs.writeFileSync` uses the `'binary'` encoding: `fs.writeFileSync('output.zip', data, 'binary');`. Also verify the integrity of the input ZIP file.

• FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

  cause Processing very large ZIP files or archives with many entries without streaming, causing the Node.js process to exceed its allocated memory limit.
  fix Consider `node-zip` unsuitable for large files. Migrate to streaming-based zip libraries (e.g., `unzipper`, `zip-stream`) for efficient memory management when handling large archives.

Warnings

• breaking This package is explicitly abandoned and has not received updates since 2015. It lacks modern features, performance optimizations (like streaming for large files), and security patches, making it unsuitable for new projects and risky for existing ones.
  Fix: Migrate to actively maintained alternatives such as `jszip` (for browser and Node.js), `adm-zip` (Node.js, synchronous), or `zip-stream`/`archiver` (Node.js, streaming for large files).
• gotcha When writing generated ZIP data to a file using Node.js's `fs.writeFileSync`, it is critical to specify `'binary'` encoding. Failing to do so can corrupt the ZIP archive, rendering it unreadable.
  Fix: Ensure `fs.writeFileSync('file.zip', data, 'binary');` is used. Do not rely on default string encodings.
• breaking Due to its age and lack of maintenance, `node-zip` does not support ES Modules (ESM) and must be imported using CommonJS `require()`. Attempting to `import` it will result in errors.
  Fix: Always use `const Zip = require('node-zip');` to import the library. If your project is ESM-only, you may need a wrapper or to transition to a modern, ESM-compatible zip library.
• gotcha Older, non-streaming zip libraries like `node-zip` can lead to 'JavaScript heap out of memory' errors or block the Node.js event loop when processing large ZIP files, as they often load the entire archive into memory.
  Fix: For large files, use streaming-based libraries (e.g., `zip-stream`, `unzipper`) which process data in chunks to conserve memory and avoid blocking. If you must use `node-zip`, process smaller files only.
• breaking The library is unmaintained and will not receive security updates for known vulnerabilities (e.g., zip bombs, path traversal attacks). Using it in production could expose your application to security risks.
  Fix: Immediately migrate to a well-maintained and actively supported zip library that has a track record of addressing security concerns.

Install

• npm install node-zip npm
• yarn add node-zip yarn
• pnpm add node-zip pnpm

Imports

• Zip
  wrong:

  import Zip from 'node-zip'; // ESM is not supported
  import { Zip } from 'node-zip'; // Not a named export
  const zipInstance = require('node-zip'); // 'new' keyword is required

  correct:

  const Zip = require('node-zip');
  const zipInstance = new Zip();

  This package is CommonJS-only and the primary export is a constructor function. It does not support ES Modules (`import`).

Quickstart

This quickstart demonstrates how to create a ZIP archive with text and binary content, save it to disk, and then read/extract files from the created ZIP using `node-zip`.

const fs = require('fs');
const Zip = require('node-zip');

// --- Zipping a file ---
const zip = new Zip();
zip.file('my_test.txt', 'Hello, this is a test file content.');
zip.file('another_folder/image.jpg', 'fake image data here, imagine a buffer'); // Can add binary data

const zippedData = zip.generate({ base64: false, compression: 'DEFLATE' });

// IMPORTANT: When writing to a file, use 'binary' encoding.
fs.writeFileSync('output.zip', zippedData, 'binary');
console.log('Successfully created output.zip');

// --- Unzipping a file ---
// For demonstration, we'll read the file we just created
const zipBuffer = fs.readFileSync('output.zip', 'binary');

const unzip = new Zip(zipBuffer, { base64: false, checkCRC32: true });

console.log('\n--- Unzipped Content ---');
console.log('Content of my_test.txt:', unzip.files['my_test.txt'].asText());
// For binary files, you'd access .asBinary() or .asNodeBuffer()
console.log('File metadata for another_folder/image.jpg:', unzip.files['another_folder/image.jpg']);