Cutting a Capacitor Android build in half

#!/usr/bin/env node
/**
 * What a phone actually downloads from an Android App Bundle.
 *
 *     node delivered-size.mjs app-release.aab [density]
 *
 * `ls -l` on the .aab is not the download, and the gap is large enough to send
 * you optimising the wrong thing. Play splits a bundle per device — by screen
 * density, by ABI, by language — and strips its own metadata before delivery.
 *
 * The one that catches everybody: turning on R8 ADDS a multi-megabyte
 * BUNDLE-METADATA/.../proguard.map to the .aab. Play keeps it to deobfuscate
 * crash reports and never sends it to anyone. On one app that was 3.83 MB, so
 * the file on disk looked barely improved while the real download had halved.
 *
 * This is an estimate, not bundletool's exact figure. It moves when the real
 * one does, which is what makes a creeping regression visible — and it needs
 * nothing but unzip.
 */
import { execFileSync } from 'node:child_process';

const aab = process.argv[2];
const density = process.argv[3] ?? 'xxhdpi';

if (!aab) {
  console.error('usage: node delivered-size.mjs <bundle.aab> [density]');
  process.exit(1);
}

const others = ['ldpi', 'mdpi', 'hdpi', 'xhdpi', 'xxhdpi', 'xxxhdpi']
  .filter((d) => d !== density);

const lines = execFileSync('unzip', ['-lv', aab], {
  encoding: 'utf8',
  maxBuffer: 1 << 28,
}).split('\n');

let total = 0;
let kept = 0;
const buckets = {};

for (const line of lines) {
  // length  method  size  cmpr  date  time  crc-32  name
  const m = line.match(/^\s*(\d+)\s+\S+\s+(\d+)\s+\S+\s+\S+\s+\S+\s+\S+\s+(.+)$/);
  if (!m) continue;

  const compressed = Number(m[2]);
  const path = m[3].trim();
  total += compressed;

  // Never delivered: R8's mapping file and the signature block.
  if (path.startsWith('BUNDLE-METADATA/') || path.startsWith('META-INF/')) continue;
  // Delivered only to devices of that density.
  if (others.some((d) => path.includes(`-${d}-`) || path.includes(`-${d}/`))) continue;

  kept += compressed;
  const key = path.split('/').slice(0, 3).join('/');
  buckets[key] = (buckets[key] ?? 0) + compressed;
}

const mb = (n) => `${(n / 1048576).toFixed(2)} MB`;

console.log(aab);
console.log(`  .aab on disk        ${mb(total)}`);
console.log(`  delivered (${density})  ${mb(kept)}`);

for (const [k, v] of Object.entries(buckets).sort((a, b) => b[1] - a[1]).slice(0, 8)) {
  console.log(`      ${mb(v).padStart(8)}  ${k}`);
}

// Typical output before and after an optimisation pass:
//
//   .aab on disk        16.83 MB          .aab on disk        10.41 MB
//   delivered (xxhdpi)  13.09 MB          delivered (xxhdpi)   5.88 MB
//        3.01 MB  base/dex/classes2.dex        3.21 MB  base/dex/classes.dex
//        2.90 MB  base/dex/classes.dex         1.10 MB  base/assets/public
//        2.71 MB  base/dex/classes3.dex        1.03 MB  base/dex/classes2.dex
//        1.65 MB  base/assets/public           0.20 MB  base/resources.pb
//        0.93 MB  base/dex/classes4.dex        0.07 MB  base/res/mipmap-xxhdpi-v4

// The release block Capacitor does NOT give you.
//
// `npx cap add android` scaffolds a project with minifyEnabled false, so every
// class of Play Services, Firebase, gRPC and Guava ships whole. On one app that
// was four dex files, 9.55 MB compressed, 73% of the download.
//
// Turning R8 on took the delivered download from 13.09 MB to 7.76 MB.

