Alright, let’s talk about something that trips up almost every React Native developer at some point: managing environment variables. It seems simple enough, right? You’ve got your API keys, your backend endpoints, maybe some feature flags – all things you don’t want hardcoded into your codebase, especially not in a way that’s visible to the world. This is where the concept of React Native environment variables becomes critical.

If you’ve ever found yourself copy-pasting credentials between different branches, or worse, accidentally committing sensitive keys to a public repository, you know the pain. We’ve all been there. In this post, we’re going to dive deep into a robust solution that’s become my personal go-to: react-native-config. We’ll cover the setup, the common gotchas, and how to make it work seamlessly across your development and production workflows. This isn’t about fancy new libraries; it’s about solid, practical engineering that saves you headaches.

Introduction: The Ubiquitous Problem of React Native Environment Variables

As your React Native application grows, so does its need for external configuration. Think about it:

• API Endpoints: Your development backend URL is likely different from your staging or production server.
• API Keys & Secrets: You definitely don’t want your production API keys scattered across your source code.
• Third-Party Service Keys: Analytics, push notifications, payment gateways – they all have keys that need managing.
• Feature Flags: Rolling out new features gradually often relies on configuration flags.

Traditionally, you might resort to simple file replacements, or worse, just updating strings directly. But this is brittle, error-prone, and doesn’t scale well. Imagine a team of developers, each needing to manage their own set of credentials or endpoints. It quickly becomes a mess. The real problem is that React Native’s build process needs to inject these values at *build time*, not runtime, especially for native code aspects and for ensuring secrets aren’t exposed in the JS bundle if you’re trying to keep them truly native.

The goal is to have a way to tell the *build process* “use this API key for production” and “use that API key for development,” without ever touching the source code files themselves after the initial setup. This is the core challenge that react-native-config aims to solve.

Why react-native-config is Your Go-To Solution

When you search for solutions to React Native environment variables, you’ll find a few approaches. Some might suggest custom scripts, others might involve complex native configurations. However, react-native-config, maintained by Wix, has emerged as the de facto standard for a reason. It elegantly bridges the gap between your JavaScript code and the native build environments (iOS and Android).

Here’s why it’s so effective:

• Native Integration: It injects variables directly into the native build configuration (Info.plist for iOS, build.gradle for Android). This means variables are available to your native modules and can be accessed reliably from your JavaScript code.
• Environment Specific Files: It supports multiple configuration files (e.g., .env, .env.staging, .env.production), making it straightforward to switch between different settings.
• Cross-Platform: It works for both iOS and Android with minimal fuss.
• Well-Maintained and Popular: Being a widely adopted library means a large community, plenty of resources, and ongoing support.

It’s not just about dumping variables; it’s about a structured way to manage them that integrates deeply with the build process. This is crucial for security and maintainability.

Setting Up react-native-config: The Basics

Let’s get our hands dirty. The installation is straightforward:

npm install react-native-config --save

or

yarn add react-native-config

After installation, you need to link it. For React Native 0.60 and above, auto-linking usually handles this. However, for older versions or if you run into issues, you might need:

npx react-native link react-native-config

The next critical step is creating your environment files. In the root of your project, create a file named .env. This will be your default environment configuration.

# .env

API_URL=http://localhost:3000/api

APP_ENV=development

SOME_API_KEY=abcdef123456

Now, you need to tell react-native-config to use this file during the build. This is done by adding a small configuration to your native build files.

For iOS:

In your ios/YourApp/Info.plist, add this line:

<key>UIBackgroundModes</key>
<array>
<string>remote-notification</string>
</array>

Wait, that’s not right. That’s for background modes. The actual configuration for react-native-config is to add a Gradle property that points to the environment file. This is usually handled by a Babel plugin, but let’s look at the native side.

Actually, the most common and recommended way is to use a Babel plugin. Let’s correct that.

You need to install the Babel plugin:

npm install --save-dev babel-plugin-module-resolver babel-plugin-react-native-config

