Org Skills

Cold start and bundle size

Supporting material for react-native-performance. Agents load it on demand; it ships inside the skill folder.

RawSource

What actually costs seconds at launch, how to find it, and how to keep the download small. Open this when the complaint is "the app takes ages to open" or "the app/update is too big".

Sources: https://docs.expo.dev/guides/analyzing-bundles/ · https://docs.expo.dev/router/reference/async-routes/ · https://docs.expo.dev/versions/latest/sdk/splash-screen/ · https://expo.dev/changelog/sdk-55

1. What a cold start is made of

  1. Native process start, Application/AppDelegate setup, native module registration.
  2. Hermes loads the bytecode bundle — near-zero parse cost, which is why "shrink the bundle to start faster" is mostly wrong.
  3. Module evaluation: every top-level statement in every imported module runs. This is where the seconds are.
  4. First React render, first data, splash hidden.

So the target is step 3: analytics SDKs initialising, remote config fetching, i18n loading every locale, a store rehydrating, a database opening and migrating, a crypto polyfill.

2. Measure before touching anything

# Android, five runs, app force-stopped in between
adb shell am force-stop com.example.app
adb shell am start -W com.example.app/.MainActivity     # TotalTime is the number

iOS: Instruments → App Launch on a release build. In-app, mark module-scope start, splash hidden and first interactive (see profiling.md §6) and report the deltas from real users.

3. Find the module side effects

  • Search for work at module scope: new Client(...), .init(, configure(, i18n.use(...).init(, openDatabaseSync(, large literal arrays, require of a whole icon set.
  • Convert each to a lazy singleton:
let client: Analytics | null = null;
export function analytics() {
  client ??= new Analytics(KEY);      // created on first real use, not at import
  return client;
}
  • Defer anything not needed for the first screen until after the first interaction:
import { InteractionManager } from 'react-native';
useEffect(() => {
  const task = InteractionManager.runAfterInteractions(() => { void loadRemoteConfig(); });
  return () => task.cancel();
}, []);
  • Keep inlineRequires on in the Metro transformer (current templates enable it) so imported modules evaluate at first use rather than at bundle load.

4. What does not work on native

Expo Router async routes "do not support native production apps yet", and when bundling for production on native "all suspense boundaries will be disabled". There is no route-level code splitting in a native production bundle: it is one file. React.lazy around a screen therefore defers evaluation, not download, and only when the import is genuinely dynamic.

Say this plainly when a user asks to code-split native routes; then redirect the work to module side effects, image payloads and data fetching, which are where the seconds actually are.

5. The splash screen is part of the measurement

import * as SplashScreen from 'expo-splash-screen';
SplashScreen.preventAutoHideAsync();

export default function RootLayout() {
  const { ready } = useBootstrap();            // fonts, session, first query, migrations
  useEffect(() => { if (ready) void SplashScreen.hideAsync(); }, [ready]);
  if (!ready) return null;
  return <Stack />;
}

Hiding the splash before the first screen has data trades a measurable number for a worse experience: the user sees a spinner instead of a logo. Hide it once, when the first screen can actually be used — and make sure useBootstrap does not serialise work that could run in parallel.

6. Analysing the JavaScript bundle

EXPO_ATLAS=true npx expo export
npx expo-atlas .expo/atlas.jsonl

Or during development: EXPO_ATLAS=true npx expo start, then Shift + M → Expo Atlas.

Look for: a library imported whole (lodash, moment, an icon pack), duplicated copies of the same package, a locale bundle for every language, and anything server-only that leaked in. Fix by importing per function, swapping to Intl, loading locales on demand, and removing dependencies you no longer use.

Size and startup are related but not the same: a big bundle costs download and update time; module evaluation costs launch time. Measure both before choosing.

7. Binary and update size

  • Android: R8/Proguard on for release, ship an .aab, strip unused resource configurations.
  • iOS: no action needed for bitcode (removed from Xcode years ago); focus on assets.
  • Assets: compress to WebP, remove unused fonts and icon sets, download large media on demand instead of embedding it.
  • Updates: from SDK 55 EAS Update ships Hermes bytecode diffs, roughly a 75 % reduction in download time. Diffs work against a base — churning runtimeVersion or the native build between updates forfeits that benefit.
  • Every native library adds registration cost at launch. Before adding one, ask what it costs in both size and startup, and remove the ones nobody uses.

8. Checklist for a startup investigation

  • Five am start -W runs (or Instruments App Launch) recorded before any change
  • Module-scope side effects listed, each one either deferred or justified
  • Splash held until the first screen is usable, hidden exactly once
  • No claim of native route code splitting
  • Expo Atlas run and the three largest contributors named
  • Re-measured with the same procedure; the delta quoted per change