react-native-config

Config variables for React Native apps, supporting iOS, Android, macOS and Windows.

Expose config variables to your JavaScript code — bring some 12 factor love to your mobile apps!

Tip

Help keep this library maintained. If react-native-config is useful to you or your company, please consider sponsoring it on Open Collective. Contributions go toward the maintenance work that keeps it working across new React Native releases. See Sponsors for the tiers and what sponsorship pays for.

Basic Usage

Create a new file .env in the root of your React Native app:

API_URL=https://myapi.com
GOOGLE_MAPS_API_KEY=abcdefgh

Then access variables defined there from your app:

importConfigfrom"react-native-config";Config.API_URL;// 'https://myapi.com'Config.GOOGLE_MAPS_API_KEY;// 'abcdefgh'

Keep in mind this module doesn't obfuscate or encrypt secrets for packaging, so do not store sensitive keys in .env. It's basically impossible to prevent users from reverse engineering mobile app secrets, so design your app (and APIs) with that in mind.

Setup

✅ The latest version of react-native-config is tested with React Native 0.87 (New Architecture) — see the example app. On Windows it is tested with react-native-windows 0.79, the newest React Native version react-native-windows supports today — see the Windows example app.

⚠️ Note (Android): react-native-config v1.6.0+ requires React Native 0.74 or higher.
If you use an older RN version, see Troubleshooting below.

Install the package:

$ yarn add react-native-config

Link the library:

On React Native 0.60 and above there is no link step — the library is autolinked. Rebuild the app so the native side is picked up. On iOS / macOS, install the pod first:

(cd ios; pod install)

Warning

Do not link this library manually on React Native 0.60 or above, and do not disable its autolinking in react-native.config.js. Autolinking is what registers the native module and, on the New Architecture, generates its TurboModule bindings — adding include ':react-native-config' to android/settings.gradle instead does neither, and the module then resolves to null at runtime. See TypeError: Cannot read property 'getConfig' of null.

(Note: For Windows, this module supports autolinking when used with react-native-windows@0.63 or later. For earlier versions you need to manually link the module.)

Manual linking — only for React Native below 0.60, or react-native-windows below 0.63

$ react-native link react-native-config

(react-native link was removed from the React Native CLI; it is only available on the older versions these instructions apply to.)

