{"id":15787,"library":"react-native-config","title":"React Native Config Variables","description":"react-native-config is a module that provides a straightforward way to expose configuration variables to React Native applications, aligning with the 12 Factor App methodology for configuration. It supports multiple platforms including iOS, Android, macOS, and Windows. The current stable version is 1.6.1, with releases occurring frequently to address platform-specific issues, introduce new architecture support (like Fabric for iOS and Android), and extend compatibility to newer platforms like visionOS. Its key differentiators include broad platform support and a simple `.env` file interface, making it easy to manage environment-specific variables without modifying code. However, it's crucial to understand that it does not obfuscate or encrypt secrets, which is a fundamental limitation for mobile apps; therefore, sensitive keys should not be stored directly in `.env` files. The package emphasizes ease of use for non-sensitive configuration parameters across diverse mobile and desktop platforms supported by React Native.","status":"active","version":"1.6.1","language":"javascript","source_language":"en","source_url":"https://github.com/luggit/react-native-config","tags":["javascript","env","config","config-var","react-native","android","ios","windows","12factor","typescript"],"install":[{"cmd":"npm install react-native-config","lang":"bash","label":"npm"},{"cmd":"yarn add react-native-config","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-native-config","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React Native environment.","package":"react","optional":false},{"reason":"Core dependency for React Native application environment.","package":"react-native","optional":false},{"reason":"Peer dependency for Windows platform support.","package":"react-native-windows","optional":true}],"imports":[{"note":"Config is the default export containing all environment variables. While CommonJS `require` might work in some setups, modern React Native tooling and module resolution favor ESM `import`. The package ships TypeScript types for type-safe access.","wrong":"const Config = require('react-native-config');","symbol":"Config","correct":"import Config from 'react-native-config';"}],"quickstart":{"code":"import Config from \"react-native-config\";\nimport { useEffect, useState } from 'react';\nimport { View, Text, StyleSheet } from 'react-native';\n\nconst App = () => {\n  const [apiUrl, setApiUrl] = useState('');\n  const [googleMapsKey, setGoogleMapsKey] = useState('');\n\n  useEffect(() => {\n    // Variables from .env are automatically loaded into the Config object\n    // Ensure you have a .env file in your project root, e.g.:\n    // API_URL=https://myapi.com/v1\n    // GOOGLE_MAPS_API_KEY=your_google_maps_api_key\n    // SENSITIVE_KEY_EXAMPLE=DO_NOT_STORE_SECRETS_DIRECTLY_HERE\n\n    setApiUrl(Config.API_URL);\n    setGoogleMapsKey(Config.GOOGLE_MAPS_API_KEY);\n  }, []);\n\n  return (\n    <View style={styles.container}>\n      <Text style={styles.header}>React Native Config Example</Text>\n      <Text style={styles.label}>API URL:</Text>\n      <Text style={styles.value}>{apiUrl || 'Not set'}</Text>\n      <Text style={styles.label}>Google Maps Key:</Text>\n      <Text style={styles.value}>{googleMapsKey || 'Not set'}</Text>\n      <Text style={styles.warning}>\n        Warning: Do not store sensitive keys in .env for mobile apps as they are not obfuscated.\n      </Text>\n    </View>\n  );\n};\n\nconst styles = StyleSheet.create({\n  container: {\n    flex: 1,\n    justifyContent: 'center',\n    alignItems: 'center',\n    padding: 20,\n    backgroundColor: '#f5f5f5',\n  },\n  header: {\n    fontSize: 24,\n    fontWeight: 'bold',\n    marginBottom: 20,\n    color: '#333',\n  },\n  label: {\n    fontSize: 16,\n    fontWeight: '600',\n    marginTop: 10,\n    color: '#555',\n  },\n  value: {\n    fontSize: 16,\n    marginBottom: 5,\n    color: '#007bff',\n  },\n  warning: {\n    fontSize: 12,\n    color: 'red',\n    marginTop: 30,\n    textAlign: 'center',\n  },\n});\n\nexport default App;\n","lang":"typescript","description":"This example demonstrates how to define environment variables in a `.env` file and access them within a React Native component using `react-native-config`. It highlights the basic usage pattern for displaying configuration values and includes a crucial warning about storing sensitive information."},"warnings":[{"fix":"Design your backend APIs to not rely on client-side secrets, or use a secure vault/backend service for sensitive key management instead of storing them directly in the app's `.env`.","message":"Secrets stored in `.env` files are not obfuscated or encrypted when packaged into a mobile app. Malicious users can reverse engineer apps to extract these values.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Refer to the `react-native-config` documentation for platform-specific manual linking instructions or upgrade your React Native project to a version that supports autolinking (RN 0.60+ for core, RN 0.63+ for Windows).","message":"For React Native versions prior to 0.60, autolinking is not available. Manual linking steps for iOS, Android, and Windows are required, which can be complex and error-prone. Windows also requires manual linking for versions below 0.63.","severity":"breaking","affected_versions":"<0.60 (core RN), <0.63 (Windows)"},{"fix":"Add `apply from: project(':react-native-config').project` to the second line of your `android/app/build.gradle` file. Alternatively, use `npx react-native-integrate react-native-config`.","message":"After installation and linking, Android projects require an additional manual step to apply a plugin in `android/app/build.gradle` for `react-native-config` to function correctly. Failure to do so will result in build errors or variables not being loaded.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Navigate to your `ios` directory (`cd ios`) and run `pod install`. Clean your build folder in Xcode afterwards (`Product > Clean Build Folder`).","message":"When using `react-native-config` in an iOS project that utilizes Cocoapods, you must run `pod install` in the `ios/` directory after adding the package to your `package.json` to ensure the native module is correctly linked.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure you are on `react-native-config@1.6.0` or higher for New Architecture support. Follow the specific New Architecture setup steps provided in the official documentation, which often involves codegen and proper project configuration.","message":"Projects upgrading to or using React Native's New Architecture (Fabric, TurboModules) on iOS or Android may encounter build issues if `react-native-config` isn't properly configured or if an incompatible version is used. Version 1.6.0+ introduced specific support for the new architecture.","severity":"gotcha","affected_versions":"~1.0.0 - 1.5.x (with New Arch); >1.6.0 (improper setup)"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Verify manual linking steps for Android (`settings.gradle`, `app/build.gradle`, `MainApplication.java`) and ensure `apply from: project(':react-native-config').project` is in `android/app/build.gradle`. If using autolinking, ensure caches are cleared and rebuild (`./gradlew clean`).","cause":"The `react-native-config` package's Android native module is not correctly linked or `MainApplication.java` is missing package registration.","error":"error: cannot find symbol class RNCConfigPackage"},{"fix":"For iOS, run `cd ios && pod install` and clean the build folder (`Product > Clean Build Folder`) in Xcode. For Android, ensure all manual linking steps are followed, especially the `apply from` line in `app/build.gradle`, and then clean the Gradle cache (`./gradlew clean`). For older RN versions, ensure manual linking is complete as per documentation.","cause":"The native module for `react-native-config` failed to load for iOS or Android, meaning the JavaScript bridge cannot find the `Config` object.","error":"Invariant Violation: `Config` has not been registered. This can happen if the `Config` module wasn't linked correctly."},{"fix":"If using Cocoapods, navigate to `ios` and run `pod install`. If not using Cocoapods or for manual linking, ensure `ReactNativeConfig.xcodeproj` is added to `Libraries` and `libRNCConfig.a` is in `Build Phases` -> `Link Binary With Libraries` in your Xcode project. Clean Xcode build folder and derived data.","cause":"The `ReactNativeConfig.xcodeproj` or `libRNCConfig.a` is not correctly linked in Xcode, or `pod install` was not run after adding the package.","error":"Undefined symbol: _OBJC_CLASS_$_RNCConfig"},{"fix":"Create a declaration file (e.g., `src/types/env.d.ts` or `env.d.ts`) in your project root and declare the module with your environment variables. Example: `declare module 'react-native-config' { export interface NativeConfig { API_URL: string; GOOGLE_MAPS_API_KEY: string; [key: string]: string | undefined; } export const Config: NativeConfig; export default Config; }`","cause":"TypeScript is not aware of the specific environment variables defined in your `.env` file, defaulting `Config` to an empty object type.","error":"Property 'API_URL' does not exist on type 'Readonly<{}>'."},{"fix":"Verify the `android/settings.gradle` file contains both `include ':react-native-config'` and the correct `project(':react-native-config').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-config/android')`.","cause":"The `include ':react-native-config'` line or the `project(':react-native-config').projectDir` mapping in `android/settings.gradle` is incorrect or missing, preventing Gradle from locating the native module.","error":"A problem occurred evaluating project ':app'. > Project with path ':react-native-config' could not be found."}],"ecosystem":"npm"}