Then, in your babel.config.js, add it to your plugins:

module.exports = {
presets: ['module:metro-react-native-babel-preset'],
plugins: [
['module-resolver', {
root: ['./'],
extensions: ['.ios.js', '.android.js', '.js', '.json'],
}],
'react-native-reanimated/plugin', // Keep this if you use reanimated
['module-alias', { adjustments: [...] }], // If you have other alias plugins
'react-native-config',
],
};

Once this is set up, you can access your variables in your JavaScript code like this:

import Config from 'react-native-config';

console.log(Config.API_URL); // Output: http://localhost:3000/api

console.log(Config.SOME_API_KEY); // Output: abcdef123456

This seems almost too simple, right? But the magic happens because the Babel plugin intercepts imports of react-native-config and substitutes the actual values from your `.env` file *during the Metro bundler’s compilation process*. This is key. It’s not a runtime import that fetches a file; it’s a build-time substitution.

For iOS: The plugin generates an `xcconfig` file that your Xcode build uses. You don’t typically touch this manually after setup.

For Android: The plugin adds configuration to your android/app/build.gradle to read the `.env` file and inject variables into the build.

The official documentation is an excellent resource for the most up-to-date installation steps:

React Native Config GitHub Repository

Common Pitfalls and How to Avoid Them

This is where the real-world experience comes in. While setup is easy, several things can go wrong, especially when you start dealing with multiple environments or team collaboration.

1. Forgetting to Rebuild/Rerun After `.env` Changes

This is by far the most common mistake. Because the variables are injected at *build time*, simply changing a value in your .env file and then running npx react-native start (or yarn start) is often not enough. Metro might not pick up the changes because the Babel plugin processed the file during the initial bundle creation.

What to do:

• Always stop and restart your Metro bundler. (Ctrl+C and then run npx react-native run-android or npx react-native run-ios).
• For native changes (less common with this setup, but good to remember): Sometimes you need a full native rebuild.

# For Android
cd android && ./gradlew clean && cd .. && npx react-native run-android

# For iOS
cd ios && xcodebuild -workspace YourApp.xcworkspace -scheme YourApp -configuration Debug clean && cd .. && npx react-native run-ios

When in doubt, a clean build usually fixes it. Don’t waste hours debugging; just rebuild.

2. Committing Sensitive Keys

Your .env file should never be committed to your version control system if it contains secrets (like API keys). This is paramount for security.

What to do:

• Add .env to your .gitignore file. This is non-negotiable.

# .gitignore
# ... other ignores
.env

• Use a .env.example file. Create a file named .env.example with placeholder values or dummy data. This file *should* be committed. It serves as a template for new developers joining the team.

# .env.example

API_URL=https://example.com/api

APP_ENV=development

SOME_API_KEY=YOUR_TEST_API_KEY_HERE

When a new developer clones the repo, they’ll see .env.example, know what variables they need, and create their own .env file locally, filling it with their specific credentials.

3. Incorrect Variable Naming

react-native-config expects environment variables to be prefixed with REACT_NATIVE_ when defining them in your native build files (like android/app/build.gradle or iOS’s `xcconfig`). However, the Babel plugin simplifies this: you can define them directly in your .env file without the prefix, and they will be available.

Correction based on current best practices and typical usage: While the plugin handles much of this abstraction, the *most robust* way, and the way that guarantees availability in native code if you were to extend it, is to prefix them with REACT_NATIVE_ in your .env files for clarity and future-proofing. The Babel plugin will expose these prefixed variables. Let’s stick to that for consistency.

So, your .env file should ideally look like:

# .env

REACT_NATIVE_API_URL=http://localhost:3000/api

REACT_NATIVE_APP_ENV=development

REACT_NATIVE_SOME_API_KEY=abcdef123456

And in your code:

import Config from 'react-native-config';

console.log(Config.REACT_NATIVE_API_URL);

This prefixing is crucial for avoiding naming collisions with system environment variables and ensuring clarity.

