How to smart compressor in developer workflows
- Step 1Bundle a build or fixture set — Drop the output folder onto /archive-tools/smart-archive-compressor. Paths are kept, so
dist/,coverage/, or a fixtures tree rebuilds exactly. Pick level6for general use or9for text-heavy output. - Step 2Triage a PR artifact without checking out — When a PR ships a ZIP artifact, drop the files to repackage and inspect locally rather than rebuilding the branch. Faster than a full checkout when you just need to see the bundle.
- Step 3Diff before/after archive contents — For PRs that change archive contents, run /archive-tools/archive-diff over the two archives to see exactly which entries were added, removed, or changed — like
diff -ron extracted trees. - Step 4Normalize timestamps for reproducibility — Compress, then run /archive-tools/timestamp-normalizer with a fixed date (1980-01-01 is the ZIP epoch). This removes the
lastModified-driven byte drift so the ZIP is identical across machines. - Step 5Attach a checksum manifest — Run /archive-tools/checksum-generator (SHA-256 default) to emit a per-entry hash manifest. Commit it next to the artifact so a later build can attest the bytes match.
- Step 6Verify the bundle opens — Before handing off, run /archive-tools/archive-integrity-tester to confirm the ZIP's CRCs pass — a quick guard against a truncated download.
Dev workflow positioning
Where the Smart Compressor fits — and where you should reach for a scriptable tool instead.
| Task | Use the Smart Compressor? | Alternative |
|---|---|---|
| Quick local bundle of build output | Yes | — |
| Step inside a CI job | No (UI only, no API) | fflate in Node, or zip/tar CLI |
| Reproducible artifact | Yes, with a chain | Compress -> timestamp-normalizer |
| Diff two artifact ZIPs | Use the sibling tool | archive-diff |
| Supply-chain attestation | Yes, with a chain | checksum-generator manifest |
| Password-protected artifact | No (unencrypted output) | encrypted-zip-creator |
Reproducibility checklist
What makes the output deterministic. The compressor alone is not enough — the chain is.
| Factor | Default behaviour | Make it reproducible |
|---|---|---|
| Entry timestamps | From each file's lastModified | timestamp-normalizer at 1980-01-01 |
| Entry order | Order files are read | Drop files in a consistent order / from one folder |
| Compression level | Slider (default 6) | Pick a fixed level every time |
| Hidden files | Included if present (.DS_Store, .git) | filename-sanitizer first |
| Verification | None by default | checksum-generator manifest |
Batch and entry limits
Per-job caps. Developer tier raises the per-batch file count to unlimited.
| Tier | Files per batch | Max entries | Max bytes |
|---|---|---|---|
| Free | 1 | 500 | 50 MB |
| Pro | 20 | 50,000 | 500 MB |
| Pro-media | 100 | 500,000 | 2 GB |
| Developer | unlimited | 500,000 | 2 GB |
Cookbook
Developer-shaped recipes. The browser tool is a UI step; the chains below show how it composes with sibling tools to reach a reproducible, attestable artifact.
Reproducible build artifact
The canonical chain. The compressor alone produces machine-specific bytes; normalizing timestamps makes them identical.
dist/ contents identical on two machines. Compress only (level 6): machine A -> compressed.zip sha256: 9f2a... machine B -> compressed.zip sha256: c41d... (differs!) Compress -> timestamp-normalizer (1980-01-01): machine A -> reproducible.zip sha256: 7b80... machine B -> reproducible.zip sha256: 7b80... (match)
Attestable artifact with a manifest
Pair the reproducible ZIP with a SHA-256 manifest your build can verify later.
smart-archive-compressor (level 6) -> timestamp-normalizer (1980-01-01) -> checksum-generator (SHA-256) Artifacts: reproducible.zip manifest.txt (one SHA-256 per entry) Later build verifies entries against manifest.txt.
Review a PR artifact without checkout
Repackage a PR's shipped files locally to inspect the bundle, instead of rebuilding the branch.
Download the PR's changed files -> drop into smart-archive-compressor (level 0 to inspect raw) -> open compressed.zip in your archive viewer No branch checkout, no local rebuild.
Diff archive contents across a PR
When a PR changes an archive, the sibling diff tool shows exactly which entries moved — the compressor itself does not diff.
before.zip (main) after.zip (PR branch) /archive-tools/archive-diff: + added: dist/new-chunk.js - removed: dist/old-chunk.js ~ changed: dist/index.html (size 4.1 KB -> 4.4 KB)
Strip junk before bundling
Hidden OS/VCS files sneak into ZIPs and break reproducibility. Clean them with a sibling tool, then compress.
dropped folder includes .DS_Store, .git/... -> filename-sanitizer (drop Finder metadata) -> empty-folder-pruner (drop empty .git/refs dirs) -> smart-archive-compressor (level 6) Cleaner, smaller, reproducible bundle.
Edge cases and what actually happens
Looking for a CLI or API
UnsupportedThere is no public API or CLI for the Smart Compressor — it is a UI tool. For CI, use fflate in Node or a zip/tar CLI. JAD programmatic access is roadmap, not shipping today.
Output differs byte-for-byte across machines
ExpectedEntry timestamps come from each file's lastModified, so the same content yields different bytes on different machines. Chain /archive-tools/timestamp-normalizer at a fixed date to make it deterministic.
Hidden files break the diff
Expected.DS_Store, Thumbs.db, and .git are included if present and make two bundles differ. Run /archive-tools/filename-sanitizer before compressing so the artifact is clean.
Re-zipping an existing artifact
ExpectedFeeding a finished ZIP into DEFLATE gives ~0% gain. Extract with /archive-tools/multi-format-extractor first if you meant to recompress its contents.
Wanting the diff from this tool
RedirectThe compressor builds archives; it does not compare them. Use /archive-tools/archive-diff for before/after entry comparison across a PR.
Needs a password on the artifact
RedirectOutput is unencrypted. For a password-protected build artifact, use /archive-tools/encrypted-zip-creator (AES-256).
Batch of many files on Free
Tier limitFree processes one file per job and caps at 500 entries. For multi-file batches use Pro (20 files / 50,000 entries) or Developer (unlimited files / 500,000 entries).
Large dist/ exhausts the tab
Memory limitzipSync is in-memory, so a very large build output can run the tab out of RAM. For large local-file ZIPs, /archive-tools/streaming-zip-builder bounds memory.
Wrong compression for the data
ExpectedLevel 9 on already-minified/bundled assets wastes CPU for little gain. Use level 6 generally, and level 0 when the input is mostly pre-compressed (sourcemaps of binaries, embedded media).
Entry order changed the checksum
ExpectedFiles are zipped in read order; a different selection order can change the bytes even after timestamp normalization. Build from a single folder, in a consistent order, for stable checksums.
Frequently asked questions
Is there a CLI or API for this?
No. It is a UI tool. The closest scriptable equivalent is fflate in Node for ZIP/DEFLATE, or a zip/tar CLI. Programmatic JAD access is on the roadmap, not available now.
How do I make the output reproducible?
Compress, then run /archive-tools/timestamp-normalizer at a fixed date (1980-01-01). Entry timestamps otherwise come from lastModified and differ per machine.
How do I attest the artifact's contents?
Run /archive-tools/checksum-generator (SHA-256) to emit a per-entry manifest, and verify against it in a later build.
Can I diff two artifact ZIPs?
Not with this tool — use /archive-tools/archive-diff, which reports added, removed, and changed entries across two archives.
Does the slider match zip -9?
Yes. The slider is fflate's DEFLATE level; slider 9 is equivalent to zip -9, slider 0 stores without compression.
Will hidden files end up in my artifact?
Yes if present — .DS_Store, .git, Thumbs.db are all included. Strip them first with /archive-tools/filename-sanitizer for clean, reproducible bundles.
Can I password-protect the artifact?
Not on this tool — output is unencrypted. Use /archive-tools/encrypted-zip-creator for AES-256.
How many files can I bundle at once?
Free 1, Pro 20, Pro-media 100, Developer unlimited — within the entry caps (500 / 50,000 / 500,000).
Why did the same input give two different checksums?
Timestamps and/or entry order differed. Normalize timestamps and build from a single folder in a consistent order to get stable bytes.
Does the output need a special reader?
No. It is a standard ZIP — any consumer that reads ZIP reads it, with no JAD-specific wrapper.
What level should I use for build output?
6 for general output, 9 for text-heavy bundles, 0 when assets are already compressed/minified and DEFLATE has nothing to gain.
Can I bundle gigabytes of build output?
Up to 2 GB on Pro-media/Developer, but zipSync is in-memory. For very large ZIPs, /archive-tools/streaming-zip-builder keeps memory bounded.
Privacy first
Every JAD Archive tool runs entirely in your browser using fflate, @zip.js/zip.js, and the libarchive WASM bridge. Your archives never leave your device — verified by zero outbound network requests during processing.