api.md

API

Table of contents

1. Files
2. CLI
   1. Advanced options for monorepo
   2. RC file
      1. Hooks
      2. JS override
3. Javascript
4. Typescript
5. ios
   1. Build settings
   2. Info.plist
   3. Objective-C
6. Android
   1. build.gradle
   2. AndroidManifest.xml
   3. Java
7. Note about types

Files

Environment data can be read from both dotenv and YAML files. Latter are automaticlaly detected by CLI based on extension: .yaml or .yml.

Example of configuration in env file:

HELLO=world
TEST=100

Equivalent config with YAML:

HELLO: world
TEST: 100

Per platform values

When using YAML it is possible to specify values per platform:

HELLO: world
TEST: 100
API_KEY:
  ios: abcdef
  android: tuvxyz
  web: 123456

☝ both keys must exist in the mapping

CLI

Inject environment data with a single command:

npm	yarn
npm yarn rnuc .env	yarn rnuc .env

Advanced options for monorepo

1. --project-root: path to the root of the project for which injection is performed
2. --lib-root: path to where library is installed

Considering typical monorepo folder structure:

|-- package.json
|-- node_modules
    |-- react-native-ultimate-config
|-- packages
    |-- my_app
    |-- package1
    |-- package2
    |-- packageN

When injecting config for my_app the command should be:

yarn rnuc --project-root . --lib-root ../../node_modules/react-native-ultimate-config .env

RC file

Hooks

When file .rnucrc.js exists in project root it will be loaded when rnuc CLI is executed. A single function on_env will be invoked with env data loaded from the file. Object returned from the function will be used instead of original env data. When function returns undefined original data will be used.

module.exports = {
  on_env: async function (env) {
    // this will be invoked with data of loaded env file
  },
};

JS override

When rc file contains boolean field js_override react-native-ultimate-config will generate js code overriding values passed from native code. Scenarios why this may be needed

module.exports = {
  js_override: true,
};

Javascript

Get your values in javascript!

// import module
import config from "react-native-ultimate-config";

// access variables
config.MY_CONFIG;

Typescript

index.d.ts file is generated according to consumed environment

ios

Build settings

All values from env file are exposed to Build Settings.

Info.plist

All values from env file are exposed to Build Settings and therefore automatically available in info plist.

Example: set app name from config

env file:

APP_NAME=example

update info plist and observe app name changed:

Objective-c

#import <react-native-ultimate-config/ConfigValues.h>
...
NSLog(APP_NAME);

Android

Gradle plugin of a library injects environment variables into as:

1. BuildConfig entries
2. stirng resources
3. project.ext.env of build.gradle

build.gradle

you can access config variales with simple

project.config.get("APP_NAME")

AndroidManifest.xml

All values from environment are made available as resources and manifest placeholders

They are accessible as:

a string resource

      <activity
        ...
        android:label="@string/APP_NAME"
        />
        ...
      </activity>

a placeholder variable

      <activity
        ...
        android:label="${APP_NAME}"
        />
        ...
      </activity>

Java

All variables are exposed via BuilConfig. They are accessible as:

package com.example;

import android.os.Bundle;
import android.util.Log;
import com.facebook.react.ReactActivity;

public class MainActivity extends ReactActivity {

  /**
   * Returns the name of the main component registered from JavaScript. This is used to schedule
   * rendering of the component.
   */
  @Override
  protected String getMainComponentName() {
    return "example";
  }

  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    Log.d("onCreate", BuildConfig.APP_NAME);
  }

}

Web

Variables are exported as an object from react-native-ultimate-config:

// import module
import config from "react-native-ultimate-config";

// access variables
config.MY_CONFIG;

This functionality relies on the package.json browser field, see the quickstart guide for details.

Note about types

If yaml file is used for configuration then it is possible to pick up types of variables, however not every place can deal with all types or deal with types at all. Please consult with the following table to know what's available:

place	types available	notes
javascript	yes	-
infoplist	no	-
objective-c	yes	-
build.gradle	yes	-
AndroidManifest.xml	yes*	floating point values are available as @string resources since there are no such type available in resources: https://developer.android.com/guide/topics/resources/available-resources
Java	yes	-