Multi-Environment Setup for React Native CLI

Switching between development, staging, and production backends should not require hand-editing .env files and rebuilding from scratch. This guide walks through a battle-tested setup for React Native CLI projects: separate environment files, native build variants, and yarn scripts that keep Metro and native builds in sync.

What you'll build

Each environment gets its own API URLs, feature flags, and home-screen label — from a single codebase.

The problem this solves

Without flavors or schemes, every environment switch means:

1. Manually editing .env
2. Rebuilding the native app
3. Hoping Metro picked up the same values

With this setup you can:

• Point each build at a different backend (dev / staging / prod)
• Show a distinct app name on the home screen (e.g. "MyApp Staging")
• Ship one codebase with separate store release configurations
• Run QA and production builds side by side (with optional bundle ID suffixes)

Architecture overview

┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  .env file  │────▶│  react-native-   │────▶│  src/config/    │
│  (per env)  │     │  config          │     │  env.ts         │
└─────────────┘     └──────────────────┘     └─────────────────┘
       │                     │
       ▼                     ▼
┌─────────────┐     ┌──────────────────┐
│ Metro       │     │ Native build     │
│ (JS bundle) │     │ (Android/iOS)    │
└─────────────┘     └──────────────────┘

Golden rule: Metro and the native app must load the same environment file.

Quick start

1. Create environment files

Add these to your project root. They are gitignored — never commit secrets.

Example .env:

APP_ENV=development
API_URL=https://api-dev.example.com/
SOCKET_URL=https://api-dev.example.com/chat

# Analytics, payments, etc.
SENTRY_DSN=
POSTHOG_API_KEY=

Important: Environment values are baked in at build time, not read live. After changing any .env file, rebuild the native app.

2. Run with matching scripts

Open two terminals and pick one environment:

Building blocks

Read values in code

Prefer typed helpers in src/config/env.ts:

import { getApiBaseUrl, getAppEnv } from '@/config/env';

const baseUrl = getApiBaseUrl();
const env = getAppEnv(); // 'development' | 'staging' | 'production'

Add new keys to src/types/react-native-config.d.ts for TypeScript support.

Android setup

Android uses product flavors in android/app/build.gradle.

Step 1 — Map variants to env files

Add before dotenv.gradle is applied:

project.ext.envConfigFiles = [
  devDebug:       ".env",
  devRelease:     ".env",
  stagingDebug:   ".env.staging",
  stagingRelease: ".env.staging",
  prodDebug:      ".env.production",
  prodRelease:    ".env.production",
]

apply from: project(':react-native-config').projectDir.getPath() + "/dotenv.gradle"

Step 2 — Define flavors

flavorDimensions "env"

productFlavors {
  dev {
    dimension "env"
    versionNameSuffix "-dev"
    resValue "string", "app_name", "MyApp Dev"
  }
  staging {
    dimension "env"
    versionNameSuffix "-staging"
    resValue "string", "app_name", "MyApp Staging"
  }
  prod {
    dimension "env"
    resValue "string", "app_name", "MyApp"
  }
}

app_name is referenced by AndroidManifest.xml via android:label="@string/app_name".

Step 3 — Enable Metro for debug flavors

Inside the react { } block:

debuggableVariants = ["devDebug", "stagingDebug", "prodDebug"]

Skip this and Metro won't attach to flavored debug builds.

Step 4 — Add run scripts

"android:dev":     "ENVFILE=.env react-native run-android --mode=devDebug",
"android:staging": "ENVFILE=.env.staging react-native run-android --mode=stagingDebug",
"android:prod":    "ENVFILE=.env.production react-native run-android --mode=prodDebug"

Variant names are camelCase: devDebug, not dev-debug.

Android build variants

A variant = flavor + build type:

flavor   +  build type  =  variant
dev      +  debug        =  devDebug
staging  +  debug        =  stagingDebug
prod     +  release      =  prodRelease   ← Play Store

Store releases

yarn android:prod:release   # APK  → android/app/build/outputs/apk/prod/release/
yarn android:prod:aab       # AAB  → android/app/build/outputs/bundle/prodRelease/

iOS setup

iOS uses Xcode schemes. Each scheme runs a script before build to pick the right .env file.

Step 1 — xcconfig files

Create ios/Config/Debug.xcconfig and Release.xcconfig:

#include "../Pods/Target Support Files/Pods-<YourApp>/Pods-<YourApp>.debug.xcconfig"
#include? "../tmp.xcconfig"

tmp.xcconfig is generated at build time — do not commit it. Point your app target's Debug / Release configurations to these files in Xcode.

Step 2 — Environment script

ios/scripts/set-env-file.sh runs before each build. It:

1. Tells react-native-config which .env file to use
2. Generates ios/tmp.xcconfig with env variables
3. Sets the app display name on the home screen

Step 3 — Create one scheme per environment

Xcode → Product → Scheme → Edit Scheme → Build → Pre-actions → +

Check "Provide build settings from" → select your app target. Save schemes under xcshareddata/xcschemes/ so they are committed to git.

Step 4 — Add run scripts

"ios:dev":     "ENVFILE=.env react-native run-ios --scheme App-Dev",
"ios:staging": "ENVFILE=.env.staging react-native run-ios --scheme App-Staging",
"ios:prod":    "ENVFILE=.env.production react-native run-ios --scheme App-Prod --mode Release"

App Store / TestFlight

1. Open ios/<YourApp>.xcworkspace in Xcode
2. Select the production scheme
3. Product → Archive

Complete script reference

android:prod and ios:prod are for testing production config locally — not for store submission.

Adding a new environment (e.g. QA)

Install multiple environments side by side

By default, all flavors share one bundle ID — only one can be installed at a time.

To install dev + staging together:

• Android: add applicationIdSuffix ".dev" (etc.) per flavor
• iOS: use different PRODUCT_BUNDLE_IDENTIFIER per scheme

Troubleshooting

Project file map

Closing thoughts

Multi-environment setups pay off the first time QA needs staging while you keep developing locally. The upfront Gradle and Xcode configuration is tedious, but the daily workflow becomes as simple as picking the right yarn script pair.

If you're shipping React Native to production, this pattern scales cleanly — from two developers to CI pipelines that archive the correct scheme per branch.