Manual Link (iOS / macOS)
1. In XCode, in the project navigator, right click Libraries ➜ Add Files to [your project's name]
2. Go to node_modules ➜ react-native-config ➜ ios and add ReactNativeConfig.xcodeproj
3. Expand the ReactNativeConfig.xcodeproj ➜ Products folder
4. In the project navigator, select your project. Add libRNCConfig.a to your project's Build Phases ➜ Link Binary With Libraries
5. And go the Build Settings tab. Make sure All is toggled on (instead of Basic)
6. Look for Header Search Paths and add $(SRCROOT)/../node_modules/react-native-config/ios/** as non-recursive

Manual Link (Android)

android/settings.gradle

+ include ':react-native-config'+ project(':react-native-config').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-config/android')

android/app/build.gradle

dependencies {
implementation "com.facebook.react:react-native:+" // From node_modules
+	implementation project(':react-native-config')
}

MainApplication.java

+ import com.lugg.RNCConfig.RNCConfigPackage;
@Override
protected List<ReactPackage> getPackages() {
return Arrays.asList(
new MainReactPackage()
+ new RNCConfigPackage()
);
}

Manual Link (Windows)
windows/myapp.sln
Add the RNCConfig project to your solution.
1. Open the solution in Visual Studio 2019
2. Right-click Solution icon in Solution Explorer > Add > Existing Project
- if using react-native-windows@0.62 or later select node_modules\react-native-config\windows\RNCConfig\RNCConfig.vcxproj
  - if using react-native-windows@0.61 select node_modules\react-native-config\windows\RNCConfig61\RNCConfig61.vcxproj
windows/myapp/myapp.vcxproj
Add a reference to RNCConfig to your main application project. From Visual Studio 2019:
1. Right-click main application project > Add > Reference...
  Check RNCConfig from Solution Projects.
pch.h
Add #include "winrt/RNCConfig.h".
app.cpp
Add PackageProviders().Append(winrt::RNCConfig::ReactPackageProvider()); before InitializeComponent();.

Extra step for Android

Using RN-Integrate

Apply extra steps automatically:

npx react-native-integrate react-native-config

Manual

You'll also need to manually apply a plugin to your app, from android/app/build.gradle:

// 2nd line, add a new apply:
apply from: project(':react-native-config').projectDir.getPath() + "/dotenv.gradle"

Advanced Android Setup

BuildConfig is generated in your module's namespace, which is not always the same as its applicationId — applicationIdSuffix and per-flavor applicationId change the latter and leave the former alone. The library resolves this for you: it looks for BuildConfig in the package declaring your Application class (that is, the namespace) before falling back to the applicationId, so the common variant setups need no extra configuration.

If your BuildConfig lives somewhere neither of those points at, name the package explicitly in android/app/build.gradle:

defaultConfig {
...
resValue "string", "build_config_package", "YOUR_NAMESPACE"
}

where YOUR_NAMESPACE matches the namespace in android/app/build.gradle (on React Native 0.72 and older, the package attribute of <manifest> in AndroidManifest.xml). This value takes priority over the automatic resolution above.

If the config arrives in JS as {}, check logcat for ReactConfig: Could not find BuildConfig class — the message lists every package that was tried.

TypeScript declaration for your .env file

If you want to get autocompletion and typesafety for your .env files. Create a file named react-native-config.d.ts in the same directory where you put your type declarations, and add the following contents:

declare module 'react-native-config'{exportinterfaceNativeConfig{HOSTNAME?: string;}exportconstConfig: NativeConfigexportdefaultConfig}

Then when you want to use it, you just write:

import Config from 'react-native-config';
console.log(Config.HOSTNAME);

Native Usage

Android

Config variables set in .env are available to your Java classes via BuildConfig:

publicHttpURLConnectiongetApiClient() {
URLurl = newURL(BuildConfig.API_URL);
// ...
}

You can also read them from your Gradle configuration:

defaultConfig {
applicationId project.env.get("APP_ID")
}

And use them to configure libraries in AndroidManifest.xml and others:

<meta-dataandroid:name="com.google.android.geo.API_KEY"android:value="@string/GOOGLE_MAPS_API_KEY" />

All variables are strings, so you may need to cast them. For instance, in Gradle:

versionCode project.env.get("VERSION_CODE").toInteger()

Once again, remember variables stored in .env are published with your code, so DO NOT put anything sensitive there like your app signingConfigs.

iOS / macOS

Read variables declared in .env from your Obj-C classes like:

// import header
#import"RNCConfig.h"// then read individual keys like:NSString *apiUrl = [RNCConfig envFor:@"API_URL"];
// or just fetch the whole configNSDictionary *config = [RNCConfig env];

Windows

You can access variables declared in .env from C++ in your App project:

std::string api_key = ReactNativeConfig::API_KEY;

Similarly, you can access those values in other project by adding reference to the RNCConfig as described in the manual linking section.

Availability in Build settings and Info.plist

With one extra step environment values can be exposed to "Info.plist" and Build settings in the native project.

click on the file tree and create new file of type XCConfig
save it under ios folder as "Config.xcconfig" with the following content:

#include? "tmp.xcconfig"

add the following to your ".gitignore":

# react-native-config codegen
ios/tmp.xcconfig

go to project settings
apply config to your configurations
Go to Edit scheme... -> Build -> Pre-actions, click + and select New Run Script Action. Paste below code which will generate "tmp.xcconfig" before each build exposing values to Build Settings and Info.plist. Make sure to select your target under Provide build settings from, so $SRCROOT environment variables is available to the script. (Note that this snippet has to be placed after "cp ... ${PROJECT_DIR}/../.env" if approach explained below is used).
```
"${SRCROOT}/../node_modules/react-native-config/ios/ReactNativeConfig/BuildXCConfig.rb" "${SRCROOT}/.." "${SRCROOT}/tmp.xcconfig"
```
You can now access your env variables in the Info.plist, for example $(MY_ENV_VARIABLE). If you face issues accessing variables, please open a new issue and provide as much details as possible so above steps can be improved.

App Extensions

Add dependency to react-native-config.

target 'ShareExtension' do
platform :ios, '9.0'
pod 'react-native-config', :path => '../node_modules/react-native-config'
# For extensions without React dependencies
pod 'react-native-config/Extension', :path => '../node_modules/react-native-config'
end

Different environments

Save config for different environments in different files: .env.staging, .env.production, etc.

By default react-native-config will read from .env, but you can change it when building or releasing your app.

The simplest approach is to tell it what file to read with an environment variable, like:

$ ENVFILE=.env.staging react-native run-ios # bash
$ SET ENVFILE=.env.staging && react-native run-ios # windows
$ env:ENVFILE=".env.staging"; react-native run-ios # powershell

This also works for run-android. Alternatively, there are platform-specific options below.

Android

The same environment variable can be used to assemble releases with a different config:

$ cd android && ENVFILE=.env.staging ./gradlew assembleRelease

Note: When trying to release the bundle you need to export with a different config

$ cd android && export ENVFILE=.env.staging ./gradlew bundleRelease

Alternatively, you can define a map in build.gradle associating builds with env files. Do it before the apply from call, and use build cases in lowercase, like:

project.ext.envConfigFiles = [
debug: ".env.development",
release: ".env.production",
anothercustombuild: ".env",
]
apply from: project(':react-native-config').projectDir.getPath() + "/dotenv.gradle"

Also note that besides requiring lowercase, the matching is done with buildFlavor.startsWith, so a build named debugProd could match the debug case, above.

iOS / macOS

There are two ways to pick the env file. Prefer the first: nothing is copied over anything else, and the same setup works from Xcode, the CLI and CI.

Per build configuration (recommended)

Create one build configuration per environment — in Xcode, select the project, then Info > Configurations, and duplicate Debug and Release into e.g. Debug-Staging and Release-Staging. Name the env files to match, and one line in the Podfile covers every configuration, present and future:

post_installdo |installer|
installer.pods_project.targets.eachdo |target|
nextunlesstarget.name == 'react-native-config'target.build_configurations.eachdo |config|
config.build_settings['ENVFILE']='.env.$(CONFIGURATION)'endendend

With configurations Debug-Staging and Release-Staging, that reads .env.Debug-Staging and .env.Release-Staging from the project root. The path is relative to the project root, and $(CONFIGURATION) — or any other build setting, such as $(PLATFORM_NAME) — is expanded when the script runs.

If your env files are not named after your configurations, map them explicitly instead:

ENVFILES={'Debug'=>'.env.development','Release'=>'.env.production','Debug-Staging'=>'.env.staging','Release-Staging'=>'.env.staging',}post_installdo |installer|
installer.pods_project.targets.eachdo |target|
nextunlesstarget.name == 'react-native-config'target.build_configurations.eachdo |config|
config.build_settings['ENVFILE']=ENVFILES[config.name]endendend

Run pod install after editing the Podfile. The chosen file is echoed in the build log — search it for ENVFILE= to see what was selected and what it expanded to.

Important

If ENVFILE names a file that does not exist, the build does not fail: it falls back to .env, which means a correct-looking setup can quietly ship the wrong environment. The build log flags this — search for ENVFILE was set, but that file is missing.

Note that if you have flipper enabled in your Podfile, you must move the flipper_post_install into the newly added hook, since Podfile doesn't allow multiple post_install hooks.

 target 'MyApp' do
# ...
use_flipper!
- post_install do |installer|- flipper_post_install(installer)- end
end
post_install do |installer|
+ flipper_post_install(installer)
installer.pods_project.targets.each do |target|
next unless target.name == 'react-native-config'
target.build_configurations.each do |config|
config.build_settings['ENVFILE'] = '.env.$(CONFIGURATION)'
end
end
end

If you have several app targets

Selection is per build configuration, not per target. CocoaPods builds one react-native-config pod target per configuration and shares it between the app targets that depend on it, so two targets built as Debug both get the same env file — there is no point at which the library can tell them apart.

Give each environment its own build configurations (Debug-Staging, Release-Staging, …), set each target's scheme to use them, and the setup above then distinguishes them correctly.

Per scheme (copies the file)

The older approach: one scheme per environment, each copying its env file over .env before the build. It rewrites a file in your project on every build, and the copy is easy to forget on CI, so prefer the configuration-based setup above unless you specifically need this.

Start by creating a new scheme:

In the Xcode menu, go to Product > Scheme > Edit Scheme
Click Duplicate Scheme on the bottom
Give it a proper name on the top left. For instance: "Myapp (staging)"
Make sure the "Shared" checkbox is checked so the scheme is added to your version control system

Then edit the newly created scheme to make it use a different env file. From the same "manage scheme" window:

Expand the "Build" settings on left
Click "Pre-actions", and under the plus sign select "New Run Script Action"

Where it says "Type a script or drag a script file", type:

cp "${PROJECT_DIR}/../.env.staging" "${PROJECT_DIR}/../.env" # replace .env.staging for your file

Also ensure that "Provide build settings from", just above the script, has a value selected so that PROJECT_DIR is set.

Troubleshooting

Problems with Proguard

When Proguard is enabled (which it is by default for Android release builds), it can rename the BuildConfig Java class in the minification process and prevent React Native Config from referencing it. To avoid this, add an exception to android/app/proguard-rules.pro:

-keep class com.mypackage.BuildConfig { *; }

com.mypackage should match the package value in your app/src/main/AndroidManifest.xml file.

If using Dexguard, the shrinking phase will remove resources it thinks are unused. It is necessary to add an exception to preserve the build config package name.

-keepresources string/build_config_package

Config is empty (`{}`) on iOS

The values are baked in at build time by the Config codegen build phase, so an empty Config means that phase either did not run or did not find an env file. The library says which it was — check the Xcode console (or npx react-native log-ios) for a line starting with [react-native-config]:

"no env file was found. Looked for <path>" — nothing was read. If the path is wrong, select the intended file with ENVFILE (ENVFILE=.env.staging npx react-native run-ios); if the path is right but the file is somewhere else, the project root is probably not where the library expects it (common in monorepos). If the path looks correct, the build phase never ran: re-run pod install and build again.
"the env file was read from <path>, and no variables were parsed out of it" — the file was found but yielded nothing. Check that it contains plain KEY=value lines.

The same paths are listed at build time. Search the Xcode build log for Missing .env file to see every location that was tried, in order.

Note that ENVFILE naming a file that does not exist is not an error: the library falls back to .env. The logged path is the file the values actually came from, which is the quickest way to spot that fallback.

TypeError: Cannot read property 'getConfig' of null

The JavaScript side loaded but the native module is not registered in the build, so TurboModuleRegistry returned null. In rough order of likelihood:

The app was not rebuilt after the library was installed. Restarting Metro does not rebuild native code — rebuild the app itself.
Autolinking is disabled for this library. Look for an entry like this in react-native.config.js and remove it:
```
dependencies: {'react-native-config': {platforms: {android: null},// <- remove},},
```
The library is linked manually. On React Native 0.60+ autolinking replaces manual linking, and on the New Architecture a manually linked module is never registered as a TurboModule. Remove include ':react-native-config' (and the accompanying project(...) line) from android/settings.gradle, and implementation project(':react-native-config') from android/app/build.gradle.
iOS only:pod install has not been run since the library was installed.

After changing any of the above, rebuild from clean — on Android, delete android/build and android/app/build first, since a stale build can keep the old registration.

TypeError: _reactNativeConfig.default.getConstants is not a function

This error stems from .env file being malformed. Accepted formats are listed here https://regex101.com/r/cbm5Tp/1. Common causes are:

Missing the .env file entirely
Rogue space anywhere, example: in front of env variable: MY_ENV='foo'

Android build error: cannot find symbol BaseReactPackage

Starting from react-native-config v1.6.0, the Android implementation uses BaseReactPackage instead of ReactPackage.

BaseReactPackage was introduced in React Native 0.74, so projects on React Native 0.73 or older will see build errors like:

cannot find symbol
class BaseReactPackage

To fix this:

Use react-native-configbelow 1.6.0 (e.g. 1.5.10), or
Upgrade React Native to 0.74 or higher

Testing

Since react-native-config contains native code, it cannot be run in a node.js environment (Jest, Mocha). react-native-config-node provides a way to mock react-native-config for use in test runners - exactly as it is used in the actual app.

On Windows, the Windows example app runs its tests with the react-native-windows Jest preset. In the Example.windows folder run:

yarn test:windows

Jest

For mocking the Config.FOO_BAR usage, create a mock at __mocks__/react-native-config.js:

// __mocks__/react-native-config.js
export default {
FOO_BAR: 'baz',
};

Name		Name	Last commit message	Last commit date
.github		.github
Example.windows		Example.windows
Example		Example
android		android
brand		brand
codegen		codegen
ios		ios
readme-pics		readme-pics
scripts		scripts
test		test
windows		windows
.gitignore		.gitignore
.npmignore		.npmignore
LICENSE		LICENSE
README.md		README.md
index.d.ts		index.d.ts
index.js		index.js
package.json		package.json
react-native-config.podspec		react-native-config.podspec
release.config.js		release.config.js
yarn.lock		yarn.lock

Tier	Amount	What you get
Partner	$1,000 / month	Logo and link at the top of this README and in each release note, listed first on Open Collective, and a direct channel to the maintainers for build breakages affecting your apps.
Sponsor	$250 / month	Logo and link in this section and on Open Collective.
Backer	$50 / month	Your name or avatar in this section and on Open Collective.
Supporter	$5 / month	Your name on Open Collective — for individuals who just want to help.
One-off	any amount	Our thanks. One-off contributions fund exactly the same work.

Uh oh!

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

react-native-config

Basic Usage

Setup

Extra step for Android

Using RN-Integrate

Manual

Advanced Android Setup

TypeScript declaration for your .env file

Native Usage

Android

iOS / macOS

Windows

Availability in Build settings and Info.plist

App Extensions

Different environments

Android

iOS / macOS

Per build configuration (recommended)

If you have several app targets

Per scheme (copies the file)

Troubleshooting

Problems with Proguard

Config is empty ({}) on iOS

TypeError: Cannot read property 'getConfig' of null

TypeError: _reactNativeConfig.default.getConstants is not a function

Android build error: cannot find symbol BaseReactPackage

Testing

Jest

Sponsors

Tiers

What sponsorship is, and what it isn't

Current sponsors

Can't sponsor? You can still help

Meta

About

Resources

Stars

Watchers

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages

Config is empty (`{}`) on iOS