android {

    // Play Services and Firebase package their .proto sources and a pile of
    // build metadata as Java resources. Android reads none of it — these SDKs
    // use generated Java classes, not runtime descriptor parsing. 164 KB -> 15 KB.
    packaging {
        resources {
            excludes += [
                '**/*.proto',
                '**/*.textproto',
                'META-INF/*.version',
                'META-INF/*.kotlin_module',
                'META-INF/proguard/**',
                'META-INF/DEPENDENCIES',
                'META-INF/LICENSE*',
                'META-INF/NOTICE*',
                'DebugProbesKt.bin',
                'kotlin-tooling-metadata.json',
            ]
        }
    }

    // Signing properties live outside the repo so the keystore password is
    // never committed.
    //
    // Guarded, because Gradle evaluates this block for EVERY variant: without
    // the check a freshly scaffolded game cannot build even a debug APK until
    // its alias exists, which is exactly backwards. A release build with the
    // properties missing falls through to no signing config and Gradle says so,
    // which is the right failure and a legible one.
    signingConfigs {
        release {
            if (project.hasProperty('GAME_UPLOAD_STORE_FILE')) {
                storeFile file(GAME_UPLOAD_STORE_FILE)
                storePassword GAME_UPLOAD_STORE_PASSWORD
                keyAlias GAME_UPLOAD_KEY_ALIAS
                keyPassword GAME_UPLOAD_KEY_PASSWORD
            }
        }
    }

    buildTypes {
        release {
            if (project.hasProperty('GAME_UPLOAD_STORE_FILE')) {
                signingConfig signingConfigs.release
            }

            // The four lines this whole file exists for.
            minifyEnabled true
            shrinkResources true
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'),
                          'proguard-rules.pro'
        }
    }
}

dependencies {
    // Firebase version matters for more than features.
    //
    // firebase-auth 24.0.1 shipped a consumer ProGuard rule inside the AAR:
    //
    //     -keep class com.google.android.gms.internal.** { *; }
    //
    // Every Play Services internal — not just the auth ones. 9,304 classes
    // pinned unshrunk and unrenamed, by a dependency, in a file nobody writes
    // or thinks to look in. It was single-handedly why Play's app-optimisation
    // report scored this app at 28% WITH R8 already enabled.
    //
    // 24.2.0 narrowed that rule to the one proto base class it needed.
    //
    // The lesson generalises: a consumer ProGuard rule is a dependency's
    // ability to disable your optimisation, and nothing in your build tells you
    // it happened. If the numbers are worse than they should be, unzip the AARs
    // and grep for -keep.
    implementation platform('com.google.firebase:firebase-bom:34.18.0')
    implementation 'com.google.firebase:firebase-analytics'
    implementation 'com.google.firebase:firebase-crashlytics'
}

# R8 rules for a Capacitor release build.
#
# Most of what a Capacitor app links against ships its own consumer rules inside
# the AAR — Capacitor keeps @CapacitorPlugin classes, Firebase keeps its model
# classes, gRPC keeps its service loaders. What is left here is the handful of
# things R8 cannot see from the bytecode alone.

# MainActivity hands the WebView an anonymous @JavascriptInterface object.
# proguard-android-optimize.txt already keeps @JavascriptInterface members, but
# the rule is repeated because losing it is a silent, RELEASE-ONLY breakage:
# the bridge method just returns undefined and nothing throws.
-keepclassmembers class * {
    @android.webkit.JavascriptInterface <methods>;
}

# Capacitor instantiates plugin classes by name from the generated plugin list,
# so their no-arg constructors must survive even though nothing calls them.
-keep class com.getcapacitor.** { *; }
-keep class * extends com.getcapacitor.Plugin { *; }
-keepnames class * implements com.getcapacitor.Plugin

# Crashlytics needs line numbers and the original file name to symbolicate the
# stack traces it uploads. Without these, every release crash report is a list
# of one-letter method names with no line numbers.
-keepattributes SourceFile,LineNumberTable
-renamesourcefileattribute SourceFile

# Optional transports and annotations these SDKs reference but never load on
# Android. R8 writes the exact list you need into
# app/build/outputs/mapping/release/missing_rules.txt — copy from there rather
# than guessing.
-dontwarn org.conscrypt.**
-dontwarn org.bouncycastle.**
-dontwarn org.openjsse.**
-dontwarn javax.naming.**
-dontwarn com.google.errorprone.annotations.**
-dontwarn javax.annotation.**

# The Firebase authentication plugin compiles in a handler for EVERY provider it
# supports, including Facebook, whose SDK is not a dependency here. This is the
# error that fails the first R8 build:
#
#   ERROR: R8: Missing class com.facebook.CallbackManager$Factory
#     (referenced from: ...FacebookAuthProviderHandler...)
-dontwarn com.facebook.**

