Bundle Size Analysis

Track and optimize your app’s binary size over time

Tuist’s Bundle Size Analysis helps you understand, track, and optimize your app’s install and download sizes, ensuring your app stays lean and user-friendly.

Overview

Bundle size analysis provides:

Size Tracking

Monitor install and download sizes over time

Detailed Breakdown

See size contribution of every file and framework

Size Trends

Track size changes across branches and versions

Understanding your app’s size is critical for user acquisition. A 6MB increase can reduce downloads by up to 23% in emerging markets.

Key Metrics

Install Size

What it is: The amount of storage your app occupies on a device after installation.

• Includes all resources, frameworks, and assets
• Uncompressed size
• What users see in Settings > Storage

Download Size

What it is: The size of the app package users download from the App Store.

• Compressed .ipa file
• App Store Connect measurement
• Varies by device (App Thinning)

Size Breakdown

Detailed analysis of size contributors:

MyApp.app (87.2 MB install, 42.3 MB download)
├── Executable (12.4 MB)
├── Frameworks/ (38.2 MB)
│   ├── CoreFramework.framework (15.8 MB)
│   ├── Networking.framework (8.2 MB)
│   └── Analytics.framework (14.2 MB)
├── Assets.car (18.4 MB)
├── Resources/ (14.3 MB)
│   ├── Videos/ (8.2 MB)
│   ├── Images/ (4.1 MB)
│   └── Fonts/ (2.0 MB)
└── Other (3.9 MB)

Getting Started

1. Build your app

   Create a release build:

   tuist build --configuration Release
   
2. Upload bundle for analysis

   Share the app to generate bundle analysis:

   tuist share
   

   Tuist automatically analyzes the bundle and uploads metrics.

3. View analysis

   Check the bundle size dashboard:

   tuist project show
   

   Or visit your project in Tuist Cloud.

Viewing Bundle Analysis

Dashboard

Access bundle analysis in Tuist Cloud:

1. Navigate to your project
2. Go to Insights > Bundle Size
3. View size trends and breakdowns

Bundle Explorer

Interactive tree view of your app’s contents:

Tree View

Navigate the bundle hierarchy:

• Expand/collapse directories
• See size and percentage of each item
• Sort by size
• Filter by file type

List View

Flat list sorted by size:

• Largest files first
• Quick identification of heavy assets
• Search by name

Charts

Visual representations:

• Pie chart by category
• Treemap visualization
• Size over time graph

Size Trends

Historical Tracking

Monitor size changes over time:

┌──────────────────────────────────┐
│  Bundle Size Trend (30 days)   │
└──────────────────────────────────┘

90 MB ┊                      ●
85 MB ┊              ● ●     ●
80 MB ┊          ●            
75 MB ┊      ●               
70 MB ┊  ●                   
      └─────────────────────────────
       Jan        Feb        Mar

Deviation Tracking

See size changes compared to baseline:

• 🟢 Within target: Size is stable
• 🟡 Small increase: +2-5% growth
• 🔴 Large increase: +5%+ growth (needs attention)

Branch Comparison

Compare feature branch size against main:

Branch	Install Size	vs Main	Download Size	vs Main
main	87.2 MB	-	42.3 MB	-
feature/video	95.8 MB	🔴 +9.9%	46.1 MB	+9.0%
fix/images	85.1 MB	🟢 -2.4%	41.2 MB	-2.6%

Optimization Strategies

Identify Large Assets

1. Find heaviest resources

   Sort bundle contents by size in the explorer

2. Analyze necessity

   Question each large file:

   • Is it essential?
   • Can it be smaller?
   • Could it be on-demand?
3. Optimize or remove

   Apply optimizations (see below)

4. Measure impact

   Upload new bundle and compare sizes

Image Optimization

Use Asset Catalogs

• Enable App Thinning automatically
• Device-specific image delivery
• Compression optimization

// Use asset catalogs, not bundled PNGs
Image("logo") // ✓ Good
Image(UIImage(named: "logo.png")!) // ✗ Bad

Choose the right format

• HEIC/WebP: Best compression for photos
• PNG: Transparency required
• SVG: Vector graphics (via SF Symbols or PDF)

// Use SF Symbols when possible
Image(systemName: "star.fill") // Tiny size

Compress images

Use tools like ImageOptim or tinypng:

# Example with ImageOptim CLI
imageoptim Resources/**/*.png

Can reduce size by 30-60% without visible quality loss.

Lazy load when possible

