docs(server): explain bundle size computation and App Store Connect comparison

What changed

Adds an “Understanding bundle sizes” section to the Bundle insights docs (server/priv/docs/en/guides/features/bundle-size.md). The section documents:

• What the values mean — install size vs download size, and that download size is only reported for .ipa inputs (not .xcarchive or .app).
• The unit — sizes are stored in bytes and displayed as decimal MB (1 MB = 1,000,000 bytes), matching the convention Apple uses for storage and app sizes, with a worked example (733,446,863 bytes → 733.4 MB).
• A “Comparing with App Store Connect” subsection — how Tuist’s numbers relate to App Store Connect’s report.

Why

Users repeatedly ask why Tuist’s reported bundle sizes differ from what they see in App Store Connect, and the existing page only covered how to use the feature, never what the numbers represent or how to compare them. The docs are the durable place to answer this.

The reasoning captured

The page now explains the actual mechanics behind the discrepancy:

• Tuist measures the bundle exactly as provided and does not apply app thinning, so its numbers correspond to App Store Connect’s Universal (unthinned) row, not the per-device variants.
• Install size lands close to the Universal install size; App Store Connect reports slightly higher because it includes on-device overhead (filesystem block allocation and Apple’s own estimation) that a raw file-size measurement doesn’t capture.
• Download size reads lower than the Universal download size because Apple encrypts the binary after upload, and encrypted data compresses less efficiently — a step that happens on Apple’s side and isn’t visible to Tuist.
• Per-device rows are smaller again due to app thinning, which Tuist does not currently apply.

These mechanics were derived from the open-source Rosalind analyzer (which the CLI uses): install_size is the summed logical size of the unzipped .app, and download_size is the size of the .ipa archive itself.

Scope notes

• English source only. The other-language bundle-size.md files are intentionally left untouched — those sync via Weblate / the tuistit bot.
• Pure-markdown addition using only constructs already present in the file (headings with {#anchor}, lists, inline code, standard links); no custom components or code-groups.
• A follow-up opportunity (not in this PR): adding per-device (thinned) size support to Rosalind, validated against App Store Connect’s per-device rows.

Validation

Not rendered in a running server — the change is pure markdown matching the file’s existing conventions, and booting the full Phoenix + Postgres + ClickHouse stack was disproportionate for this. Happy to render and screenshot on request.

🤖 Generated with Claude Code

No GitHub comments yet.