4. Typos and Case Sensitivity

JavaScript is case-sensitive, and so are environment variables. A simple typo like API_URL vs API_URLS can lead to a nightmare of debugging. Always double-check your variable names in both the .env file and where you import/use them.

5. Not Handling Missing Variables

What happens if a crucial variable is missing? Your app might crash or behave unexpectedly. You should always have fallbacks or clear error handling.

What to do:

• Provide defaults in your JS code (use with caution):

const apiUrl = Config.REACT_NATIVE_API_URL || 'https://default.api.com';

This is okay for non-critical, non-secret variables, but for API keys or critical endpoints, you probably want to fail fast if they’re not set.

• Validate at startup:

import Config from 'react-native-config';

if (!Config.REACT_NATIVE_API_KEY) {
console.error('FATAL ERROR: REACT_NATIVE_API_KEY is not set!');
// Potentially crash the app or show a user-friendly error screen
// For example, using 'sentry-expo' or a custom error boundary
// throw new Error('API Key not configured.');
}

Handling Different Environments (Dev, Staging, Prod)

This is where react-native-config truly shines. You can manage distinct configurations for various stages of your application lifecycle.

Create separate .env files:

• .env: For development (often used by default)
• .env.staging: For your staging environment
• .env.production: For your production environment

To specify which environment file to use during a build, you pass an environment variable to the build command:

For Android:

# To use .env.staging

cd android
APP_ENV=staging ./gradlew assembleRelease
cd ..

# To use .env.production

cd android
APP_ENV=production ./gradlew assembleRelease
cd ..

Then, in your android/app/build.gradle, you’d typically have logic like this:

def env = System.getenv("APP_ENV") ?: "development"
def propertiesFile = "dotenv-${env}.gradle"
apply from: propertiesFile

And create files like android/dotenv-staging.gradle, android/dotenv-production.gradle that load the respective .env.staging or .env.production files. The react-native-config setup often automates much of this by looking for these files based on the APP_ENV variable.

For iOS:

This is often handled by creating different Xcode build configurations (e.g., `Debug`, `Release`, `Staging`, `Production`) and associating different `.xcconfig` files with them. The `react-native-config` Babel plugin helps in generating these.

You’ll typically run your app for a specific environment like this:

# To use .env.staging (assuming your Xcode config is set up for staging)

APP_ENV=staging npx react-native run-ios

or more explicitly by setting the build configuration:

APP_ENV=staging react-native run-ios --configuration Staging

The key is that the `APP_ENV` variable (or equivalent) tells the build system which set of variables to inject. For the Babel plugin to pick up these environment-specific files, you usually need to set the `APP_ENV` variable during the build process itself.

Example usage in your JS code:

import Config from 'react-native-config';

const getApiBaseUrl = () => {
switch (Config.REACT_NATIVE_APP_ENV) {
case 'staging':
return 'https://staging.api.example.com/api';
case 'production':
return 'https://prod.api.example.com/api';
default: // development
return 'http://localhost:3000/api';
}
};

const API_URL = getApiBaseUrl();

This approach ensures that when you build your app for staging, it points to staging APIs, and when you build for production, it uses production endpoints, all without code changes.

Advanced Scenarios and Best Practices

1. Using Different Bundle Identifiers/App Names per Environment

It’s incredibly useful to have distinct app icons, names, and bundle identifiers for different environments. This helps you avoid confusion (e.g., installing the staging app alongside the production app on your device).

react-native-config can help with this by allowing you to define these in your environment files:

# .env.staging

REACT_NATIVE_APP_NAME=MyApp (Staging)
REACT_NATIVE_BUNDLE_ID=com.yourcompany.myapp.staging

# .env.production

REACT_NATIVE_APP_NAME=MyApp
REACT_NATIVE_BUNDLE_ID=com.yourcompany.myapp

Then, you’ll need to configure your native projects to read these variables. For Android, this is often done in android/app/build.gradle.