Download heavy images on-demand:

// Download tutorial videos at runtime
// Not bundled with app
func downloadTutorial() async {
    let url = URL(string: "https://cdn.app.com/tutorial.mp4")!
    // Download...
}

Code Optimization

Remove unused code

• Delete dead code paths
• Remove unused dependencies
• Audit third-party libraries

# Use periphery to find unused code
periphery scan

Enable optimization flags

In release builds:

// Project.swift or Build Settings
SWIFT_OPTIMIZATION_LEVEL = "-O"
SWIFT_COMPILATION_MODE = "wholemodule"

Use dynamic frameworks sparingly

Dynamic frameworks add overhead:

• Prefer static linking for small frameworks
• Only use dynamic for shared or plugin frameworks

Dependency Audit

1. List all dependencies

   tuist dependencies list
   
2. Measure each dependency's size

   Check bundle breakdown for framework sizes

3. Find lighter alternatives

   • Do you need the full library?
   • Can you implement the feature yourself?
   • Are there smaller alternatives?
4. Remove or replace

   Update Package.swift or Project.swift

A single large dependency (like Firebase or AWS SDK) can add 10-30MB to your app.

CI/CD Integration

Automatic Size Tracking

Track bundle size in every build:

GitHub Actions

name: Track Bundle Size
on:
  pull_request:
    branches: [main]

jobs:
  bundle-size:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install Tuist
        run: curl -Ls https://install.tuist.io | bash
      
      - name: Build and analyze
        run: |
          tuist build --configuration Release
          tuist share --no-upload  # Analyze only
        env:
          TUIST_TOKEN: ${{ secrets.TUIST_TOKEN }}
      
      - name: Check size increase
        run: |
          # Tuist CLI can check if size increased
          tuist bundle check --max-increase 5%

PR Size Warnings

Get notified of size changes in pull requests:

## 📊 Bundle Size Report

**Install Size:** 89.2 MB (+2.0 MB, +2.3%)
**Download Size:** 43.1 MB (+0.8 MB, +1.9%)

### Changes:
- 🔴 +1.5 MB in Analytics.framework
- 🟡 +0.5 MB in Images/

[View detailed breakdown](https://tuist.dev/acme/myapp/bundles/xyz)

Size Budgets

Enforce size limits:

# .tuist/Config.yml
bundle:
  size_limits:
    install: 100MB  # Fail CI if install size exceeds 100MB
    download: 50MB  # Fail CI if download size exceeds 50MB
    increase: 5%    # Fail if size increases by more than 5%

Best Practices

Set Size Budgets

Define acceptable size ranges:

• Max install size
• Max download size
• Max per-release increase

Monitor Regularly

Check bundle analysis:

• Every release
• After adding dependencies
• When users report issues

Optimize Assets First

Assets are usually the biggest wins:

• Images: 30-60% savings
• Videos: Consider streaming
• Fonts: Subset unused glyphs

Review Dependencies

Audit third-party libraries:

• Quarterly dependency review
• Remove unused packages
• Find lighter alternatives

App Thinning

Leverage Apple’s App Thinning:

Slicing

What it is

App Store delivers device-specific assets:

• iPhone 15 Pro gets @3x images only
• iPad gets iPad-specific resources
• Older devices get compatible assets

Setup:

// Use asset catalogs with device variants
Assets.xcassets/
  Icon.imageset/
    [e-mail]  // iPhone SE
    [e-mail]  // iPhone 14
    [e-mail]  // iPhone 15 Pro

Bitcode (Deprecated)

Note

Bitcode was deprecated in Xcode 14. Modern apps use Metal shader compilation instead.

On-Demand Resources

What it is

Resources downloaded when needed:

• Game levels
• Tutorial content
• Additional languages

Example:

let request = NSBundleResourceRequest(tags: ["level2"])
request.beginAccessingResources { error in
    if error == nil {
        // Level 2 assets are now available
    }
}

Performance Impact

Bundle size affects user experience:

Size	User Impact
<50 MB	🟢 Excellent - Quick downloads, minimal storage concern
50-100 MB	🟡 Good - Acceptable for most users
100-200 MB	🟠 Fair - Slower downloads, storage consideration
>200 MB	🔴 Poor - Requires WiFi, significant storage, lower conversion

For every 6MB increase, expect a ~1% decrease in download conversion rate.

Next Steps

Build Insights

Analyze build performance and compilation time

Binary Caching

Speed up builds with intelligent caching