The Problem

Managing environment variables in React Native is painful:

❌ Different config files for iOS and Android
❌ Separate setup for each platform
❌ Type-unsafe string values
❌ No support for New Architecture
❌ Existing solutions are unmaintained

The Solution

One config file. Every platform. Type-safe. Just works.

# Create your config
echo "API_URL=https://api.myapp.com" > .env

# Generate for all platforms
npx rncu .env

# Use everywhere ✨

import Config from 'react-native-config-ultimate';

// TypeScript knows your config shape!
console.log(Config.API_URL); // https://api.myapp.com

Why Choose This Library?

• New Architecture ready
• TurboModules support
• React Native 0.73+
• React 18 & 19

• iOS (Swift, Obj-C)
• Android (Kotlin, Java)
• Web (RN Web, Vite)

• Auto-generated .d.ts
• Strict TypeScript
• Schema validation
• Zero any types

Comparison

| Feature | react-native-config-ultimate | react-native-config | react-native-dotenv | |---------|:----------------------------:|:-------------------:|:-------------------:| | New Architecture | ✅ | ❌ | ❌ | | React Native 0.79+ | ✅ | ⚠️ | ⚠️ | | Web support | ✅ | ❌ | ✅ | | YAML config | ✅ | ❌ | ❌ | | Per-platform values | ✅ | ❌ | ❌ | | Type-safe | ✅ | ⚠️ | ⚠️ | | Multi-env merging | ✅ | ❌ | ❌ | | Schema validation | ✅ | ❌ | ❌ | | Native code access | ✅ | ✅ | ❌ | | Active maintenance | ✅ | ⚠️ | ⚠️ |

Quick Start

1. Install

npm install react-native-config-ultimate
# or
yarn add react-native-config-ultimate
# or
pnpm add react-native-config-ultimate

2. Create config file

Option A: .env (simple)

API_URL=https://api.myapp.com
APP_NAME=MyApp
DEBUG_MODE=true
VERSION=1.0.0

Option B: .env.yaml (powerful)

API_URL: https://api.myapp.com
APP_NAME: MyApp
DEBUG_MODE: true
VERSION: 1.0.0

# Per-platform values 🎯
APP_ICON:
  ios: AppIcon
  android: ic_launcher

3. Setup native projects

📱 iOS — Setup Guide
🤖 Android — Setup Guide

4. Generate & use

npx rncu .env
# or
npx rncu .env.yaml

import Config from 'react-native-config-ultimate';

function App() {
  return (
    <View>
      <Text>API: {Config.API_URL}</Text>
      <Text>Version: {Config.VERSION}</Text>
      {Config.DEBUG_MODE && <Text>🐛 Debug Mode</Text>}
    </View>
  );
}

That's it! Full guide: Quickstart →

5. TypeScript Setup (recommended)

Out of the box, Config.API_URL resolves to a generic string | number | boolean because the library cannot know your env keys at publish time. To get fully typed access with autocomplete and compile-time errors on typos, drop this 5-line augmentation file into your project once:

// rncu-types.d.ts (at your project root, committed to git)
declare module 'react-native-config-ultimate' {
  import type { ConfigVariables } from 'react-native-config-ultimate/index';
  const Config: ConfigVariables;
  export default Config;
}

How it works: every time you run npx rncu, the CLI regenerates node_modules/react-native-config-ultimate/index.d.ts with a ConfigVariables interface containing your exact keys (HELLO: string, PORT: number, DEBUG: boolean, etc.). The augmentation above pulls that interface in and types the default export with it.

You only write this file once. The keys evolve via rncu; your augmentation stays stable.

If your tsconfig.json uses "include": ["src"] (or any pattern that excludes the project root), either add "rncu-types.d.ts" to include or move the file inside src/.

Features

Merge multiple env files — great for staging, production, etc:

npx rncu .env.base .env.staging

Later values override earlier ones.

Reference other variables:

BASE_URL=https://api.myapp.com
API_URL=$BASE_URL/v1
AUTH_URL=$BASE_URL/auth

Fail fast if required vars are missing:

// .rncurc.js
module.exports = {
  schema: {
    API_URL: { type: 'string', required: true },
    DEBUG_MODE: { type: 'boolean', default: false },
  }
};

Different values for iOS/Android/Web:

APP_STORE_URL:
  ios: https://apps.apple.com/app/myapp
  android: https://play.google.com/store/apps/details?id=com.myapp
  web: https://myapp.com

Transform values at build time:

// .rncurc.js
module.exports = {
  on_env: (env) => ({
    ...env,
    BUILD_TIME: new Date().toISOString(),
  })
};

Auto-regenerate on changes:

npx rncu .env --watch

How It Works

The CLI reads your .env / .env.yaml at build time, generates platform-specific files (rncu.xcconfig for iOS, BuildConfig fields for Android, typed JS for the runtime), and your app reads the values natively at startup.

📊 See the full architecture diagram with technology stack on the docs site →

The diagram is intentionally hosted on the docs site (which renders Mermaid) instead of inlined here, because the npm package page does not render Mermaid blocks and the source would otherwise appear as raw text to anyone reading the package on npmjs.com.

Access Everywhere

Your config is available in every layer of your app:

| Layer | iOS | Android | |:------|:----|:--------| | JavaScript / TypeScript | Config.API_URL | Config.API_URL | | Native Code | UltimateConfig.API_URL (Swift / Obj-C) | BuildConfig.API_URL (Kotlin / Java) | | Build Settings | $(API_URL) — Xcode Build Settings, Info.plist | ${API_URL} — AndroidManifest.xml, build.gradle |

Examples:

// Swift
let apiUrl = UltimateConfig.API_URL

// Kotlin
val apiUrl = BuildConfig.API_URL

<!-- AndroidManifest.xml -->
<meta-data android:name="api_url" android:value="${API_URL}" />

Compatibility

| Version | React Native | React | Gradle | Architecture | |:-------:|:------------:|:-----:|:------:|:------------:| | 0.2.x | ≥ 0.73 | ≥ 18 | ≥ 8 | ✅ New (TurboModules) |

Need older RN support? See react-native-ultimate-config

Documentation

| 📖 Guide | Description | |:---------|:------------| | Quickstart | Installation and setup | | API Reference | JavaScript, native code, build tools | | Migration Guide | From react-native-config | | Cookbook | Common patterns and recipes | | Testing | Mocking Config in tests | | Monorepo Tips | pnpm, yarn workspaces, Lerna | | Troubleshooting | Common issues and solutions |

Examples

| Project | React Native | Platforms | Description | |:--------|:------------:|:---------:|:------------| | example | 0.83 | iOS, Android | Full native app with YAML | | Example079 | 0.79 | iOS, Android, Web | Native + Vite web | | example-web | — | Web | Standalone Vite + RN Web |

Frequently Asked Questions

JavaScript: No, just re-run npx rncu .env and reload the app.

Native values (Info.plist, AndroidManifest): Yes, you need to rebuild.

Use multi-file merging:

npx rncu .env.base .env.production

Or use separate commands in your package.json:

{
  "scripts": {
    "env:dev": "rncu .env.dev",
    "env:prod": "rncu .env.prod"
  }
}

Yes! This is a community fork that adds New Architecture support, React 19 compatibility, and ongoing maintenance. See CONTRIBUTING.md.

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

git clone https://github.com/javier545dev/react-native-config-ultimate.git
cd react-native-config-ultimate
pnpm install
pnpm test
pnpm build

Credits

This is a community-maintained fork of react-native-ultimate-config. Full credit to Max for the original design and years of maintenance. The MIT license is preserved.

License

MIT License — see LICENSE for details.