Environments & EAS Environment Variables

Separate dev, staging, and production configuration without committing secrets - using local .env files for development and EAS environment variables for cloud builds, updates, and workflows.

Recipe

Quick-reference recipe card - copy-paste ready.

// eas.json - wire each build profile to an EAS environment
{
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "environment": "development"
    },
    "preview": {
      "distribution": "internal",
      "environment": "preview"
    },
    "production": {
      "distribution": "store",
      "environment": "production"
    }
  }
}

# Create cloud variables (repeat per environment)
eas env:create --name EXPO_PUBLIC_API_URL \
  --value https://api.staging.example.com \
  --environment preview \
  --visibility plaintext
 
# Pull preview vars locally (writes .env.local - keep gitignored)
eas env:pull --environment preview
 
# Publish an OTA update using the same environment as the build
eas update --environment production --message "Hotfix auth redirect"

// src/config.ts - only EXPO_PUBLIC_ vars are inlined into the bundle
export const config = {
  apiUrl: process.env.EXPO_PUBLIC_API_URL ?? "http://localhost:3000",
  appEnv: process.env.EXPO_PUBLIC_APP_ENV ?? "development",
} as const;

When to reach for this:

• You ship multiple app variants (dev client, internal QA, App Store) that need different API endpoints or bundle identifiers.
• Your team runs EAS Build or EAS Update and cannot rely on uncommitted local .env files on remote runners.
• You need role-based visibility - plaintext for public config, sensitive for obfuscated logs, secret for NPM tokens and signing keys.
• You want one source of truth so a preview build and a preview OTA update resolve the same EXPO_PUBLIC_* values.

Working Example

// app.config.ts - branch native config per environment without hardcoding secrets
import type { ExpoConfig } from "expo/config";
 
const APP_ENV = process.env.EXPO_PUBLIC_APP_ENV ?? "development";
 
const bundleIds: Record<string, string> = {
  development: "com.example.myapp.dev",
  preview: "com.example.myapp.staging",
  production: "com.example.myapp",
};
 
const apiUrls: Record<string, string> = {
  development: "http://localhost:3000",
  preview: "https://api.staging.example.com",
  production: "https://api.example.com",
};
 
const config: ExpoConfig = {
  name: APP_ENV === "production" ? "My App" : `My App (${APP_ENV})`,
  slug: "my-app",
  version: "1.0.0",
  ios: {
    bundleIdentifier: bundleIds[APP_ENV] ?? bundleIds.development,
  },
  android: {
    package: bundleIds[APP_ENV] ?? bundleIds.development,
  },
  extra: {
    appEnv: APP_ENV,
    apiUrl: process.env.EXPO_PUBLIC_API_URL ?? apiUrls[APP_ENV],
    eas: {
      projectId: "00000000-0000-0000-0000-000000000000",
    },
  },
};
 
export default config;

// App.tsx - read runtime config from inlined public vars and app.config extra
import Constants from "expo-constants";
import { StyleSheet, Text, View } from "react-native";
 
export default function App() {
  const apiUrl =
    process.env.EXPO_PUBLIC_API_URL ??
    (Constants.expoConfig?.extra?.apiUrl as string | undefined) ??
    "not configured";
 
  const appEnv =
    process.env.EXPO_PUBLIC_APP_ENV ??
    (Constants.expoConfig?.extra?.appEnv as string | undefined) ??
    "unknown";
 
  return (
    <View style={styles.container}>
      <Text style={styles.title}>Environment: {appEnv}</Text>
      <Text style={styles.body}>API: {apiUrl}</Text>
      <Text style={styles.hint}>
        EAS builds inject EXPO_PUBLIC_* at bundle time. Secrets never appear here.
      </Text>
    </View>
  );
}
 
const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: "center", padding: 24, gap: 8 },
  title: { fontSize: 20, fontWeight: "700" },
  body: { fontSize: 15, color: "#374151" },
  hint: { fontSize: 13, color: "#6b7280", marginTop: 12 },
});

# .gitignore - never commit local overrides or pulled secrets
.env*.local

What this demonstrates:

