Bundle Size Analysis

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

Build your app

Create a release build:

tuist build --configuration Release

Upload bundle for analysis

Share the app to generate bundle analysis:

tuist share

Tuist automatically analyzes the bundle and uploads metrics.

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:

Navigate to your project
Go to Insights > Bundle Size
View size trends and breakdowns

Bundle Explorer

Interactive tree view of your app’s contents:

Tree View
List View
Charts

Navigate the bundle hierarchy:

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

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

Find heaviest resources

Sort bundle contents by size in the explorer

Analyze necessity

Question each large file:

Is it essential?
Can it be smaller?
Could it be on-demand?

Optimize or remove

Apply optimizations (see below)

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

List all dependencies

tuist dependencies list

Measure each dependency's size

Check bundle breakdown for framework sizes

Find lighter alternatives

Do you need the full library?
Can you implement the feature yourself?
Are there smaller alternatives?

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/
    Icon@1x.png  // iPhone SE
    Icon@2x.png  // iPhone 14
    Icon@3x.png  // 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

​Overview

Size Tracking

Detailed Breakdown

Size Trends

​Key Metrics

​Install Size

​Download Size

​Size Breakdown

​Getting Started

​Viewing Bundle Analysis

​Dashboard

​Bundle Explorer

​Size Trends

​Historical Tracking

​Deviation Tracking

​Branch Comparison

​Optimization Strategies

​Identify Large Assets

​Image Optimization

​Code Optimization

​Dependency Audit

​CI/CD Integration

​Automatic Size Tracking

​PR Size Warnings

​Size Budgets

​Best Practices

Set Size Budgets

Monitor Regularly

Optimize Assets First

Review Dependencies

​App Thinning

​Slicing

​Bitcode (Deprecated)

​On-Demand Resources

​Performance Impact

​Next Steps

Build Insights

Binary Caching

Overview

Key Metrics

Install Size

Download Size

Size Breakdown

Getting Started

Viewing Bundle Analysis

Dashboard

Bundle Explorer

Size Trends

Historical Tracking

Deviation Tracking

Branch Comparison

Optimization Strategies

Identify Large Assets

Image Optimization

Code Optimization

Dependency Audit

CI/CD Integration

Automatic Size Tracking

PR Size Warnings

Size Budgets

Best Practices

App Thinning

Slicing

Bitcode (Deprecated)

On-Demand Resources

Performance Impact

Next Steps