For iOS, you’d typically use these variables to dynamically set values in your Info.plist or in your Xcode build settings. This requires some native configuration, but react-native-config provides the variables, and you hook them into your native build scripts.

2. Managing Secrets Securely (Beyond `.env` Files)

While .env files are great for development and staging, committing them directly to version control, even for staging, can be risky. For production secrets, you should never store them directly in your repository.

What to do for Production Secrets:

• CI/CD Secrets Management: Your CI/CD pipeline (e.g., GitHub Actions, GitLab CI, Jenkins) should have secure ways to store secrets. When building your production app, the CI/CD system injects these secrets as environment variables into the build process.
• Use a dedicated secrets management service: Services like AWS Secrets Manager, Google Cloud Secret Manager, or HashiCorp Vault can store your sensitive credentials. Your build process or backend can fetch these securely.

For example, in a CI environment, you might set `REACT_NATIVE_API_KEY` as a secret in your CI provider’s settings, and the build command would implicitly pick it up.

# Example in GitHub Actions workflow (.yml)

- name: Build Android Release
env:`

REACT_NATIVE_API_KEY: ${{ secrets.PROD_API_KEY }}`

run: cd android && ./gradlew assembleRelease && cd ..`

This is the most secure way to handle production credentials. Your JavaScript code then accesses `Config.REACT_NATIVE_API_KEY` just as it would any other variable, but the value comes from a secure source during the build.

3. Performance Considerations

react-native-config injects variables at build time. This means there’s no runtime performance penalty. The variables are effectively compiled into your JavaScript bundle (or made available to native modules). So, no, it won’t slow down your app.

4. Testing with Environment Variables

When writing unit or integration tests, you’ll need to mock react-native-config or provide a mock implementation. Jest, for example, allows you to mock modules easily.

// __mocks__/react-native-config.js

export default {

REACT_NATIVE_API_URL: 'http://localhost:8081/mock-api',

// Add other mock variables as needed

};

Then, in your test files, you can import from react-native-config, and Jest will automatically use your mock.

Debugging Tips and Tricks

1. Check the Native Build Logs

If variables aren’t showing up, especially for Android, dive into the Gradle output. It often reveals if the dotenv file was found or if there were parsing errors.

For iOS, check the Xcode build logs. The Babel plugin should generate output indicating it’s processing the `.env` file.

2. Verify Babel Configuration

Ensure the babel-plugin-react-native-config is correctly listed in your babel.config.js and that it’s not being overridden or excluded by other configurations.

3. `console.log` During Development Build

While running your app in development mode (npx react-native run-android or run-ios), you can use console.log(Config.YOUR_VARIABLE) to see the values being injected. Remember, for release builds, you’d need to build using the appropriate commands (e.g., `./gradlew assembleRelease` for Android).

4. Inspecting Native Code (Advanced)

If you suspect variables aren’t reaching native modules:

• Android: Check your android/app/build.gradle and any generated .gradle files. Variables are often injected as BuildConfig.VAR_NAME fields.
• iOS: Inspect the generated `.xcconfig` files. Variables are often accessible via `process.env.VAR_NAME` in scripts or sometimes exposed as constants in native code.

However, for most use cases, accessing via Config.VARIABLE_NAME in JavaScript is sufficient and the intended pattern.

Conclusion: Confident Environment Management

Mastering React Native environment variables with react-native-config is a fundamental skill for building robust, scalable, and secure mobile applications. It moves sensitive information out of your source code and into a managed configuration system that integrates seamlessly with your build pipelines.

By understanding the setup, anticipating common pitfalls like forgetting to rebuild, and implementing best practices for security (especially for production secrets), you can save yourself countless hours of debugging and avoid costly mistakes. Embrace the `.env.example` workflow, leverage CI/CD secrets, and always double-check your variable names. Your future self, and your teammates, will thank you.

It’s not just about making variables accessible; it’s about having a reliable, repeatable process for configuring your app across different environments. react-native-config provides that structure, allowing you to focus on building great features instead of wrestling with configuration.