// ============================================ // README.md // ============================================ /*

Browser ZIP

A lightweight, zero-dependency library for creating ZIP files in the browser using the native Compression Streams API.

Installation

Via npm

npm install sum-zipper

Via CDN (No build step required!)

<script src="https://unpkg.com/sum-zipper@latest/dist/browser-zip.min.js"></script>
<script>
  const { createZip, downloadZip } = BrowserZip;
  // Ready to use!
</script>

Download

Download browser-zip.min.js from the releases page and include it in your HTML.

Usage

Basic Example with Folder Structure

import { createZip, downloadZip } from "browser-zip";

const files = [
  { name: "folder1/hello.txt", content: "Hello World!" },
  {
    name: "folder1/subfolder/data.json",
    content: JSON.stringify({ foo: "bar" }),
  },
  { name: "folder2/readme.md", content: "# My Project" },
  { name: "root-file.txt", content: "This is in the root" },
];

const zipData = await createZip(files);
downloadZip(zipData, "my-archive.zip");

From File Input (Preserves Folder Structure)

<!-- Allow directory selection -->
<input type="file" webkitdirectory multiple />

import { createZipFromFiles, downloadZip } from "browser-zip";

const input = document.querySelector('input[type="file"]');
input.addEventListener("change", async (e) => {
  const files = Array.from(e.target.files);
  // Automatically preserves folder structure from webkitRelativePath
  const zipData = await createZipFromFiles(files);
  downloadZip(zipData, "uploaded-folder.zip");
});

Create Nested ZIPs (Zip each child folder separately)

import { createNestedZip, downloadZip } from "browser-zip";

// Your folder structure:
const files = [
  { name: "parent/src/index.js", content: 'console.log("main")' },
  { name: "parent/src/utils.js", content: "export const help = () => {}" },
  { name: "parent/dist/package/index.ts", content: "export {}" },
  { name: "parent/dist/build.js", content: "compiled code" },
  { name: "parent/README.md", content: "# Parent level file" },
];

// This creates: parent.zip with src.zip, dist.zip, and README.md inside
const zipData = await createNestedZip(files);
downloadZip(zipData, "parent.zip");

Result when extracted:

parent.zip/
├── src.zip          ← Contains index.js, utils.js
├── dist.zip         ← Contains package/index.ts, build.js
└── README.md        ← Root files stay as-is

What's inside src.zip:

src/
├── index.js
└── utils.js

What's inside dist.zip:

dist/
├── package/
│   └── index.ts
└── build.js

Create from Object

import { createZipFromObject, downloadZip } from "browser-zip";

const fileObject = {
  "docs/readme.md": "# Documentation",
  "src/index.js": 'console.log("hello")',
  "config.json": JSON.stringify({ version: "1.0.0" }),
};

const zipData = await createZipFromObject(fileObject);
downloadZip(zipData, "project.zip");

Get as Blob (for uploading)

import { createZipBlob } from "browser-zip";

const files = [{ name: "file.txt", content: "Hello!" }];

const blob = await createZipBlob(files);

// Upload to server
const formData = new FormData();
formData.append("file", blob, "archive.zip");
await fetch("/upload", { method: "POST", body: formData });

API

createZip(files: ZipFile[]): Promise<Uint8Array>

Creates a ZIP archive from an array of files.

Parameters:

• files: Array of objects with name (string) and content (string | Uint8Array)

Returns: Promise that resolves to a Uint8Array containing the ZIP data

downloadZip(zipData: Uint8Array, filename?: string): void

Triggers a download of the ZIP file in the browser.

Parameters:

• zipData: The ZIP data as Uint8Array
• filename: Optional filename (default: 'archive.zip')

createZipFromFiles(fileList: File[]): Promise<Uint8Array>

Helper function to create a ZIP from browser File objects.

Parameters:

• fileList: Array of File objects (e.g., from file input)

Returns: Promise that resolves to a Uint8Array containing the ZIP data

createZipBlob(files: ZipFile[]): Promise<Blob>

Creates a ZIP and returns it as a Blob (useful for uploads).

Parameters:

• files: Array of ZipFile objects

Returns: Promise that resolves to a Blob

createNestedZip(files: ZipFile[], parentFolderName?: string): Promise<Uint8Array>

Creates a ZIP where each direct child folder becomes its own nested ZIP file.

Parameters:

• files: Array of ZipFile objects with paths
• parentFolderName: Optional parent folder name

Returns: Promise that resolves to a Uint8Array

Example:

// Input files:
// parent/src/file.js
// parent/dist/build.js

const zipData = await createNestedZip(files);
// Creates: parent.zip containing src.zip and dist.zip

createNestedZipWithParent(parentFolderName: string, files: ZipFile[]): Promise<Uint8Array>

Same as createNestedZip but ensures all files are under a parent folder first.

Parameters:

• parentFolderName: Name of the parent folder
• files: Array of ZipFile objects

Returns: Promise that resolves to a Uint8Array

Browser Compatibility

This library uses the Compression Streams API, which is supported in:

• Chrome 80+
• Edge 80+
• Safari 16.4+
• Firefox 113+

Features

✅ Zero dependencies
✅ Full TypeScript support
✅ Preserves folder structure
✅ Handles binary and text files
✅ Works with File API
✅ Create Blobs for uploads
✅ Lightweight and fast

License

MIT *