Bundle Analysis

The Bundle Analysis service helps you track your app’s size over time, identify what contributes to bundle bloat, and optimize your app for faster downloads and better user experience.

Overview

Bundle Analysis provides:

Size tracking: Monitor download and install sizes
Component breakdown: See what takes up space
Trend analysis: Track size changes over time
Regression detection: Alert on unexpected size increases
Optimization recommendations: Suggestions to reduce size

Prerequisites

Authenticate with Tuist Cloud
Configure your project:

Config.swift

import ProjectDescription

let config = Config(
    cloud: .cloud(
        url: "https://cloud.tuist.io",
        projectId: "your-org/your-project"
    )
)

Uploading Bundles for Analysis

iOS Bundles (IPA)

Upload an IPA for analysis:

tuist build MyApp --platform iOS --configuration Release
tuist bundle upload MyApp

Tuist will:

Extract the IPA contents
Analyze all components (binaries, assets, resources)
Calculate download and install sizes
Upload analysis to cloud

macOS Bundles (.app)

Analyze macOS app bundles:

tuist build MyMacApp --platform macOS --configuration Release
tuist bundle upload MyMacApp --platform macOS

Android Bundles (APK/AAB)

Upload Android bundles:

# APK analysis
tuist bundle upload MyApp.apk --platform Android

# AAB analysis
tuist bundle upload MyApp.aab --platform Android

Archives (.xcarchive)

Analyze Xcode archives:

tuist bundle upload MyApp.xcarchive

Bundle analysis automatically happens when you upload previews with tuist share.

Bundle Components

What Gets Analyzed

The service analyzes:

Executables: Main binary and embedded frameworks
Assets: Images, icons, asset catalogs
Resources: Localization files, fonts, data files
Frameworks: Embedded frameworks and libraries
Debug symbols: dSYM files (if included)

Size Metrics

Two key metrics are tracked:

Download size: Compressed size users download from the App Store
Install size: Uncompressed size on device

Download size: 25.3 MB
Install size: 67.8 MB
Compression ratio: 2.68x

Viewing Bundle Analysis

List Bundles

View all analyzed bundles:

tuist bundle list

Shows:

Bundle version and build number
Upload date
Download and install sizes
Platform and supported devices

Bundle Details

Get detailed analysis for a specific bundle:

tuist bundle show bundle-id-123

Displays:

Size breakdown by component type
Largest files
Comparison with previous version
Optimization suggestions

Web Dashboard

Access the bundle analysis dashboard:

https://cloud.tuist.io/your-org/your-project/bundles

The dashboard provides:

Interactive size trend charts
Component breakdown visualizations
File-level drill-down
Historical comparisons

Component Breakdown

By File Type

See size distribution by file type:

Executables:    15.2 MB (22.4%)
Images:         28.5 MB (42.0%)
Asset Catalogs: 12.3 MB (18.1%)
Fonts:           4.2 MB  (6.2%)
Localizations:   3.8 MB  (5.6%)
Other:           3.8 MB  (5.6%)
─────────────────────────────
Total Install:  67.8 MB

By Framework

Break down by embedded frameworks:

MyApp:           15.2 MB
Networking:       3.5 MB
UI:               5.8 MB
ThirdParty:       8.2 MB

Largest Files

Identify the biggest individual files:

background_video.mp4     - 8.5 MB
app_binary               - 7.2 MB
icon_assets.car          - 4.3 MB
font_family.ttf          - 2.8 MB
translations.lproj       - 1.9 MB

Size Trends

Historical Tracking

Track size changes over time:

Version   Download  Install   Change
1.0     25.3 MB   67.8 MB   +1.2 MB
0.0     24.1 MB   65.6 MB   -0.5 MB
9.0     24.6 MB   68.1 MB   +3.2 MB
8.0     21.4 MB   59.9 MB   baseline

Size Budget

Set size budgets and get alerts:

Config.swift

