react-native-config-ultimate

Config that works

This is a community-maintained fork of react-native-ultimate-config originally created by Max Komarychev.

The original library has not received updates since September 2023 and does not support React Native's New Architecture (TurboModules), React 19, or modern tooling. This fork picks up where it left off.

Full credit and gratitude to Max for the original design, architecture, and years of maintenance. This project would not exist without his work. The MIT license is preserved in its entirety.

Gradle compatibility

| react-native-config-ultimate | gradle | | ---------------------------- | ------ | | 0.0.x | 8 |

For older versions see the original package react-native-ultimate-config.

React Native compatibility

| react-native-config-ultimate | react-native | react | New Architecture | | ---------------------------- | ------------ | ------ | ---------------- | | 0.0.x | >=0.73 | >=18 | ✅ TurboModules |

TL;DR usage

1. install | npm | yarn | |-|-| |npm install react-native-config-ultimate | yarn add react-native-config-ultimate|
2. one-off setup for native projects
3. initialize env | npm | yarn | |-|-| |npx rncu .env|yarn rncu .env|
4. build! react-native run-{ios,android}

☝❗Approach to versioning and breaking changes

This library is using semver and heavily relying on codegeneration. Many new features and/or bugfixes will require these files to be regenerated. Changes to codegenerated files will not be considered breaking unless they affect behavior of API or CLI.

Therefore every time this library is updated all files MUST be regenerated using rncu command.

Table of contents

1. Features 🎆
2. Mission 🥾
3. Quickstart Guide 🏃
4. Migration Guide 🚀 — from react-native-ultimate-config or react-native-config
5. API 🧰
6. Testing Guide 🧪
7. Cookbook 🥦
8. Troubleshooting 🎱
9. Contributing 🤝
10. Alternatives

Features

1. Simple one-off setup for native projects
2. No need to mess with xcode schemes or android flavors
3. Access from javascript
4. Access from native code: Java, Kotlin, Objective-C, and Swift
5. Access in build tools: xcode, gradle and AndroidManifest.xml
6. Web support (works with React Native for Web)
7. Hooks
8. Monorepo support (yarn workspaces or lerna)
9. New Architecture — TurboModules support (RN 0.68+), fully backward-compatible with old arch
10. Multi-env file merging — rncu .env.base .env.staging (v7+)
11. Dotenv variable expansion — API_URL=$BASE_URL/v1 (v7+)
12. Schema validation — fail at build time on missing or invalid vars (v7+)
13. Unit tested with jest (136 tests, 93%+ coverage)
14. Written in TypeScript with strict mode — exact typings generated for your env vars
15. Supports dotenv and yaml
16. Fully typed values available when using yaml config
17. Configure values per platform in one file

Mission

React-Native brings together 3 platforms: ios, android, javascript each of which have different conventions and approaches how to manage environment settings.

A typical app is usually operating in some environment defined by server urls various api keys or feature flags. When dealing with react-native such things often need to exist in 3 places: ios, android and js code. Even managing things as simple as application name or bundle id needs to be done in 2 places: Info.plist and AndroidManifest.xml

react-native-config-ultimate tries to reduce friction in managing these things by abstracting away from nuances of native projects.

With react-native-config-ultimate it is possible to consume variables in every place of a typical react-native app:

• javascript / typescript
• native code
  • java / kotlin
  • objective-c / swift
• native build configuration
  • ios
    • build settings
    • infoplist
  • android
    • build config
    • string resources
    • project.ext

|-------------------------------------------------------|
|                                                       |
|                 javascript / typescript               |
|                                                       |
|-------------------------------------------------------|
|                          |                            |
|   objective-c / swift    |       java / kotlin        |
|                          |                            |
|-------------------------------------------------------|
|                          |                            |
|      build settings      |     AndroidManifest.xml    |
|         infoplist        |        build.gradle        |
|                          |                            |
|-------------------------------------------------------|

Releases

This project uses release-please for automated releases. Every merge to master with conventional commits (feat:, fix:, etc.) will automatically:

1. Create/update a Release PR with changelog
2. When merged, create a GitHub Release
3. Publish to npm

See CONTRIBUTING.md for commit conventions.