• Mapping EAS environments (development, preview, production) to eas.json build profiles.
• Using EXPO_PUBLIC_* for client-safe values that Metro inlines at bundle time.
• Keeping bundle identifiers and display names environment-specific via app.config.ts.
• Separating build-time secrets (NPM tokens, signing keys) from anything referenced in JavaScript.

Deep Dive

How It Works

• Local development: Expo CLI loads .env, .env.local, and other standard dotenv files. Variables prefixed with EXPO_PUBLIC_ are statically replaced in your source during bundling.
• EAS Build: When environment is set on a build profile, EAS injects that environment's variables into the build worker. Plaintext and sensitive variables are available when resolving app.config.ts; secret variables are available only on the server during the job.
• EAS Update (SDK 55+): eas update --environment <name> is required. Only variables from that EAS environment are used - local .env files are ignored, keeping OTA bundles aligned with store builds.
• Scope: Variables can be project-wide (one app) or account-wide (shared across apps in an organization).

EAS Environment Mapping

Explicit environment fields are recommended - auto-detection is convenient but easy to misconfigure when profiles share similar flags.

Visibility Settings

Anything embedded in client JavaScript is extractable from the compiled app. Use secrets for NPM_TOKEN, SENTRY_AUTH_TOKEN, and similar build-time values - not for "private" API keys shipped to users.

Built-in EAS Build Variables

These are set automatically on EAS Build workers (not part of your project environments):

Use EAS_BUILD_PROFILE in app.config.ts when you need profile-specific logic beyond the three standard environments.

TypeScript Notes

// env.d.ts - document expected public variables for the team
declare namespace NodeJS {
  interface ProcessEnv {
    EXPO_PUBLIC_API_URL: string;
    EXPO_PUBLIC_APP_ENV: "development" | "preview" | "production";
  }
}
 
// Static access only - Metro will NOT inline bracket notation or destructuring
const url = process.env.EXPO_PUBLIC_API_URL; // ✓ inlined
// const url = process.env["EXPO_PUBLIC_API_URL"]; // ✗ not inlined

Gotchas

• Putting API secrets in EXPO_PUBLIC_* - Any value inlined into JavaScript is visible in the app binary. Fix: Keep secrets server-side; use short-lived tokens from your backend.
• Omitting --environment on eas update (SDK 55+) - Updates may not match the variables used in your production build. Fix: Always pass --environment matching the target build profile.
• Using NODE_ENV to switch .env files - npx expo export forces NODE_ENV=production, so test/staging files won't load as expected. Fix: Use eas env:pull --environment <name> or explicit EXPO_PUBLIC_APP_ENV.
• Bracket notation for env vars - process.env['EXPO_PUBLIC_KEY'] is not statically analyzable and won't be inlined. Fix: Use dot notation: process.env.EXPO_PUBLIC_KEY.
• Assuming secrets are available in app.config.ts locally - Secret-type variables are unreadable outside EAS servers. Fix: Use sensitive/plaintext for values needed during local config resolution, or provide dev defaults.
• Committing .env.local after eas env:pull - Pulled files often contain staging/production values. Fix: Add .env*.local to .gitignore and use separate pull commands per developer machine.
• Mismatched environments across workflow jobs - A fingerprint job on production paired with a preview build causes wrong secrets. Fix: Set jobs.<id>.environment to match the build profile's environment in EAS Workflows.

Alternatives

FAQs

{
  "build": {
    "production": {
      "environment": "production"
    }
  }
}

eas env:pull --environment development

eas env:exec --environment production 'npx sentry-expo-upload-sourcemaps dist'

Related

• app.json & app.config.js - dynamic config, plugins, and multi-environment manifests
• Expo Platform Basics - APP_VARIANT branching and EAS project linking
• Expo Go vs Development Builds - development profile and dev-client setup
• Upgrading Expo SDK Versions - env var behavior changes across SDK bumps
• Expo Account, Projects & Permissions - org-scoped variables and role access
• Best Practices - secrets hygiene and long-term config governance

External Related Links

• docs.expo.dev - official Expo docs (recommended framework)
• reactnative.dev/docs/more-resources - curated further reading, tools, starter kits
• reactnative.dev - official React Native site

Stack versions: This page was written for React 19.2.3, React Native 0.86.0, and Expo SDK 57 (expo ~57.0.4).