How to archive previewer in developer workflows
- Step 1Grab the artifact — Take the build output —
dist.zip,mypkg-1.0.0.tgz, a downloaded release asset — straight from your machine. Nothing needs to be uploaded. - Step 2Drop it into the previewer — Open archive-previewer, drop one archive, and press Process. There are no settings to tune.
- Step 3Verify the layout in the tree — Confirm the expected top-level:
dist/for a build,package/for an npm tarball, the right package root for a.jar. Spot a stray folder immediately. - Step 4Sort by size to catch bloat — The top-200 table is largest-first. A 40 MB source map or a checked-in
node_moduleswill be at the top — fix it before publishing. - Step 5Cross-check ZIP integrity fields — For ZIP, the Method and (parsed) CRC columns let you confirm files are Deflate-compressed as expected and spot Stored entries that should have compressed.
- Step 6Automate if it's recurring — For a repeating check, script
unzip -l/npm pack --dry-runin CI, or on Pro+ dispatch the previewer through the local @jadapps/runner for a headless browser run on your machine.
Developer artifacts the previewer reads
ZIP-family artifacts get full central-directory detail; tar-family and 7Z get tree + uncompressed sizes. Format is detected from magic bytes, so extension quirks don't matter.
| Artifact | Underlying format | What the preview confirms | Detail level |
|---|---|---|---|
npm tarball (.tgz) | GZIP+TAR | package/ root, that dist/ and files made it in | Tree + uncompressed size |
Java/Android (.jar, .apk) | ZIP | Class/asset layout, manifest presence, method + CRC | Full ZIP detail |
Release bundle (.zip) | ZIP | Single root folder, no leaked node_modules/.git | Full ZIP detail |
CI artifact (.tar.gz) | GZIP+TAR | Build outputs present, oversized maps/assets | Tree + uncompressed size |
Vendored dump (.7z) | 7Z (libarchive) | Folder structure and the biggest files | Tree + uncompressed size |
Office/OOXML (.docx, .xlsx) | ZIP | Internal XML + media parts | Full ZIP detail |
CLI equivalents and where the previewer fits
The previewer is the no-install, shareable option; the CLIs are the scriptable option. They overlap most on ZIP.
| Task | CLI command | Previewer equivalent | Best for |
|---|---|---|---|
| List a ZIP with sizes | unzip -l -v dist.zip | Drop ZIP → top-200 table | One-off, shareable HTML |
| List an npm tarball | tar -tzf pkg.tgz | Drop .tgz → tree | Quick visual layout check |
| Dry-run npm pack contents | npm pack --dry-run | Drop the built .tgz | Verify after pack |
| List a 7Z | 7z l dump.7z | Drop .7z → tree | When 7z isn't installed |
| Find biggest files | unzip -l | sort -k1 | Top-200 table (auto-sorted) | Spotting bloat at a glance |
Tier limits for the Archive Previewer
Per-job limits enforced before parsing. The previewer reads one archive at a time, so the batch column matters less here than the per-file size and the per-archive entry cap. Numbers are the live values from the archive tier-limit table.
| Tier | Max file size | Max entries / archive | Files per job | Notes |
|---|---|---|---|---|
| Free | 50 MB | 500 entries | 1 | Enough for a release ZIP or a Finder-zipped folder. Larger archives prompt an upgrade before any bytes are read. |
| Pro | 500 MB | 50,000 entries | 20 | Covers most CI artifacts and node_modules snapshots. Entry cap, not size, is usually the first wall on monorepo ZIPs. |
| Pro + Media | 2 GB | 500,000 entries | 100 | For dataset bundles and disk-image-sized archives. |
| Developer | 2 GB | 500,000 entries | unlimited | Same ceilings as Pro + Media with unlimited files per job for scripted runs via the runner. |
Cookbook
Artifact-inspection recipes that come up in real PR and release work — drop the artifact, read the answer, no extraction.
Catch node_modules leaking into a release ZIP
A misconfigured build packed dependencies into the release. The size-sorted table makes it impossible to miss.
Drop: release-1.0.0.zip (180 MB)
release-1.0.0.zip — 41,233 entries (ZIP)
Top files by size:
node_modules/.cache/... 62 MB
node_modules/typescript/ 18 MB
dist/app.js 1.2 MB
→ node_modules leaked. Fix .npmignore / build globs.Verify an npm tarball before publish
Confirm the .tgz produced by npm pack has the package/ root and includes dist/ but not test fixtures.
Drop: mypkg-2.1.0.tgz
mypkg-2.1.0.tgz — 96 entries (TAR)
/package/
├ dist/index.js
├ dist/index.d.ts
├ package.json
└ README.md
→ No test/ or src/ — files field is correct. Publish.Confirm a JAR's compression method
For ZIP-based artifacts the previewer shows the method. A JAR that should be Deflate but is mostly Stored signals a packaging mistake.
Drop: app.jar app.jar — 1,204 entries (ZIP) Name Size Compressed Method com/app/Main.class 8.1 KB 3.2 KB Deflate resources/big.bin 12 MB 12 MB Stored → big.bin is Stored (incompressible/binary) — expected.
Diff intent: is this the artifact I think it is?
Quick identity check by entry count and root folder before wiring it into a deploy step. (For a true two-archive diff, use the sibling tool.)
Drop: build-ci.zip → 318 entries (ZIP), root dist/ Drop: build-local.zip → 322 entries (ZIP), root dist/ 4 extra entries locally — likely .map files. For a precise added/removed/changed list, use archive-diff with both archives.
Inspect a 7Z dump with no 7-Zip installed
On a CI runner or a fresh machine without p7zip, the previewer still enumerates the 7Z via WASM.
$ 7z l vendor-dump.7z bash: 7z: command not found Previewer: vendor-dump.7z — 2,540 entries (7Z) Full tree renders; top-200 table by size. (Compressed = Size for 7Z — use compression-ratio-calculator for true ratios.)
Edge cases and what actually happens
Artifact larger than the tier cap
BlockedA 700 MB CI bundle exceeds the Pro 500 MB cap. Pro + Media / Developer raise it to 2 GB; Free is 50 MB. Past your ceiling, list it with unzip -l / tar -tzf in CI instead.
Over 50,000 entries on Pro
Entry capA node_modules-heavy artifact can exceed Pro's 50,000-entry cap while staying small in bytes. Pro + Media / Developer allow 500,000. For routine huge-tree checks, prefer a scripted CLI listing.
Compressed/ratio needed for a .tgz
By designThe previewer reports uncompressed sizes for tar-family and 7Z. To compare packed vs original for a tarball, use compression-ratio-calculator.
Comparing two builds
Use a sibling toolThe previewer lists one archive; it doesn't diff. For a precise added/removed/changed entry list between two artifacts, use archive-diff, which takes two archive inputs.
No public HTTP API
Browser-onlyArchive tools have no server-side endpoint; there's no REST API to POST a file to. Automation runs through the local @jadapps/runner on Pro+ (a headless Chromium on your machine), keeping bytes local.
Only top 200 files in the table
ExpectedThe table caps at the 200 largest files; the tree is complete and the header shows the true count. For a full machine-readable manifest in CI use file-listing-generator.
Stored entries that you expected compressed
PreservedThe Method column showing Stored on a text file may indicate a packaging step skipped compression. The previewer reports it faithfully; fix the build, then re-check. Already-compressed binaries being Stored is normal.
Extension doesn't match contents
SupportedA .jar is just a ZIP; a renamed .bin ZIP previews fine. Detection is by magic bytes, so mismatched or missing extensions don't break the preview.
Frequently asked questions
Can I call the Archive Previewer from a script or CI?
There's no public HTTP API — archive tools are browser-only with no server-side path. On Pro and above you can drive the tool through the local @jadapps/runner, a short-lived headless Chromium on your own machine, so it can sit inside a local check without uploading anything. For plain CI listing, unzip -l, tar -tzf, and npm pack --dry-run are usually the simpler primitives.
Does the previewer match `unzip -l -v` for a ZIP?
Yes in substance: same entry names, uncompressed and compressed sizes, timestamps, and it additionally labels the compression method (Deflate/Stored/LZMA/AES) and parses the CRC-32. It reads all of this from the central directory without decompressing, then renders it as a tree plus a size-sorted table.
How do I see if my release accidentally bundled node_modules?
Drop the release ZIP and read the top-200-by-size table — a leaked node_modules/ or .cache will dominate the top rows. The header's entry count is another tell: a tidy release is hundreds of entries, a leaked one is tens of thousands. Then fix your .npmignore / packaging globs and re-check.
Will it pollute my working directory like extracting does?
No. The previewer is strictly read-only — it parses the index (ZIP) or decodes entries in memory (tar/7Z) and renders a listing. Nothing is written to disk, so there's no unzip-and-clean-up cycle and no stray extracted files in your tree.
Can it tell me the difference between two build artifacts?
Not directly — it previews one archive at a time. For an exact added/removed/changed comparison between two builds, use archive-diff, which is built for two archive inputs. The previewer is good for a fast identity sanity check (entry count, root folder) before a deeper diff.
Does the previewer extract or decompress my archive?
For ZIP, no. It reads only the central directory — the index ZIP keeps at the end of the file — so a 1 GB ZIP with 50,000 entries lists in well under a second because no compressed bytes are touched. For every other format (7Z, RAR, TAR, GZIP, BZIP2, XZ, ISO) it must decode the whole archive in memory to enumerate entries, because those containers have no detached index a browser can parse. Nothing is written to disk and nothing is uploaded either way.
Why is the Compressed column equal to the Size column for my 7Z or TAR?
Because the previewer only has the real per-entry compressed size for ZIP, which it reads straight from the central directory. For 7Z, RAR, TAR, GZIP and the libarchive-handled formats it decodes the entries and reports the uncompressed byte length in both columns. So treat the Compressed column as meaningful for ZIP only. If you need true compressed-vs-original numbers for a non-ZIP archive, use compression-ratio-calculator.
Are timestamps in the tree accurate?
For ZIP, yes — each entry's DOS date/time is decoded from the central directory. For non-ZIP formats the previewer does not surface per-entry timestamps; it falls back to the archive file's own last-modified date for every entry. To normalise or inspect ZIP timestamps specifically, see timestamp-normalizer.
Can it preview password-protected archives?
For ZIP, yes — filenames in a ZIP central directory are stored in the clear even when the file data is AES-256 or ZipCrypto encrypted, so the tree and table render fine and the entry simply shows an encryption flag. The previewer never asks for or needs the password because it does not decompress ZIP data. Encrypted 7Z/RAR that libarchive cannot open without a password may fail to enumerate. To actually unlock and pull files, use multi-format-extractor.
Is there any options panel to configure?
No. The previewer has zero options — you drop one archive and press Process. There is no glob filter, no sort toggle, no depth slider. If you need to filter the listing by pattern, generate a CSV/JSON listing, or limit recursion, those are separate sibling tools: selective-extractor, file-listing-generator, and nested-archive-extractor.
How is the format detected — by extension?
By magic bytes, not extension. The first eight bytes are checked: PK for ZIP, 1F 8B for GZIP, BZh for BZIP2, the XZ and 7Z signatures, Rar! for RAR, and ustar at offset 257 for TAR. A .zip renamed to .bin still previews correctly; a corrupt header that matches nothing falls through to a best-effort ZIP attempt and otherwise errors.
Why do only 200 files show in the table?
The flat table is capped at the 200 largest files by uncompressed size so the HTML stays responsive. The folder tree above it is not capped — it renders every entry — and the header line reports the true total entry count. If you need a complete machine-readable listing of all entries, run file-listing-generator for CSV, JSON, or a full text tree.
Do my files get uploaded?
No. Archive tools are browser-only — there is no server-side path. The bytes are read by FileReader, parsed by fflate / libarchive WASM locally, and the result is rendered in the same tab. The result panel shows a 0 bytes uploaded badge. On Pro and above, scripted runs go through the local @jadapps/runner (a short-lived headless Chromium on your own machine), still without leaving your hardware.
Why is the compression method blank for my .tgz entries?
Because the Method column is populated only for ZIP, where the per-entry method lives in the central directory. For tar-family and 7Z the previewer enumerates entries via fflate/libarchive and reports uncompressed size without a per-entry method. That's expected, not a bug.
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.