let config = Config(
    cloud: .cloud(
        url: "https://cloud.tuist.io",
        projectId: "your-org/your-project",
        options: .options(
            bundleSizeBudget: .budget(
                downloadSize: 30 * 1024 * 1024,  // 30 MB
                installSize: 75 * 1024 * 1024     // 75 MB
            )
        )
    )
)

When a build exceeds the budget:

CI builds fail
Team receives notifications
Analysis shows what caused the increase

Regression Detection

Automatic Alerts

Get notified when bundle size increases unexpectedly:

⚠️ Bundle size increased by 15% (3.2 MB)
   Largest additions:
   - new_feature_assets.car (+2.1 MB)
   - updated_framework (+1.1 MB)

CI Integration

Fail CI builds on size regressions:

.github/workflows/build.yml

name: Build
on: [pull_request]

jobs:
  build:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Tuist
        run: curl -Ls https://install.tuist.io | bash
      
      - name: Authenticate
        run: tuist auth login
      
      - name: Build and analyze
        run: tuist build MyApp --platform iOS --configuration Release
      
      - name: Upload bundle
        run: tuist bundle upload MyApp --fail-on-regression

PR Comments

Post bundle analysis on pull requests:

- name: Comment PR with bundle size
  uses: actions/github-script@v7
  with:
    script: |
      const analysis = JSON.parse(process.env.BUNDLE_ANALYSIS);
      await github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body: `## Bundle Size Analysis\n\n` +
              `Download: ${analysis.downloadSize}\n` +
              `Install: ${analysis.installSize}\n` +
              `Change: ${analysis.change}`
      });

Optimization Recommendations

Image Optimization

Tuist identifies opportunities to:

Convert images to WebP or HEIC
Remove unused @3x assets
Compress asset catalogs
Use lossy compression where appropriate

Asset Catalog Analysis

Suggestions for asset catalogs:

💡 Optimization Opportunities

Icons.xcassets contains 12 unused images (2.3 MB)
Consider using vector PDFs instead of PNG @2x/@3x (save ~1.5 MB)
Some images can be compressed further (save ~800 KB)

Framework Optimization

Identify unused frameworks to remove
Suggest dynamic framework candidates
Recommend framework thinning

Code Optimization

Dead code detection
Unused symbols
Duplicate symbols across frameworks

App Store Size Estimation

Universal vs App Thinning

Compare universal binary size with thinned sizes:

Universal (all architectures):
  Download: 45.2 MB
  Install: 120.5 MB

App Thinned for iPhone 15 Pro:
  Download: 25.3 MB
  Install: 67.8 MB
  
Savings: 19.9 MB (44%)

Per-Device Estimates

Estimate size for different devices:

iPhone SE (2nd gen):  24.1 MB
iPhone 15:            25.3 MB
iPhone 15 Pro Max:    26.8 MB
iPad Air:             27.5 MB

Advanced Analysis

Binary Symbol Analysis

Analyze what’s in your executable:

tuist bundle symbols MyApp

Shows:

Largest symbols
Unused symbols (with optimization flags)
Swift vs Objective-C distribution
Standard library overhead

Localization Analysis

Break down by language:

English:    1.2 MB (baseline)
Spanish:    1.3 MB (+100 KB)
French:     1.3 MB (+100 KB)
German:     1.4 MB (+200 KB)
Japanese:   1.8 MB (+600 KB)

Recommendations:

Remove unused localizations
Use on-demand resources
Optimize string files

On-Demand Resources

Track on-demand resource usage:

Initial Download:  25.3 MB
On-Demand:
  Level Packs:      12.5 MB
  Extra Content:     8.2 MB

CI/CD Integration

Automated Bundle Uploads

.github/workflows/release.yml

name: Release
on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Tuist
        run: curl -Ls https://install.tuist.io | bash
      
      - name: Authenticate
        run: tuist auth login
      
      - name: Build release
        run: tuist build MyApp --platform iOS --configuration Release
      
      - name: Upload to TestFlight
        run: xcrun altool --upload-app -f MyApp.ipa ...
      
      - name: Analyze bundle
        run: tuist bundle upload MyApp --tag ${{ github.ref_name }}

