react-native-config 1.6.2 → 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
 
@@ -352,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
@@ -404,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
@@ -427,6 +498,28 @@ 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

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.2",
+  "version": "1.7.0",
   "description": "Expose config variables to React Native apps",
   "keywords": [
     "env",
@@ -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",