react-native-config 1.6.1 → 1.7.0

package/README.md

@@ -1,8 +1,24 @@
-# Config variables for React Native apps
+<p align="center">
+  <img src="brand/logo.png" alt="" width="120" height="120" />
+</p>
 
-Module to expose config variables to your javascript code in React Native, supporting iOS, Android, macOS and Windows.
+<h1 align="center">react-native-config</h1>
 
-Bring some [12 factor](http://12factor.net/config) love to your mobile apps!
+<p align="center">
+  Config variables for React Native apps, supporting iOS, Android, macOS and Windows.
+</p>
+
+Expose config variables to your JavaScript code — bring some
+[12 factor](http://12factor.net/config) 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](https://opencollective.com/react-native-config).
+> Contributions go toward the maintenance work that keeps it working across new React Native
+> releases. See
+> [#885](https://github.com/react-native-config/react-native-config/issues/885) for what
+> sponsorship pays for and other ways to help.
 
 ## Basic Usage
 
@@ -26,6 +42,9 @@ Keep in mind this module doesn't obfuscate or encrypt secrets for packaging, so
 
 ## Setup
 
+> ⚠️ 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:
 
 ```
@@ -34,20 +53,34 @@ $ yarn add react-native-config
 
 Link the library:
 
-(Note: For React Native 0.60 or greater, [autolinking](https://reactnative.dev/blog/2019/07/03/version-60#native-modules-are-now-autolinked) is available)
+On React Native 0.60 and above there is no link step — the library is
+[autolinked](https://reactnative.dev/blog/2019/07/03/version-60#native-modules-are-now-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](#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.)
 
+<details>
+<summary><b>Manual linking</b> — only for React Native below 0.60, or react-native-windows below 0.63</summary>
+
 ```
 $ react-native link react-native-config
 ```
 
-if cocoapods are used in the project then pod has to be installed as well:
-
-```
-(cd ios; pod install)
-```
+(`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)
 
@@ -115,6 +148,8 @@ if cocoapods are used in the project then pod has to be installed as well:
 
 	Add `PackageProviders().Append(winrt::RNCConfig::ReactPackageProvider());` before `InitializeComponent();`.
 
+</details>
+
 ### Extra step for Android
 #### Using RN-Integrate
 Apply extra steps automatically:
@@ -132,16 +167,29 @@ apply from: project(':react-native-config').projectDir.getPath() + "/dotenv.grad
 
 #### Advanced Android Setup
 
-In `android/app/build.gradle`, if you use `applicationIdSuffix` or `applicationId` that is different from the package name indicated in `AndroidManifest.xml` in `<manifest package="...">` tag, for example, to support different build variants:
-Add this in `android/app/build.gradle`
+`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_PACKAGE_NAME_IN_ANDROIDMANIFEST_XML"
+    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:
@@ -320,44 +368,63 @@ Also note that besides requiring lowercase, the matching is done with `buildFlav
 
 #### iOS / macOS
 
-The basic idea in iOS is to have one scheme per environment file, so you can easily alternate between them.
+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.
 
-Start by creating a new scheme:
+##### Per build configuration (recommended)
 
-- 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
+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:
 
-Then edit the newly created scheme to make it use a different env file. From the same "manage scheme" window:
+```ruby
+post_install do |installer|
+  installer.pods_project.targets.each do |target|
+    next unless target.name == 'react-native-config'
 
-- 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.
+    target.build_configurations.each do |config|
+      config.build_settings['ENVFILE'] = '.env.$(CONFIGURATION)'
+    end
+  end
+end
+```
 
-Alternatively, if you have separated build configurations, you may easily set the different envfiles per configuration by adding these lines into the end of Podfile:
+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:
 
 ```ruby
 ENVFILES = {
-  'Debug' => '$(PODS_ROOT)/../../.env.debug',
-  'Release' => '$(PODS_ROOT)/../../.env.production',
+  'Debug' => '.env.development',
+  'Release' => '.env.production',
+  'Debug-Staging' => '.env.staging',
+  'Release-Staging' => '.env.staging',
 }
 post_install do |installer|
   installer.pods_project.targets.each do |target|
+    next unless target.name == 'react-native-config'
+
     target.build_configurations.each do |config|
-      if target.name == 'react-native-config'
-        config.build_settings['ENVFILE'] = ENVFILES[config.name]
-      end
+      config.build_settings['ENVFILE'] = ENVFILES[config.name]
     end
   end
 end
 ```
 
-Note that if you have flipper enabled in your Podfile, you must move the `flipper_post_install` into the newely added hook since Podfile doesn't allow multiple `post_install` hooks.
+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.
 
 ```diff
   target 'MyApp' do
@@ -372,15 +439,51 @@ Note that if you have flipper enabled in your Podfile, you must move the `flippe
 +   flipper_post_install(installer)
 
     installer.pods_project.targets.each do |target|
+      next unless target.name == 'react-native-config'
+
       target.build_configurations.each do |config|
-        if target.name == 'react-native-config'
-          config.build_settings['ENVFILE'] = ENVFILES[config.name]
-        end
+        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
@@ -395,12 +498,78 @@ If using Dexguard, the shrinking phase will remove resources it thinks are unuse
 
     -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:
+
+1. **The app was not rebuilt** after the library was installed. Restarting Metro does not rebuild
+   native code — rebuild the app itself.
+2. **Autolinking is disabled for this library.** Look for an entry like this in
+   `react-native.config.js` and remove it:
+
+   ```js
+   dependencies: {
+     'react-native-config': {
+       platforms: { android: null }, // <- remove
+     },
+   },
+   ```
+
+3. **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`.
+4. **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-config` **below 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](https://github.com/CureApp/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.

package/android/src/main/java/com/lugg/RNCConfig/RNCConfigModuleImpl.java

@@ -7,12 +7,18 @@ import com.facebook.react.bridge.WritableMap;
 import java.lang.ClassNotFoundException;
 import java.lang.IllegalAccessException;
 import java.lang.reflect.Field;
+import java.util.ArrayList;
+import java.util.LinkedHashSet;
+import java.util.List;
 import java.util.Map;
 import java.util.HashMap;
+import java.util.Set;
 
 public class RNCConfigModuleImpl {
   public static final String NAME = "RNCConfigModule";
 
+  private static final String TAG = "ReactNative";
+
   private ReactApplicationContext context;
 
   public RNCConfigModuleImpl(ReactApplicationContext context) {
@@ -32,31 +38,78 @@ public class RNCConfigModuleImpl {
     // because of type safety on the new arch
     final Map<String, Object> realConstants = new HashMap<>();
 
-    try {
-      int resId = this.context.getResources().getIdentifier("build_config_package", "string", context.getPackageName());
-      String className;
+    final List<String> candidates = buildConfigPackageCandidates();
+    Class<?> clazz = null;
+
+    for (String candidate : candidates) {
       try {
-        className = this.context.getString(resId);
-      } catch (Resources.NotFoundException e) {
-        className = this.context.getApplicationContext().getPackageName();
+        clazz = Class.forName(candidate + ".BuildConfig");
+        break;
+      }
+      catch (ClassNotFoundException e) {
+        // Not here - try the next candidate.
       }
-      Class clazz = Class.forName(className + ".BuildConfig");
+    }
+
+    if (clazz == null) {
+      Log.w(TAG, "ReactConfig: Could not find BuildConfig class. Tried: " + candidates + ". "
+          + "If BuildConfig is generated somewhere else, point the library at it with "
+          + "`resValue \"string\", \"build_config_package\", \"<your namespace>\"` in android/app/build.gradle.");
+    }
+    else {
       Field[] fields = clazz.getDeclaredFields();
       for(Field f: fields) {
         try {
           realConstants.put(f.getName(), f.get(null));
         }
         catch (IllegalAccessException e) {
-          Log.d("ReactNative", "ReactConfig: Could not access BuildConfig field " + f.getName());
+          Log.d(TAG, "ReactConfig: Could not access BuildConfig field " + f.getName());
         }
       }
     }
-    catch (ClassNotFoundException e) {
-      Log.d("ReactNative", "ReactConfig: Could not find BuildConfig class");
-    }
 
     ret.put("config", realConstants);
 
     return MapConverter.convertMapToWritableMap(ret);
   }
+
+  /**
+   * Packages that may hold the app's generated BuildConfig, most-specific first.
+   *
+   * BuildConfig is generated in the module's `namespace`, which is not necessarily the
+   * applicationId: `applicationIdSuffix` and per-flavor `applicationId` change the latter and
+   * leave the former alone. Resolving only via getPackageName() therefore misses BuildConfig on
+   * any such variant, and the config silently arrives in JS as {}.
+   */
+  private List<String> buildConfigPackageCandidates() {
+    // LinkedHashSet keeps the priority order below while dropping duplicates, which is the
+    // common case: for most apps all three candidates are the same string.
+    final Set<String> candidates = new LinkedHashSet<>();
+
+    // 1. An explicit `resValue "string", "build_config_package", "..."`. Honoured first so that
+    //    existing setups relying on it keep working, and so it stays an escape hatch when the
+    //    derived candidates below are wrong.
+    int resId = this.context.getResources().getIdentifier(
+        "build_config_package", "string", this.context.getPackageName());
+    if (resId != 0) {
+      try {
+        candidates.add(this.context.getString(resId));
+      }
+      catch (Resources.NotFoundException e) {
+        // Declared but unreadable - fall through to the derived candidates.
+      }
+    }
+
+    // 2. The package declaring the Application class. That class is part of the app module, so
+    //    its package is the `namespace` - unaffected by applicationId/applicationIdSuffix.
+    Package applicationPackage = this.context.getApplicationContext().getClass().getPackage();
+    if (applicationPackage != null) {
+      candidates.add(applicationPackage.getName());
+    }
+
+    // 3. The applicationId. Correct whenever it matches the namespace, which is the default.
+    candidates.add(this.context.getApplicationContext().getPackageName());
+
+    return new ArrayList<>(candidates);
+  }
 }

package/index.js

@@ -1,5 +1,27 @@
 "use strict";
 
-export const Config =
-  require("./codegen/NativeConfigModule").default.getConfig().config;
+const NativeConfigModule = require("./codegen/NativeConfigModule").default;
+
+if (NativeConfigModule == null) {
+  // TurboModuleRegistry.get returns null when the native module is not registered in the app.
+  // Left alone, the next line fails with "Cannot read property 'getConfig' of null", which says
+  // nothing about the cause - so spell out the ones that actually produce this.
+  throw new Error(
+    "react-native-config: the native module RNCConfigModule was not found.\n\n" +
+      "JavaScript loaded, but the native side is not registered in this build. Common causes:\n\n" +
+      "  1. The app was not rebuilt after installing the library. Restarting Metro is not enough -\n" +
+      "     rebuild the native app.\n" +
+      "  2. Autolinking is disabled for this library. Check react-native.config.js for a\n" +
+      "     `dependencies` entry setting `platforms.android` or `platforms.ios` to null, and\n" +
+      "     remove it.\n" +
+      "  3. The library is linked manually. React Native 0.60+ autolinks it, and on the New\n" +
+      "     Architecture a manually linked module is not registered as a TurboModule. Remove\n" +
+      "     `include ':react-native-config'` from android/settings.gradle and the matching\n" +
+      "     `implementation project(':react-native-config')` from android/app/build.gradle.\n" +
+      "  4. iOS only: `pod install` has not run since the library was installed.\n\n" +
+      "See https://github.com/react-native-config/react-native-config#troubleshooting"
+  );
+}
+
+export const Config = NativeConfigModule.getConfig().config;
 export default Config;

package/ios/ReactNativeConfig/BuildDotenvConfig.rb

@@ -12,13 +12,23 @@ puts "reading env file from #{envs_root} and writing .m to #{m_output_path}"
 Encoding.default_external = Encoding::UTF_8
 Encoding.default_internal = Encoding::UTF_8
 
-dotenv, custom_env = read_dot_env(envs_root)
+dotenv, custom_env, resolution = read_dot_env(envs_root)
 puts "read dotenv #{dotenv}"
 
 # create obj file that sets DOT_ENV as a NSDictionary
 dotenv_objc = dotenv.map { |k, v| %(@"#{k}":@"#{v.chomp}") }.join(',')
+
+# Carry the outcome of the lookup into the binary alongside the values themselves. An empty
+# DOT_ENV is otherwise indistinguishable at runtime from an env file that was never found, and
+# the latter is by far the more common cause - see RNCConfig.m.
+env_found = resolution && resolution[:found] ? 1 : 0
+env_path = (resolution && (resolution[:path] || resolution[:tried].first)).to_s
+env_path_objc = env_path.gsub('\\', '\\\\\\\\').gsub('"', '\"')
+
 template = <<EOF
   #define DOT_ENV @{ #{dotenv_objc} };
+  #define RNC_DOT_ENV_FOUND #{env_found}
+  #define RNC_DOT_ENV_PATH @"#{env_path_objc}"
 EOF
 
 # write it so that RNCConfig.m can return it

package/ios/ReactNativeConfig/GeneratedDotEnv.m

@@ -1 +1,3 @@
   #define DOT_ENV @{  };
+  #define RNC_DOT_ENV_FOUND 0
+  #define RNC_DOT_ENV_PATH @"(none - the Config codegen build phase has not run)"

package/ios/ReactNativeConfig/RNCConfig.m

@@ -1,10 +1,22 @@
 #import "RNCConfig.h"
-#import "GeneratedDotEnv.m" // written during build by BuildDotenvConfig.ruby
+#import "GeneratedDotEnv.m" // written during build by BuildDotenvConfig.rb
+
+// A GeneratedDotEnv.m produced by an older version of the library defines DOT_ENV alone. That
+// copy lives in node_modules and is only replaced when the codegen build phase runs, which is
+// precisely the case this file reports on - so fall back rather than failing to compile.
+#ifndef RNC_DOT_ENV_FOUND
+#define RNC_DOT_ENV_FOUND 0
+#endif
+#ifndef RNC_DOT_ENV_PATH
+#define RNC_DOT_ENV_PATH @"(unknown - GeneratedDotEnv.m predates this diagnostic)"
+#endif
 
 @implementation RNCConfig
 
 + (NSDictionary *)env {
-    return (NSDictionary *)DOT_ENV;
+    NSDictionary *env = (NSDictionary *)DOT_ENV;
+    [self warnOnceIfEmpty:env];
+    return env;
 }
 
 + (NSString *)envFor: (NSString *)key {
@@ -12,4 +24,33 @@
     return value;
 }
 
+// An empty config reaches JS as `{}` with nothing else to go on, and is the most reported
+// symptom against this library. Say which file was looked for, and whether it was found, at the
+// point the emptiness is first observed.
+//
+// NSLog rather than RCTLog: this file is also compiled into the `Extension` subspec, which has no
+// React dependency.
++ (void)warnOnceIfEmpty:(NSDictionary *)env {
+    if (env.count > 0) {
+        return;
+    }
+
+    static dispatch_once_t onceToken;
+    dispatch_once(&onceToken, ^{
+        if (RNC_DOT_ENV_FOUND) {
+            NSLog(@"[react-native-config] Config is empty. The env file was read from %@, and no "
+                  @"variables were parsed out of it - check that it contains KEY=value lines.",
+                  RNC_DOT_ENV_PATH);
+        } else {
+            NSLog(@"[react-native-config] Config is empty: no env file was found. Looked for %@.\n"
+                  @"  - If the path is wrong, set ENVFILE (e.g. `ENVFILE=.env.staging npx react-native run-ios`),\n"
+                  @"    or point the library at the right root if this project is in a monorepo.\n"
+                  @"  - If the path is right, the 'Config codegen' build phase did not run: re-run\n"
+                  @"    `pod install`, then build again.\n"
+                  @"  See https://github.com/react-native-config/react-native-config#troubleshooting",
+                  RNC_DOT_ENV_PATH);
+        }
+    });
+}
+
 @end

package/ios/ReactNativeConfig/ReadDotEnv.rb

@@ -6,38 +6,100 @@
 Encoding.default_external = Encoding::UTF_8
 Encoding.default_internal = Encoding::UTF_8
 
+# Expands build settings referenced in an env file name, so that a single setting can serve every
+# configuration: ENVFILE=.env.$(CONFIGURATION) becomes .env.Release-Staging.
+#
+# Xcode expands $(FOO) itself when the value is a build setting, so this covers the cases where it
+# does not - an ENVFILE exported from the shell, or a value passed through untouched. A reference
+# to something unset expands to nothing and is reported, because being told that ".env." is
+# missing explains very little on its own.
+def expand_build_settings(value)
+  unset = []
+  expanded = value.gsub(/\$[({]([A-Za-z_][A-Za-z0-9_]*)[)}]|\$([A-Za-z_][A-Za-z0-9_]*)/) do
+    name = Regexp.last_match(1) || Regexp.last_match(2)
+    replacement = ENV[name]
+    unset << name if replacement.nil? || replacement.empty?
+    replacement.to_s
+  end
+  [expanded, unset]
+end
+
+# Which env file was asked for, and by whom. Kept separate from finding it so that a fallback can
+# be reported against what was actually requested.
+def select_env_file(default_env_file)
+  if File.exist?('/tmp/envfile')
+    return { name: File.read('/tmp/envfile').strip, source: :tmp_envfile, unset: [], custom: true }
+  end
+
+  requested = ENV['ENVFILE']
+  if requested.nil? || requested.empty?
+    return { name: default_env_file, source: :default, unset: [], custom: false }
+  end
+
+  expanded, unset = expand_build_settings(requested)
+  { name: expanded, source: :envfile, unset: unset, custom: false, requested: requested }
+end
+
 # TODO: introduce a parameter which controls how to build relative path
 def read_dot_env(envs_root)
   defaultEnvFile = '.env'
   puts "going to read env file from root folder #{envs_root}"
 
-  # pick a custom env file if set
-  if File.exist?('/tmp/envfile')
-    custom_env = true
-    file = File.read('/tmp/envfile').strip
-  else
-    custom_env = false
-    file = ENV['ENVFILE'] || defaultEnvFile
+  selection = select_env_file(defaultEnvFile)
+  file = selection[:name]
+  custom_env = selection[:custom]
+
+  if selection[:source] == :envfile
+    puts "ENVFILE=#{selection[:requested]}"
+    puts "  expands to #{file}" if selection[:requested] != file
+    unless selection[:unset].empty?
+      puts "  note: #{selection[:unset].uniq.join(', ')} " \
+           'resolved to nothing. Outside Xcode these build settings are not set - pass the file ' \
+           'name directly, or run the build through Xcode.'
+    end
   end
 
+  # Every path considered, in order. A miss here is not a build failure - the app compiles and
+  # receives an empty config - so the paths are recorded to be named in the message below and
+  # handed to the runtime, rather than leaving "it is empty" as the only available symptom.
+  tried = []
+  resolved_path = nil
+  requested_paths = []
+
   dotenv = begin
     # https://regex101.com/r/cbm5Tp/1
     dotenv_pattern = /^(?:export\s+|)(?<key>[[:alnum:]_]+)\s*=\s*((?<quote>["'])?(?<val>.*?[^\\])\k<quote>?|)$/
 
-    path = File.expand_path(File.join(envs_root, file.to_s))
-    if File.exist?(path)
-      raw = File.read(path)
-    elsif File.exist?(file)
-      raw = File.read(file)
-    else
-      defaultEnvPath = File.expand_path(File.join(envs_root, "#{defaultEnvFile}"))
-      unless File.exist?(defaultEnvPath)
-        # try as absolute path
-        defaultEnvPath = defaultEnvFile
-      end
-      raw = File.read(defaultEnvPath)
+    # The paths that satisfy what was asked for. Anything found beyond these is a fallback.
+    requested_paths = [
+      File.expand_path(File.join(envs_root, file.to_s)),
+      file.to_s
+    ]
+    candidates = requested_paths + [File.expand_path(File.join(envs_root, defaultEnvFile.to_s))]
+    # Last resort, preserving the previous behaviour: treat the default name as a path of its own.
+    candidates << defaultEnvFile unless File.exist?(candidates[2])
+
+    tried = candidates.uniq
+    resolved_path = tried.find { |candidate| File.exist?(candidate) }
+    raise Errno::ENOENT, tried.last if resolved_path.nil?
+
+    # Falling back is not an error - it is long-standing behaviour and some setups rely on it for
+    # a gitignored .env.local - but it is silent, and a build that quietly ships the wrong
+    # environment is worse than one that fails. Say so where the person configuring it will look.
+    if selection[:source] == :envfile && !requested_paths.include?(resolved_path)
+      puts('**********************************************')
+      puts('*** ENVFILE was set, but that file is missing ')
+      puts('**********************************************')
+      puts("Asked for: #{file}")
+      puts('Not found at:')
+      requested_paths.each { |candidate| puts("  - #{candidate}") }
+      puts("Falling back to: #{resolved_path}")
+      puts('The build will succeed using those values. If that is not what you want, correct')
+      puts('ENVFILE or add the missing file.')
     end
 
+    raw = File.read(resolved_path)
+
     raw.split("\n").inject({}) do |h, line|
       m = line.match(dotenv_pattern)
 
@@ -57,7 +119,16 @@ def read_dot_env(envs_root)
       puts('**************************')
       puts('*** Missing .env file ****')
       puts('**************************')
-      return [{}, false] # set dotenv as an empty hash
+      puts('Tried, in order:')
+      tried.each { |candidate| puts("  - #{candidate}") }
+      puts('The build will succeed and Config will be empty at runtime.')
+      # set dotenv as an empty hash
+      return [{}, false, { found: false, path: nil, tried: tried, source: selection[:source],
+                           requested: file, fell_back: false }]
   end
-  [dotenv, custom_env]
+
+  [dotenv, custom_env, { found: true, path: resolved_path, tried: tried,
+                         source: selection[:source], requested: file,
+                         fell_back: selection[:source] == :envfile &&
+                                    !requested_paths.include?(resolved_path) }]
 end

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-config",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "description": "Expose config variables to React Native apps",
   "keywords": [
     "env",
@@ -12,14 +12,14 @@
     "windows",
     "12factor"
   ],
-  "homepage": "https://github.com/luggit/react-native-config",
+  "homepage": "https://github.com/react-native-config/react-native-config",
   "contributors": [
     "Luan Curti <luancurti@gmail.com> (https://github.com/luancurti)",
     "Amer Lotfi Orimi <amerllica@gmail.com> (https://github.com/amerllica)"
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/luggit/react-native-config"
+    "url": "git+https://github.com/react-native-config/react-native-config.git"
   },
   "private": false,
   "author": "Pedro Belo",
@@ -35,6 +35,9 @@
   ],
   "types": "./index.d.ts",
   "license": "MIT",
+  "scripts": {
+    "test": "ruby test/run.rb"
+  },
   "devDependencies": {
     "@react-native-community/cli": "^20.0.2",
     "@semantic-release/git": "^10.0.1",
@@ -62,7 +65,7 @@
     },
     "ios": {
       "modules": {
-        "RNCConfig": {
+        "RNCConfigModule": {
           "className": "RNCConfigModule",
           "unstableRequiresMainQueueSetup": true
         }