# Flatten every renamed class into the root package. Play's app-optimisation
# report checks for this ("Repackage classes"); the payoff is a smaller dex —
# each package name is a string in the pool, and 15k classes spread over
# hundreds of packages is a lot of strings nothing reads at runtime.
#
# Safe because R8 leaves anything a -keep rule names where it is, and
# -allowaccessmodification lets it widen package-private access when a class
# does move. Spelled out rather than relied on from full mode's defaults.
-allowaccessmodification
-repackageclasses ''

// Drop the Firebase JS SDK from a native (Capacitor) build.
//
// Nothing in a Capacitor build can reach the firebase/* web SDK, yet it was
// ~730 KB of the shipped bundle. Two separate paths pulled it in:
//
//  1. Services pick a provider at runtime — Capacitor.isNativePlatform()
//     chooses the native plugin, otherwise the web SDK — but import BOTH arms
//     statically, so the bundler emits both.
//
//  2. Every @capacitor-firebase plugin registers a browser fallback as
//         registerPlugin('X', { web: () => import('./web').then(...) })
//     registerPlugin only calls that on a browser, but it is still a static
//     import site, so each of those web.js files drags in its slice of the web
//     SDK. This is where the 525 KB Firestore chunk and the 168 KB Auth chunk
//     were coming from — not from app code at all.
//
// With VITE_NATIVE=1 both resolve to stubs that throw. Nothing calls them, and
// if something ever does the message says why rather than failing somewhere
// inside a tree-shaken Firebase.
//
// Main chunk 909 KB -> 433 KB, and the two large chunks disappear entirely.

/** Module ids whose web-only implementation is unreachable on a device. */
const WEB_ONLY_STUBS = {
  '@your-scope/analytics': ['createAnalytics'],
  // Add the service arms your own app imports statically. Keep the export
  // names accurate — a missing one is a build error, which is the good failure.
};

const PLUGIN_WEB_FALLBACK =
  /@capacitor-firebase[/\\]([a-z]+)[/\\]dist[/\\]esm[/\\]web\.js$/;

export const dropWebFirebase = () => ({
  name: 'drop-web-firebase',
  apply: 'build',
  enforce: 'pre',

  async resolveId(source, importer, options) {
    if (WEB_ONLY_STUBS[source]) return `\0web-only:${source}`;

    // Only './web' can be a plugin fallback, so resolve nothing else — this
    // hook runs for every import in the graph.
    if (!source.startsWith('./web')) return null;
    const resolved = await this.resolve(source, importer, { ...options, skipSelf: true });
    const plugin = resolved && PLUGIN_WEB_FALLBACK.exec(resolved.id);
    return plugin ? `\0web-only-plugin:${plugin[1]}` : null;
  },

  load(id) {
    if (id.startsWith('\0web-only:')) {
      const from = id.slice('\0web-only:'.length);
      return WEB_ONLY_STUBS[from]
        .map((name) => `export const ${name} = () => { throw new Error(${JSON.stringify(
          `${name} (${from}) is stubbed out of native builds — the Capacitor provider ` +
          'should have been chosen instead.',
        )}) }`)
        .join('\n');
    }

    if (id.startsWith('\0web-only-plugin:')) {
      const plugin = id.slice('\0web-only-plugin:'.length);
      // e.g. authentication -> FirebaseAuthenticationWeb, the name the plugin's
      // index.js constructs off the dynamic import.
      const cls = `Firebase${plugin[0].toUpperCase()}${plugin.slice(1)}Web`;
      return `export class ${cls} { constructor() { throw new Error(${JSON.stringify(
        `${cls} is stubbed out of native builds — registerPlugin should have used the ` +
        'native implementation.',
      )}) } }`;
    }

    return null;
  },

  /**
   * The part worth insisting on.
   *
   * A stub only helps while nothing re-imports the real thing. Assert on the
   * emitted chunks rather than trusting that the import graph stayed clean —
   * without this, the next dependency upgrade quietly puts 700 KB back and
   * nobody finds out.
   */
  generateBundle(_options, bundle) {
    const leaked = Object.entries(bundle)
      .filter(([, c]) => c.type === 'chunk' &&
        /@firebase\/(app|auth|firestore|analytics)\b/.test(c.code))
      .map(([name]) => name);

    if (leaked.length) {
      this.error(
        `VITE_NATIVE=1 but the Firebase JS SDK is still in ${leaked.join(', ')}. ` +
        'Something imports it outside the stubbed entry points.',
      );
    }
  },
});