A better zip download experience — 1 line of code. (v3)
🌐 Live demo / home page: https://spuds0588.github.io/ZipLayer/ — try the wizard with a simulated loan file.
ZipLayer is a zero-config, ultra-lightweight, open-source (MIT) JavaScript SDK and web component that makes it easy for end users to download and interact with zip files — without requiring the end user to have an unzipping utility.
Instead of forcing users to download one massive monolithic ZIP, ZipLayer launches a wizard modal that streams the archive into the browser, previews its contents ("X-Ray"), and lets users grab exactly what they need:
- ⬇️ Selective download — pick individual files
- 📁 Direct-to-folder extraction — unpack straight into an OS folder (Chromium desktop)
- 🔗 Fallback download — the entire zip as a plain download (legacy browsers)
URL sources are streamed through a Web Worker straight into the browser's Origin Private File System (OPFS) — flat RAM even on 1 GB+ archives, with download progress. Everything runs 100% client-side. No backend, no API keys, no servers.
| ⚡ Zero Setup | No build step, no worker files to eject, no backend. Drop it in and it works. |
| 🔍 X-Ray Preview | Stream the archive and inspect the directory tree before downloading anything. |
| 🧵 Worker + OPFS Streaming | URL sources decompress in a Web Worker and write straight to the browser's OPFS — flat RAM on huge archives. |
| ⬇️ Selective Download | Let users tick the files they actually need instead of grabbing one giant zip. |
| 📁 Direct-to-OS Streaming | Extract straight into an OS folder via File System Access — the worker streams files directly to disk, no OPFS round-trip. |
| 🛡️ Graceful Fallback | Device-aware tiers: direct extraction → OPFS preview → plain download fallback. |
| 🔓 Open Source | MIT licensed. Fully transparent, privacy-first, free for personal and commercial use. |
<!-- 1 line of code -->
<zip-layer-modal src="https://portal.com/api/export.zip"></zip-layer-modal><script type="module">
import "./src/zip-layer-modal.js";
document.querySelector("zip-layer-modal").open();
</script>That's it. The modal streams the archive, shows download progress, then presents the X-Ray contents with the three options.
Use the SDK directly without any UI:
import { ZipLayer } from "./src/ziplayer.js";
// 1. Device capabilities (Tier 1 / 2 / 3)
const caps = ZipLayer.getDeviceCapabilities();
// { canPreview: boolean, canExtractLocal: boolean, mustFallback: boolean }
if (caps.mustFallback) {
// Legacy: plain download
window.location.href = "https://portal.com/api/export.zip";
} else {
// 2. X-Ray: stream + inspect contents
const archive = await ZipLayer.xray("https://portal.com/api/export.zip", {
onProgress: (pct) => console.log(`Streaming: ${pct}%`), // optional
});
const tree = archive.getFileTree(); // [{ path, name, dir, size, compressedSize }]
// 3. Selectively extract one file
const file = await archive.extractFile(tree[0].path); // native File object
// 4. Or extract everything to an OS folder (Tier 1 only)
if (caps.canExtractLocal) {
await archive.extractToLocalFolder({
onProgress: (pct) => console.log(`Unpacking: ${pct}%`),
});
}
// 5. GLBA-friendly cleanup when done (wipes OPFS session storage)
archive.destroy();
}ZipLayer.xray() accepts a URL string, ArrayBuffer, TypedArray, or a File/Blob. URL strings stream — the fetch pipe hands compressed chunks to a module Worker (src/zip-worker.js) that decompresses with fflate and writes each file straight into OPFS, one chunk in flight at a time (backpressured, flat RAM). On devices without OPFS or Workers, or for raw bytes/File/Blob input, it falls back to in-memory parsing automatically. ZipLayer.canStream() reports whether streaming is available on the current device.
The site and library are fully static and root-relative, so they work from any host — including GitHub Pages and CDNs like jsDelivr — with no build step or configuration.
GitHub Pages — the home page is live at https://spuds0588.github.io/ZipLayer/ (served from the repo root via .nojekyll).
jsDelivr (GitHub) — the ESM modules are dependency-free and import each other relatively, so they work straight off the CDN:
<script type="module">
import "https://cdn.jsdelivr.net/gh/Spuds0588/ZipLayer@main/src/zip-layer-modal.js";
document.querySelector("zip-layer-modal").open();
</script>👉 Open the home page → https://spuds0588.github.io/ZipLayer/ (or just open index.html) and click ⬇ Download Example Zip to launch the wizard with a simulated mortgage loan file (assets/JohnSmith-LoanFile.zip) — W-2, pay stub, sales contract, and driver's license for a fictitious borrower. The example archive is committed as a static asset — swap it for your own zip any time.
| Tier | Browsers | Capabilities |
|---|---|---|
| Tier 1 | Chromium desktop | Full OPFS + File System Access — direct-to-folder extraction |
| Tier 2 | Modern Safari / Firefox / mobile | OPFS enabled — X-Ray preview + selective file download |
| Tier 3 | Legacy | Graceful fallback to a plain .zip download |
getDeviceCapabilities() evaluates navigator.storage.getDirectory (OPFS), Worker support, and window.showDirectoryPicker (File System Access) to pick the right tier automatically. Phase 2 streaming (Worker + OPFS) requires a secure context — GitHub Pages, jsDelivr, and localhost all qualify; xray() degrades gracefully to in-memory parsing otherwise.
We collect nothing at all — and we never will. ZipLayer runs entirely in your browser: no servers, no accounts, no analytics, no cookies, no trackers. Your files never leave your machine. See Privacy Policy.
- 💌 MailLayer — native email sending from a Chrome extension
- ✉️ MailLayer Embedded — drop-in email script for the web
Building with ZipLayer using a vibe coder, Cursor, Copilot, Claude Code, or any other AI coding agent? This repo ships AGENTS.md, a knowledge file that teaches coding agents how to use ZipLayer: quick-start integration for the drop-in modal and headless SDK, the full API reference, browser-support tiers, and integration gotchas. Many agents read AGENTS.md automatically — point yours at it and it can wire ZipLayer into your app without guessing. Point your agent at it and go.
npm install # installs fflate (the only dependency)
npm run dev # start the local preview server (http://localhost:4173)
npm run build # build static site into dist/ZipLayer's archive engine is fflate (MIT) by Arjun Barrett — a tiny, high-performance, dependency-free zip/gzip library that does all the heavy lifting. A vendored copy ships in lib/fflate.mjs, so ZipLayer stays 100% offline and dependency-free at runtime.
MIT © 2026 ZipLayer.