Environment variables

Every key lives in .env at the repo root (gitignored). bun run setup generates .env.example with exactly the keys your selection needs, each with a # docs: link to the dashboard that issues it; copy it to .env and fill in what you use. bun run doctor flags the required ones that are still empty.

There are two kinds, and the prefix decides which:

• EXPO_PUBLIC_* keys are public. Metro inlines them into the JavaScript bundle, so anyone with the app can read them. Only publishable / anon / SDK keys belong here. They're typed in src/lib/env.ts as optional: a missing key makes its module show a "Configure X" state instead of crashing. Restart with bun run start -- -c after changing one.
• Keys without the prefix are server-only. They're read with process.env.X inside src/app/api/** and src/server/** (API routes, Pro with backend=api-routes) and never reach the bundle. Never rename one to EXPO_PUBLIC_. Build-time keys (APP_VARIANT, SENTRY_AUTH_TOKEN, …) work the same way: app.config.ts and config plugins read them while EAS builds, and the app never sees them.

TemplateCopy Anchor Link

Present in every tree, whatever you picked. The Free tier has no eas.json, so the per-profile values don't apply there.

EXPO_PUBLIC_API_URL on a physical iPhone must be https://, a LAN IP, localhost or *.local: App Transport Security blocks plain http:// to anything else, and src/lib/env.ts warns in dev when it sees one.

ModulesCopy Anchor Link

Only the modules you selected add keys. Every row below is a Pro module (auth, payments, analytics, crash, backend) except data/apollo, which Starter can pick too; the backend/api-routes rows, src/server/webhooks included, exist only in a Pro tree set up with backend=api-routes. Required means the module stays in its "Configure" state (and doctor fails) until the key is set.

Each module page under Features has the dashboard steps for its keys. The two example apps carry their own .env.example with the subset they use.

On EASCopy Anchor Link

Your .env is gitignored, so EAS never uploads it: a cloud build, eas update and an EAS Hosting deploy all run without it. A key that works locally but is missing in a TestFlight build almost always was never set on EAS.

Set each key in the EAS environment it's used in (development, preview, production). A build picks the environment from its profile: build.<profile>.environment in eas.json if you add one, otherwise production for store builds (the shipped production profile), development for dev-client builds (development) and preview for the rest:

bunx eas-cli env:set --environment production --name EXPO_PUBLIC_SUPABASE_URL --value https://xyz.supabase.co --visibility plaintext
bunx eas-cli env:set --environment production --name STRIPE_SECRET_KEY --value sk_live_xxx --visibility sensitive
bunx eas-cli env:list --environment production

env:set creates or updates a variable (the older env:create still works but is deprecated). --visibility takes three values:

• plaintext - visible on expo.dev, in EAS CLI and in logs. Fine for EXPO_PUBLIC_* keys: they end up in the bundle anyway.
• sensitive - masked in build and workflow logs, still readable in EAS CLI and on the dashboard behind a toggle. Use it for server keys your API routes read (STRIPE_*, BETTER_AUTH_*, CLERK_SECRET_KEY, WEBHOOK_SECRET): EAS Hosting can't deploy secret variables, only plaintext and sensitive ones. Also use it for SENTRY_AUTH_TOKEN if you upload source maps after eas update from your machine.
• secret - never readable outside EAS servers, not even by EAS CLI. Right for keys only an EAS build job needs (SENTRY_AUTH_TOKEN for native builds, an NPM_TOKEN). A secret isn't available while EAS CLI resolves app.config.ts on your machine, can't be pulled, and isn't used by eas update.

bunx eas-cli env:pull --environment development writes that environment's variables to .env.local (pass --path for another file); secret ones appear only as a commented-out ***** line. Expo loads .env.local on top of .env, so a pulled value wins over the one in .env. bun run doctor reads only .env, though, so it still lists pulled keys as missing; pull with --path .env (it asks before overwriting) if you want doctor to see them.

eas update needs --environment on SDK 55 and later - see Your first update. APP_VARIANT and EXPO_PUBLIC_APP_VARIANT are already set per profile in eas.json, so don't create them.

Your tree ships no CI workflows. If you add your own (see Expo's GitHub Actions guide), EAS needs an EXPO_TOKEN secret (expo.dev → Account settings → Access tokens); set EAS_PROJECT_ID there too if you'd rather not commit the id.