rnx-kit/incubator/build

@rnx-kit/build

🚧🚧🚧🚧🚧🚧🚧🚧🚧🚧🚧

This tool is EXPERIMENTAL - USE WITH CAUTION

🚧🚧🚧🚧🚧🚧🚧🚧🚧🚧🚧

An experimental tool for building your apps in the cloud.

Requirements

• Node.js LTS 18.12 or greater

Feature	Android	iOS	macOS	Windows
Build with Azure DevOps	🚧	🚧	🚧	🚧
Build with GitHub Actions	✓	✓	✓	✓
Launch in device (local)	✓¹	✓²	✓	✓
Launch in emulator/simulator	✓¹	✓²	-	-
Launch from QR code	✓	🚧	-	-

1. Requires Android Studio
2. Requires Xcode

Usage

npm run rnx-build --platform <platform>

-p, --platform

Target platform to build for.

Supported platforms are android, ios, macos, windows.

--deploy (optional)

Where builds should be deployed from. For how to configure your app distribution service, please see Distribution.

Supported deployment methods are remote-first, local-only.

Defaults to remote-first.

--device-type (optional)

Target device type. This is currently only implemented for iOS.

Supported device types are device, emulator, simulator.

Specifying emulator/simulator implies --deploy local-only.

Defaults to simulator.

--package-manager (optional)

Binary name of the package manager used in the current repo.

Defaults to npm, pnpm, or yarn if detected.

--project-root (optional)

Path to the root of the project.

Defaults to current working directory.

--scheme (optional)

The workspace scheme to build (iOS and macOS only).

Defaults to ReactTestApp.

Distribution

Android: Local Deployment

In order to launch the build artifact on device, you need to install Android Studio. Once installed, go into Preferences ❭ Appearance & Behavior ❭ System Settings ❭ Android SDK, and install Android SDK Build-Tools and Android SDK Platform-Tools.

If you want to run apps on the Android Emulator, follow the instructions here: Run apps on the Android Emulator.

iOS: Install Signing Certificate and Provisioning Profile

In order to launch the build artifact on device, you need to install Apple signing certificate and provisioning profile on your host of choice.

For GitHub, please follow the steps to create the four secrets here: Creating secrets for your certificate and provisioning profile

Plugins

@rnx-kit/build's remote app distribution is enabled by plugins. A plugin is configured by the rnx-kit.build.distribution key in package.json. It takes a tuplet, the module name and an options object. For instance, the Firebase plugin may be configured like below:

{
  ...
  "rnx-kit": {
    "build": {
      "distribution": [
        "@rnx-kit/build-plugin-firebase",
        {
          "appId": {
            "android": "1:1234567890:android:0a1b2c3d4e5f67890",
            "ios": "1:1234567890:android:0a1b2c3d4e5f67890"
          }
        }
      ]
    },
  }
}

The options object is passed to the plugin on load:

import type { DistributionPlugin, Platform } from "@rnx-kit/build";

type Config = {
  appId: string | Partial<Record<Platform, string>>;
};

module.exports = (config: Partial<Config>): DistributionPlugin => {
  ...
};

GitHub Actions

Personal Access Token

To use @rnx-kit/build with GitHub Actions, you need to make a fine-grained access token with the action:write permission. When creating a new access token, make sure Repository permissions ❭ Actions is set to Read and write. Create a JSON config file and paste in the token like below:

{
  "github": {
    "token": "github_pat_0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
  }
}

Save the file in one of the following locations depending on your platform:

Platform	Location
macOS	$HOME/Library/Preferences/rnx-build-nodejs/config.json
Windows	%AppData%\Roaming\rnx-build-nodejs\config.json
Linux	$XDG_CONFIG_HOME/rnx-build-nodejs/config.json

For how to create a personal access token, see: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token

Actions Permissions

If your Actions permissions is restricted, you need to allow the following actions and reusable workflows:

actions/cache@*,
actions/checkout@*,
actions/download-artifact@*,
actions/setup-java@*,
actions/setup-node@*,
actions/upload-artifact@*,
gradle/actions/setup-gradle@*,
microsoft/react-native-test-app/.github/actions/*,
microsoft/setup-msbuild@*,
ruby/setup-ruby@*,

You can find this setting under Settings ❭ Code and automation ❭ Actions ❭ General. Make sure permissions is set to Allow enterprise, and select non-enterprise, actions and reusable workflows.

Assumptions

Folder Structure

Workflows currently assume that your project has a folder structure similar to the one generated by react-native init, e.g.:

app
├── android
│   ├── gradlew
│   └── gradlew.bat
├── ios
│   └── Podfile
├── macos
│   └── Podfile
├── windows
│   └── App.sln
├── package.json
└── src

Contributing

If you want to help making this tool more feature complete, check out the project board.