client-zip

library2.5.0jsnpmunverified

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.

serialization

npm install client-zip

github ↗package ↗

INSTALL

IMPORT

SIG · CLIENT-ZIP

client-zip

serializationjavascriptv2.5.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

downloadZip

✓ import { downloadZip } from 'client-zip';

✗ const { downloadZip } = require('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

✓ import type { InputTypes } from 'client-zip';

✗ import { InputTypes } from 'client-zip';

TypeScript types should be imported using 'import type' for clarity and to prevent runtime issues in some environments.

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();

Debug

Known issues

breakingclient-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.

affects: >=2.0.0

gotchaclient-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.

affects: >=2.0.0

gotchaCancelling 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.

affects: >=2.4.1

gotchaFor 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.

affects: >=2.4.2

gotchaWhen 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).

affects: any

Errors

Common errors & fixes

ReferenceError: BigInt is not defined

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)

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)

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.

Upgrade

Version history

2.5.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Touffy/client-zip ↗

packagehttps://www.npmjs.com/package/client-zip ↗