cookbook.md

Cookbook

collection of recipes how react-native-ultimate-config can be used for typical tasks

☝️ most of the recipes assume default template of react-native app (single target/scheme on ios and no flavors on android) unless stated otherwise

Table of contents

1. Application name
2. Bundle identifier
3. Deeplink
4. Using multiple schemes (ios)
5. Using multiple flavors (android)
6. Generate fastlane dotenv
7. Override native values in js

Application name

1. Declare env variable APP_NAME=RNUC Demo
2. Initialize config yarn rnuc .env
3. Configure native projects

iOS

1. open xcode

2. go to "Info" tab

3. find entry "Bundle Display Name"

4. replace it with ${APP_NAME}

   

5. checkout app name has changes

   

Android

1. open android/app/src/main/AndroidManifest.xml

2. find tag application and set attribute android:label to @strings/APP_NAME or ${APP_NAME}

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

   or

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

Bundle identifier

1. Declare env variable BUNDLE_ID=com.awesomern.app
2. Initialize config yarn rnuc .env
3. Configure native projects

ios

1. open xcode

2. go to "Build Settings" tab

3. find entry "PRODUCT_BUNDLE_IDENTIFIER"

4. replace it with ${BUNDLE_ID}

   

5. checkout bunle id has changed

Android

1. open android/app/build.gradle
2. set bundle id with data from config:

android {
    ...
    defaultConfig {
        applicationId project.config.get("BUNDLE_ID")
        ...
    }
}

Deeplink

Suppose you want your app to open links with scheme "awesomeapp://"

1. declare env variable DEEPLINK_SCHEME=awesomeapp

iOS

1. get familiar with official guide
2. open xcode
3. go to "Info" tab
4. find section "URL Types" and press "+"
5. in "scheme" field type ${DEEPLINK_SCHEME}

Android

1. get familiar with official guide

2. open android/app/src/main/AndroidManifest.xml

3. add intent filter according to the guide and configure scheme using variable:

   <activity>
       ...
       <intent-filter>
           ...
           <data android:scheme="${DEEPLINK_SCHEME}" />
       </intent-filter>
   </activity>

Using multiple schemes (ios)

️❗❗❗This recipe has experimental support and may not cover all edge cases. If your project is using multiple schemes you may still use library via cli without this recipe.

⚠️️⚠️️⚠️️ With this approach xcode project remains uninitialized until you build it first time. Until project is built some UI elements may dispay empty values (like app name or bundle id)

⚠️️⚠️️⚠️️ While this approach is suitable in certain scenarios make sure you know exactly why do you need multiple schemes in first place. This library lets you avoid creating unnecessary native schemes/targets in many scenarios.

Using multiple schemes it is possible to avoid using cli tool manually when building specific environment. This is possible by defining pre-build script phase in a scheme.

1. open schemes of the project

   

2. ensure scheme is shared (otherwise it will not be committed)

   

3. go to scheme details

   

4. add Script "Pre-action" for "Build" action. ⚠️ make sure to select "Provide build settings from.."

5. paste the following code

   if [ -d "$HOME/.nvm" ]; then
       export NVM_DIR="$HOME/.nvm"
       [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
   fi
   
   RN_ROOT_DIR=$(dirname "$PROJECT_DIR")
   
   cd "$RN_ROOT_DIR"
   yarn run rnuc ".env.yaml"
   #or
   #npm run rnuc ".env.yaml"

   

6. you can now duplicate scheme per every environment you use and change name of the file that is used for rnuc command.

Using multiple flavors (android)

️❗❗❗This recipe has experimental support and may not cover all edge cases. If your project is using multiple flavors you may still use library via cli without this recipe. ️❗Typescript typings are not available for this setup at the moment.

⚠️️⚠️️⚠️️ While this approach is suitable in certain scenarios make sure you know exactly why do you need multiple flavors in first place. This library lets you avoid creating unnecessary native flavors in many scenarios.

Assuming you want to support multiple flavors of the app: "dev" and "staging".

1. Define flavor => env mapping in android/app/build.gradle

   project.ext.flavorEnvMapping = [
       dev: "../.env.yaml",
       staging: "../.env.staging.yaml"
   ]

   ️️⚠️️ only yaml files are supported here

2. Define some flavors (or you may already have them defined)

    flavorDimensions "default"
    productFlavors {
        dev{
        }
        staging{
        }
    }

3. Done. If you run (cd android; ./gradlew/assembleDebug) it will properly pick up all configs per flavor names. Whenever gradle is configuring tasks it will read env data from files and populate resources, build config and manifest placeholders from them.

Generate fastlane dotenv

1. Create rc file touch .rnucrc.js

2. Add hook code:

   const fs = require("fs");
   module.exports = {
     on_env: async function (env) {
       if (fs.existsSync("./ios/fastlane")) {
         const writer = fs.createWriteStream("./ios/fastlane/.env");
         for (const key in env) {
           writer.write(`${key}=${env[key]}\n`);
         }
         writer.close();
       }
       // repeat for android
     },
   };

Override native values in js

Sometimes you may need to make config values generated in javascript as opposed to consuming them from native. For example if you want to benefit from fast code reload (without recompilation) with metro or to use over-the-air deploys with services like codepush.

This can be achieved with rc config: js_override:

// rnuc.rc
module.exports = {
  js_override: true,
};

In this case react-native-ultimate-config will embed all config values into javascript code overriding values from native.

NOTE: This feature does not apply to web projects which do not use native values either way. See the quickstart guide for help configuring react-native-ultimate-config for use in a web project.