Client-side Streaming ZIP Generator

2.5.0 · active · verified Tue Apr 21

client-zip is a lightweight, dependency-free JavaScript library for client-side generation of streaming ZIP archives directly in the browser. It allows developers to concatenate multiple files, often fetched from HTTP requests, into a single downloadable ZIP file without server-side processing. The current stable version is 2.5.0, with regular patch and minor releases indicating active maintenance. Key differentiators include its small bundle size (2.6kB gzipped), superior performance compared to alternatives like JSZip (reportedly 40x faster), and native support for modern browser streaming APIs. It handles Zip64 archives, necessary for large files, though this means generated ZIPs require a reader compatible with "ZIP version 4.5" and may not be universally readable by all older ZIP utilities. It does not perform file compression or unzipping.

Common errors

```
ReferenceError: BigInt is not defined
```
cause The client-zip library (v2.x) relies on BigInts, which are not supported in JavaScript environments targeting ES2019 or earlier.

fix Update your project's JavaScript compilation target (e.g., in tsconfig.json or Babel configuration) to ES2020 or later. If targeting older environments is strictly necessary, use client-zip v1.x.
```
Archive corruption error / Cannot open file (from an old ZIP tool)
```
cause client-zip v2.x generates Zip64 archives by default, which are not universally compatible with all legacy ZIP decompression utilities.

fix Use a modern ZIP extraction tool that supports Zip64 (ZIP version 4.5). For maximum compatibility with very old tools, consider using client-zip v1.x.
```
Potential memory leak identified (e.g., in browser dev tools)
```
cause A Blob URL created using `URL.createObjectURL()` was not explicitly released from memory.

fix Ensure `URL.revokeObjectURL(blobUrl)` is called for every Blob URL generated, typically after the associated download or use case is complete.

Warnings

breaking client-zip v2.x and above require environments that support BigInt. Attempting to transpile the library to targets lower than ES2020 will result in runtime errors.
Fix: Ensure your build target is ES2020 or higher (e.g., `"target": "ES2020"` in tsconfig.json, or configure Babel accordingly). For compatibility with ES2018 or lower, use client-zip v1.x, which does not utilize BigInts.
gotcha client-zip v2.x generates Zip64 archives, which specify 'ZIP version 4.5 required to unzip'. While widely supported, some older or non-compliant ZIP utilities may fail to open these archives.
Fix: Inform users that archives generated by v2.x require a modern ZIP reader compatible with Zip64. If broad compatibility with very old tools is critical, consider using client-zip v1.x.
gotcha Cancelling the output stream (e.g., browser closing the download) will now propagate an error to the source `AsyncIterable` input's iterator, causing it to halt.
Fix: When providing an `AsyncIterable` as input, ensure its iterator's `return` method is robust and can handle errors gracefully if the output stream is unexpectedly cancelled mid-process.
gotcha For archives with non-ASCII filenames, especially when intended for Windows users, the `buffersAreUTF8` option may be necessary to ensure correct display of filenames in some ZIP utilities.
Fix: If your archive contains non-ASCII filenames and is encountering display issues, set the `buffersAreUTF8: true` option in `downloadZip` or `makeZip` options.
gotcha When creating Blob URLs with `URL.createObjectURL` for downloading, these URLs persist in memory until explicitly revoked, potentially leading to memory leaks.
Fix: Always call `URL.revokeObjectURL(blobUrl)` after the generated Blob URL is no longer needed (e.g., after a download has started or completed, or when the temporary link is removed).

Install

npm install client-zip npm
yarn add client-zip yarn
pnpm add client-zip pnpm

Imports

downloadZip
wrong:
```
const { downloadZip } = require('client-zip');
```
correct:
```
import { downloadZip } from 'client-zip';
```
client-zip is an ES module and should be imported using ES import syntax. CommonJS 'require' is not supported.
makeZip
```
import { makeZip } from 'client-zip';
```
Used to get a ReadableStream directly instead of a Response wrapper from downloadZip.
predictLength
```
import { predictLength } from 'client-zip';
```
Estimates the final ZIP file size without creating it, useful for Content-Length headers.
InputTypes
wrong:
```
import { InputTypes } from 'client-zip';
```
correct:
```
import type { InputTypes } from 'client-zip';
```
TypeScript types should be imported using 'import type' for clarity and to prevent runtime issues in some environments.

Quickstart

Demonstrates how to use `downloadZip` to create a ZIP file from multiple inputs (a string and a fetched resource) and initiate a client-side download.

import { downloadZip } from 'client-zip';

async function downloadTestZip() {
  // Define what we want in the ZIP
  const code = await fetch("https://raw.githubusercontent.com/Touffy/client-zip/master/src/index.ts");
  const intro = { name: "intro.txt", lastModified: new Date(), input: "Hello. This is the client-zip library." };

  // Get the ZIP stream in a Blob
  const blob = await downloadZip([intro, code]).blob();

  // Make and click a temporary link to download the Blob
  const link = document.createElement("a");
  link.href = URL.createObjectURL(blob);
  link.download = "test.zip";
  link.click();
  link.remove();

  // In real life, don't forget to revoke your Blob URLs if you use them to prevent memory leaks.
  URL.revokeObjectURL(link.href);
}

downloadTestZip();

view raw JSON →