Size Regression Check

#!/bin/bash
# Add to CI pipeline

BASE_SIZE=$(tuist bundle list --branch main --latest --json | jq '.installSize')
CURRENT_SIZE=$(tuist bundle upload MyApp --json | jq '.installSize')
DIFF=$((CURRENT_SIZE - BASE_SIZE))
DIFF_PCT=$((100 * DIFF / BASE_SIZE))

if [ $DIFF_PCT -gt 10 ]; then
  echo "❌ Bundle size increased by ${DIFF_PCT}% (${DIFF} bytes)"
  exit 1
fi

echo "✅ Bundle size within acceptable range"

Best Practices

Set and enforce size budgets

Define acceptable size limits and fail CI builds that exceed them.

Analyze every release candidate

Always run bundle analysis before submitting to App Store.

Track size in code review

Include bundle size changes in PR descriptions and reviews.

Optimize assets regularly

Run asset optimization passes quarterly to compress and remove unused assets.

Use on-demand resources

Move non-essential content to on-demand resources to reduce initial download.

Troubleshooting

Analysis Fails

If bundle analysis fails:

Verify the bundle is valid and builds successfully
Check authentication: tuist auth whoami
Ensure sufficient storage quota

Inaccurate Size Estimates

If size estimates seem wrong:

Compare with actual App Store Connect sizes
Verify bitcode settings (if applicable)
Check app thinning configuration

Missing Components

If some components aren’t analyzed:

Ensure all assets are included in the bundle
Verify embedded frameworks are present
Check that the archive includes all targets

Next Steps

Build Insights

View bundle size trends in the insights dashboard

Optimization Guide

Learn techniques to reduce app size

​Overview

​Prerequisites

​Uploading Bundles for Analysis

​iOS Bundles (IPA)

​macOS Bundles (.app)

​Android Bundles (APK/AAB)

​Archives (.xcarchive)

​Bundle Components

​What Gets Analyzed

​Size Metrics

​Viewing Bundle Analysis

​List Bundles

​Bundle Details

​Web Dashboard

​Component Breakdown

​By File Type

​By Framework

​Largest Files

​Size Trends

​Historical Tracking

​Size Budget

​Regression Detection

​Automatic Alerts

​CI Integration

​PR Comments

​Optimization Recommendations

​Image Optimization

​Asset Catalog Analysis

​Framework Optimization

​Code Optimization

​App Store Size Estimation

​Universal vs App Thinning

​Per-Device Estimates

​Advanced Analysis

​Binary Symbol Analysis

​Localization Analysis

​On-Demand Resources

​CI/CD Integration

​Automated Bundle Uploads

​Size Regression Check

​Best Practices

​Troubleshooting

​Analysis Fails

​Inaccurate Size Estimates

​Missing Components

​Next Steps

Build Insights

Optimization Guide

Overview

Prerequisites

Uploading Bundles for Analysis

iOS Bundles (IPA)

macOS Bundles (.app)

Android Bundles (APK/AAB)

Archives (.xcarchive)

Bundle Components

What Gets Analyzed

Size Metrics

Viewing Bundle Analysis

List Bundles

Bundle Details

Web Dashboard

Component Breakdown

By File Type

By Framework

Largest Files

Size Trends

Historical Tracking

Size Budget

Regression Detection

Automatic Alerts

CI Integration

PR Comments

Optimization Recommendations

Image Optimization

Asset Catalog Analysis

Framework Optimization

Code Optimization

App Store Size Estimation

Universal vs App Thinning

Per-Device Estimates

Advanced Analysis

Binary Symbol Analysis

Localization Analysis

On-Demand Resources

CI/CD Integration

Automated Bundle Uploads

Size Regression Check

Best Practices

Troubleshooting

Analysis Fails

Inaccurate Size Estimates

Missing Components

Next Steps