Expo

Expo & EAS: shipping React Native

Hand-off — the app vs its motion. This skill owns the Expo platform: router, config plugins, EAS, native modules, store builds. Animation and gestures — Reanimated worklets, the UI runtime, sheets, screen transitions, press feedback, haptics, motion that stutters on a real device — are ../motion-craft/SKILL.md's.

What this skill owns

Expo is the toolchain and EAS cloud platform layered on React Native: cloud builds, store submission, over-the-air JS updates, and native configuration declared in JavaScript instead of hand-edited Xcode/Gradle projects. This skill owns the shipping pipeline and native-config-via-JS.

The verb rule of thumb: if the verb is build / submit / update / prebuild / plugin / EAS / channel / runtime-version, you are in expo. If it is render / navigate / animate / bridge / write a native module, route to react-native. Other exits: web React/hooks/state → react, a Dart app → flutter, native-only Swift/Kotlin → swift-ios/kotlin-android, a desktop wrapper → tauri/electron, CI unrelated to EAS → github-actions.

Current stable as of 2026-06-02: Expo SDK 55 — React Native 0.83.1, React 19.2.0, shipped 2026-02-25. SDK 56 is in beta (beta opened 2026-05-06, ~2-week window; RN 0.85.2, React 19.2.3) — upcoming, not yet shipped stable. Both run exclusively on the New Architecture; the Legacy Architecture was removed in SDK 55.

Decision rules

The shipping pipeline (core)

Four EAS verbs, in this order: prebuild → build → submit → update.

npx expo prebuild --clean      # regenerate native dirs from app config + plugins (CNG)
eas build -p ios --profile production       # cloud-build the binary (.ipa/.aab)
eas submit -p ios --profile production      # upload to App Store / Play Store
eas update --branch production --message "fix typo"   # ship JS-only over the air

prebuild is only needed for managed/CNG apps and runs automatically inside eas build; run it locally to inspect or to verify a plugin. Build/submit ship a new binary; update ships JS only — anything touching native code needs a new build.

Minimal eas.json with the three default profiles plus channels. Each build is stamped with a channel; a channel maps to a same-named EAS Update branch by default (SDK 55 stable builders: RN 0.83.1, Xcode 26 on iOS, Android 16 target):

{
  "cli": { "version": ">= 16.0.0" },
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "channel": "development"
    },
    "preview": {
      "distribution": "internal",
      "channel": "preview"
    },
    "production": {
      "channel": "production",
      "autoIncrement": true
    }
  },
  "submit": {
    "production": {}
  }
}

Run scripts/verify.sh inside an Expo project to gate eas.json, the runtime policy, committed secrets, and New-Arch readiness.

EAS Update mental model

Runtime version is the compatibility gate. An update applies to a build only when BOTH the platform AND the runtimeVersion match exactly — there is no "close enough". The chain is: build stamped with a channel → channel points at a branch → you publish updates to a branch. Updates flow only down a matching runtime within the linked branch.

The #1 footgun: a hardcoded runtimeVersion that drifts from the binary, so the update silently never installs and you stare at unchanged devices.

// BAD — hardcoded string in app.json; bump a native dep and every old build
// silently stops matching, so your "shipped" OTA never reaches users.
{ "expo": { "runtimeVersion": "1.0.0" } }

// GOOD — fingerprint policy: EAS hashes the native runtime and auto-bumps the
// runtime version whenever native code/config changes, so updates only ever
// reach binaries that can actually run them.
{ "expo": { "runtimeVersion": { "policy": "fingerprint" } } }

Inspect, branch ops, rollouts/rollbacks, republish, and the full "update not applying" decision flow → references/eas-update.md.

Config plugins / CNG

Never hand-edit ios/ or android/ — they are ephemeral, regenerated by npx expo prebuild --clean from app.config + plugins + autolinking. To change native config, write a config plugin (a function in the plugins array) or use a mod like withInfoPlist / withAndroidManifest.

