JSZip

Common errors

• Corrupted zip or bug: unexpected signature

  cause This error often occurs when binary zip content is incorrectly handled, such as an AJAX request decoding binary data as a text string, leading to data corruption.
  fix When fetching zip files via AJAX/XHR, ensure the response type is set to `arraybuffer` or `blob` to retrieve binary data correctly. For example: `xhr.responseType = 'arraybuffer';`.

• My browser crashes / becomes unresponsive / never finish the execution.

  cause Attempting to process large amounts of data using JSZip's older synchronous APIs (pre-v3) can block the main thread, causing the browser to freeze.
  fix Always use the asynchronous methods like `generateAsync()` and `loadAsync()`. These methods return Promises, allowing operations to run in the background without blocking the UI.

• Module 'jszip' has no default export.

  cause When using TypeScript with `import JSZip from 'jszip'` for a library that primarily uses CommonJS `module.exports = JSZip;`, this error indicates that TypeScript's module resolution is strict about default exports.
  fix Enable `allowSyntheticDefaultImports: true` in your `tsconfig.json`. Alternatively, use `import * as JSZip from 'jszip';` or `import JSZip = require('jszip');` if you prefer explicit CommonJS import syntax in TypeScript.

• Encrypted zip: unsupported encrypt method

  cause Trying to decompress a password-protected zip file that uses an unsupported encryption method, such as PKZIP 2.0 (often generated by `zip -e` on macOS), which JSZip does not support.
  fix JSZip does not support PKZIP 2.0 encryption due to security concerns. If you need to handle encrypted zips, they must use AES encryption if JSZip offers any support for it, or use a different library. Avoid `zip -e` for JSZip-compatible archives.

Warnings

• breaking JSZip v3 introduced significant breaking changes, shifting from synchronous to exclusively asynchronous APIs for file operations and generation. Methods like `generate()` were replaced by `generateAsync()`, synchronous content getters (e.g., `asText()`) by `async()`, and `load()` by `loadAsync()`. The `type` option in `generateAsync()` became mandatory, and `createFolders` option now defaults to `true`.
  Fix: Migrate all file content access and zip generation/loading calls to their asynchronous `*Async()` counterparts. Ensure all operations are `await`ed or chained with `.then()` for Promise-based execution. Review the upgrade guide for a full list of changes.
• gotcha Handling large zip files or numerous small files synchronously can lead to browser unresponsiveness or crashes, particularly in older browsers like IE <= 9. JSZip's synchronous APIs are less performant for substantial workloads.
  Fix: Always use the asynchronous `generateAsync()` and `loadAsync()` methods introduced in v3. Utilize Promise-based workflows to prevent UI blocking. For optimal performance with binary data, prefer using typed arrays (e.g., `Uint8Array`, `ArrayBuffer`) as input/output types rather than strings.
• breaking Versions prior to 3.8.0 were vulnerable to 'zip slip' path traversal attacks when using `loadAsync()` with untrusted zip files, which could allow malicious files to be written outside the intended directory.
  Fix: Upgrade JSZip to version 3.8.0 or newer. This version sanitizes filenames by removing relative path components (e.g., `../`). The original unsanitized filename is available as `unsafeOriginalName` if needed.
• gotcha JSZip does not support all features of the ZIP specification. Specifically, encrypted zip files (especially those using older encryption methods like PKZIP 2.0, common from macOS `zip -e`), multi-volume archives, or extremely large ZIP64 files (where 64-bit integers exceed JavaScript's safe integer limits) are not fully supported, leading to failed `loadAsync()` operations.
  Fix: Avoid using JSZip with password-protected or multi-volume archives. If dealing with encrypted files, ensure they use AES encryption, which JSZip might support in specific contexts, but be aware that PKZIP 2.0 is not supported. For very large files, consider using Node.js stream-based APIs if applicable.

Install

• npm install jszip npm
• yarn add jszip yarn
• pnpm add jszip pnpm

Imports

• JSZip
  wrong:

  const JSZip = require('jszip');

  correct:

  import JSZip from 'jszip';

  CommonJS `require` is typical in Node.js, but `import JSZip from 'jszip'` is the idiomatic ESM import, often requiring `allowSyntheticDefaultImports` in TypeScript or bundler configuration to treat the CommonJS export as a default. For strict CommonJS in TypeScript, use `import JSZip = require('jszip');`.
• JSZip.loadAsync
  wrong:

  import { loadAsync } from 'jszip';

  correct:

  import JSZip from 'jszip';
  const zip = await JSZip.loadAsync(data);

  loadAsync is a static method on the JSZip class, not a named export. Ensure you import the class itself to access this method. Available since v3.0.0.
• JSZip.support
  wrong:

  import { support } from 'jszip';

  correct:

  import JSZip from 'jszip';
  if (JSZip.support.blob) { /* ... */ }

  support is a static property on the JSZip class, used for feature detection (e.g., support for ArrayBuffer, Blob, Promises, Node.js Buffer).

Quickstart

This quickstart demonstrates creating a zip file with text and binary content, including nested folders, and asynchronously generating a Blob to trigger a browser download.

import JSZip from 'jszip';

async function createAndDownloadZip() {
  const zip = new JSZip();

  zip.file("Hello.txt", "Hello World\n");

  const imgFolder = zip.folder("images");
  // Assume imgData is a base64 encoded string of an image
  const imgData = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII='; // 1x1 transparent PNG
  imgFolder.file("smile.gif", imgData, { base64: true });

  zip.file("nested/path/document.pdf", new Uint8Array([73, 84, 73, 83, 32, 65, 32, 80, 68, 70, 32, 70, 73, 76, 69]), { binary: true });

  try {
    const content = await zip.generateAsync({ type: "blob", compression: "DEFLATE" });
    // In a browser, you would typically use a library like FileSaver.js
    // or create a URL object to trigger a download.
    const url = URL.createObjectURL(content);
    const a = document.createElement('a');
    a.href = url;
    a.download = "example.zip";
    document.body.appendChild(a);
    a.click();
    document.body.removeChild(a);
    URL.revokeObjectURL(url);
    console.log("Zip file generated and download initiated.");
  } catch (error) {
    console.error("Error generating zip file:", error);
  }
}

// Call the function to create and download the zip
createAndDownloadZip();