How to ratio calculator in developer workflows
- Step 1Grab the artifact — Download the release ZIP from your CI run, registry, or PR. The calculator reads it locally — no need to check out the branch or upload the artifact anywhere.
- Step 2Drop it on the tool — Open /archive-tools/compression-ratio-calculator and drop the single ZIP. Note: a
.tar.gzor.7zCI tarball won't work — it's ZIP-only. Convert first if needed. - Step 3Read the per-entry table — Process (there are no options to configure). Scan the
methodandratiocolumns. Entries showingDeflateat ~0% are re-compressing already-compressed data — wasted build CPU. - Step 4Rank the offenders — Download the CSV and sort ascending by
ratioin a spreadsheet. The worst-compressing files rise to the top: those are your candidates to mark Stored in the build, or to exclude/optimise upstream. - Step 5Compare against the previous release — Run the same archive from the prior tag and diff the two SUMMARY ratios. A sudden drop with the same content usually means a method or build-config change — track it down before shipping.
- Step 6Act on the findings — To auto-pick Stored for media and Deflate for text, repack with smart-archive-compressor. To trial multiple levels and compare size vs time, use compression-level-optimizer.
Reading the report as a developer
What each column tells you about your build, and the action it implies.
| Column / value | What it means for your build | Action |
|---|---|---|
method = Deflate, ratio ≈ 0% | Re-deflating already-compressed data (PNG, jar, nested gz) | Mark that entry Stored in the build |
method = Stored, big entry | Shipped uncompressed on purpose (media/binary) | Usually correct; verify it's intentional |
method = Deflate, ratio high (70%+) | Text/source compressing well | Leave as is |
ratio = — | Zero-byte entry | Likely a placeholder; safe to ignore |
| SUMMARY ratio drop vs last release | Packing changed (method/config regression) | Diff the build config between tags |
Unexpected method (LZMA/BZIP2/PPMd) | Build uses a non-Deflate method | Confirm consumers can read it |
Batch and tier options for artifact auditing
How many artifacts you can audit per job by tier, and where to go for bulk.
| Tier | Max ZIP size | Files per job | Bulk path |
|---|---|---|---|
| Free | 50 MB | 1 | One artifact at a time |
| Pro | 500 MB | 20 | Up to 20 ZIPs, or batch-compression-report |
| Pro-media | 2 GB | 100 | batch-compression-report |
| Developer | 2 GB | Unlimited (per UI batch) | batch-compression-report |
Cookbook
Real artifact-audit moments, the way the CSV reports them.
Find the bundled asset wasting build CPU
A web bundle re-deflated its already-optimised images. The ratio column flags them so you can switch those globs to Stored.
name,uncompressedSize,compressedSize,ratio,method dist/main.js,512000,118000,77.0%,Deflate dist/vendor.js,1048576,240000,77.1%,Deflate dist/logo.png,84000,83600,0.5%,Deflate dist/hero.jpg,612000,610200,0.3%,Deflate SUMMARY,2256576,1051800,53.4%, logo.png + hero.jpg gain ~0% from Deflate. Store them and you save CPU with no size cost.
Catch a packing regression between releases
v3 dropped to a far lower overall ratio for the same files — someone changed the pack step to store everything. The SUMMARY makes it obvious.
v2 SUMMARY: ...,71.8%, (Deflate across the board) v3 SUMMARY: ...,9.4%, (almost all Stored) Same file set, ratio cratered. The v3 build switched method to Stored unintentionally. Revert the pack step; re-run to confirm the ratio returns to ~72%.
Verify a nested archive isn't double-compressed
A release that bundles a vendored .gz inside the ZIP — re-deflating it is pure waste, and the ratio proves it.
name,uncompressedSize,compressedSize,ratio,method bin/app,4096000,1820000,55.6%,Deflate vendor/lib.tar.gz,9400000,9398800,0.0%,Deflate SUMMARY,13496000,11218800,16.9%, lib.tar.gz is already compressed; the 0.0% confirms the outer ZIP gained nothing. Store nested archives.
Convert a CI tarball before measuring
Your pipeline ships .tar.gz, which this tool can't read. Convert to ZIP first, then audit.
release.tar.gz on the calculator: Error: "Not a valid ZIP archive." Workflow: /archive-tools/tar-gz-to-zip -> release.zip -> drop release.zip on the calculator -> per-entry ratios for the tarball contents
Audit many artifacts at once (Pro+)
For a monorepo that produces a dozen ZIPs per build, the single-file calculator is one-at-a-time; the batch report aggregates them.
Single-file calculator: drop one ZIP per run.
Many artifacts at once (Pro+):
/archive-tools/batch-compression-report
-> one combined table across all dropped ZIPs,
so you compare packing across the whole build.Edge cases and what actually happens
Artifact is a .tar.gz / .tgz / .7z
Rejected: not a valid ZIPMany CI pipelines ship gzipped tarballs, which have no ZIP central directory — the calculator rejects them with Not a valid ZIP archive.. Convert first with tar-gz-to-zip (or archive-format-converter) and audit the resulting ZIP.
Entry shows method Stored at 0%
By designStored means the entry was written uncompressed, so its ratio is 0% — correct, not a bug. It's the right choice for media/binaries. Only investigate if a file you expected to be Deflate is unexpectedly Stored (a packing regression).
ZIP64 release (> 65,535 entries or > 4 GB entry)
Sentinel sizesThe reader uses the 32-bit size and 16-bit count fields and doesn't parse ZIP64 extras, so a huge entry reads the 0xFFFFFFFF sentinel and the count wraps at 65,535. Big monorepo artifacts can hit this — keep entries under 4 GB, or list with a CLI for accuracy.
No public API to wire into CI
By designArchive tools are browser-only with apiAvailable: false; there's no REST endpoint to POST an artifact to. On Pro+ the logic runs via the local @jadapps/runner (headless browser). For a true CI gate, use unzip -v/zipinfo in the pipeline and the calculator for interactive review.
Artifact over the tier size cap
Rejected: tier limitOver the cap you get File "name.zip" exceeds the <tier> tier per-job limit (<size>). Upgrade for larger files. (50 MB Free / 500 MB Pro / 2 GB above). Split with archive-splitter or upgrade for large artifacts.
Encrypted release ZIP
SupportedIf your distribution ZIP is AES-encrypted, the calculator still reports sizes and labels entries AES from the directory — no password needed to read the ratios. It just can't show file contents, which isn't what this tool does anyway.
Want the result reproducible across machines
SupportedThe report is deterministic from the archive's central directory — the same ZIP always yields the same CSV. If your concern is reproducible archive bytes (not the report), normalise timestamps with timestamp-normalizer before packing, then audit.
Need to compare which entries changed between releases
Use the right toolThe calculator profiles packing, not content changes. To see which entries were added/removed/modified between two archives, use archive-diff, then run the calculator on each side to compare ratios.
Frequently asked questions
Is there a CLI or API I can call from CI?
No public HTTP API — archive tools are browser-only (apiAvailable: false). On Pro+ the same logic runs via the local @jadapps/runner (a headless browser). For a CI step, unzip -v or zipinfo in the pipeline is the practical equivalent; use the calculator for interactive review.
Why is my release ZIP barely smaller than the files inside it?
Because most of the bytes are already-compressed data (images, fonts, nested archives, minified+gzipped assets) that Deflate can't shrink. The report shows them at ~0% ratio. Mark those entries Stored to stop wasting build CPU, or compress text-heavy content more aggressively.
Can it tell me which files to store vs deflate?
Indirectly — sort the CSV by ratio and any entry near 0% with method Deflate is a Store candidate. To act on it automatically, smart-archive-compressor picks Stored for media and Deflate for text when it repacks.
Does it work on my .tar.gz CI artifacts?
Not directly — it's ZIP-only and rejects tarballs with Not a valid ZIP archive.. Convert with tar-gz-to-zip first, then audit the ZIP. The contents and per-entry ratios survive the conversion.
How do I detect a packing regression between releases?
Run the calculator on both tags' artifacts and compare the SUMMARY ratios. A large drop with the same content usually means the pack step changed method (e.g. Deflate → Stored). Diff the build config to find the cause.
Can I audit many artifacts at once?
The single-file calculator does one ZIP per run (Pro allows 20 files per job). For a whole build's worth of ZIPs in one pass, use batch-compression-report on Pro+, which aggregates them into one table.
Are there any options to set?
No — the option schema is empty. There's no sort, level, or password control. You drop a ZIP, press Process, and get a deterministic CSV plus four metric chips (Files, Uncompressed total, Compressed total, Overall ratio).
Does it decompress my artifact?
No. It reads the central-directory size and method fields only, so it's fast and never expands a potentially huge or hostile entry. That's also why it can report ratios for encrypted (AES) entries without a password.
What compression methods can it report?
Stored, Shrunk, Imploded, Deflate, Deflate64, BZIP2, LZMA, XZ, PPMd, and AES (encrypted). If your build uses a non-Deflate method, the method column shows it — handy for confirming downstream consumers can read the format.
How big an artifact can I audit?
50 MB on Free, 500 MB on Pro, 2 GB on Pro-media/Developer, with per-archive entry caps of 500 / 50,000 / 500,000. The size cap is enforced before processing with a clear error message.
Is the report reproducible in code review?
Yes — it's deterministic from the archive's directory, so a reviewer running the same artifact gets an identical CSV. That makes it easy to attach the report to a PR and have others confirm the numbers.
How do I see which entries changed, not just how they're packed?
Use archive-diff to compare two archives' contents, then run the calculator on each to compare packing. The calculator answers 'how is it packed', archive-diff answers 'what changed'.
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.