// app.plugin.ts — add an iOS Info.plist key during prebuild, the CNG way.
import { ConfigPlugin, withInfoPlist } from "expo/config-plugins";

const withCameraUsage: ConfigPlugin<{ reason: string }> = (config, { reason }) =>
  withInfoPlist(config, (cfg) => {
    cfg.modResults.NSCameraUsageDescription = reason;
    return cfg;
  });

export default withCameraUsage;

// app.config.ts — dynamic config; reference the plugin with its options.
export default {
  expo: {
    name: "MyApp",
    runtimeVersion: { policy: "fingerprint" },
    plugins: [["./app.plugin.ts", { reason: "Scan receipts" }]],
  },
};

Plugin anatomy, dangerous mods, mod ordering, and prebuild troubleshooting → references/config-plugins.md.

New Architecture & SDK upgrade

The Legacy Architecture is gone. SDK 54 was the last release to ship it; SDK 55 (2026-02-25, current stable) removed it entirely, and the SDK 56 beta builds on that. On any supported SDK you are already on the New Architecture — it is always enabled and cannot be turned off. The newArchEnabled flag was deleted from app.json in SDK 55; if you still carry one, it is dead config — remove it. There is no legacy fallback to lean on, so a dependency that only works on the old architecture is now a hard blocker, not a "flip the flag back" escape hatch.

Upgrade checklist:

1. npx expo install expo@latest --fix — bump SDK and align every dependency.
2. npx expo-doctor@latest — catch deps that never made the New-Arch jump before you build.
3. npx expo prebuild --clean — regenerate native dirs (managed/CNG apps).
4. Build a development/preview binary on a device before promoting to production.

Two upgrade tripwires: every Android app is edge-to-edge (on since SDK 54, non-negotiable) — audit manual inset/status-bar code. And SDK 55+ ships Hermes bytecode diffing for EAS Update (~75% smaller OTA downloads) automatically; you get it for free once both the build and the update are on SDK 55+.

Credentials & secrets

• Let EAS manage credentials (signing keys, provisioning profiles) by default — it stores and rotates them server-side so they never touch the repo.
• Supply per-profile config through EAS environment variables / .env files scoped by profile, not committed plaintext.
• Never commit a keystore (*.jks/*.keystore), *.p12, or *.mobileprovision, and never put API keys in app.config/app.json — anything in app config ships inside the public bundle. See ../secure-coding/SKILL.md.

EAS Workflows

EAS Workflows are Expo's own CI: YAML in .eas/workflows/. Jobs use pre-packaged types (build, submit, update) and chain via needs: + outputs. Route to the github-actions skill only when the user explicitly wants GH Actions or non-Expo CI.

# .eas/workflows/release-android.yml — build then submit, chained by needs.
name: Release Android
on:
  push:
    branches: [main]
jobs:
  build:
    type: build
    params:
      platform: android
      profile: production
  submit:
    needs: [build]
    type: submit
    params:
      platform: android
      build_id: ${{ needs.build.outputs.build_id }}

Plan limits (set expectations)

EAS Free: 15 Android + 15 iOS builds/month on the low-priority queue only (peak waits can exceed an hour). High-priority queue needs a paid plan; the Production plan includes 2 build concurrencies, with extra concurrency at $50/concurrency/month, up to 5 extra. If a user complains about build queue waits, the fix is usually the plan, not the config. (Pricing per expo.dev/pricing, verified 2026-06-02; re-check before quoting — Expo adjusts tiers and dollar figures.)

Anti-patterns

Project grounding (02-DOCS + CLAUDE.md)

In a project with a 02-DOCS/ layer (the harness wiki), read 02-DOCS/wiki/stack/expo.md first and record this app's shipping decisions there — managed-vs-bare, runtime-version policy, channel/branch map, SDK/New-Arch status — linked from the root CLAUDE.md ## Knowledge map, bumping its Updated date when a convention changes. No 02-DOCS/? Skip silently. Conventions are recorded, not gated — never block the task on this.