@rnue/cli

Command line utilities to help with React Native for Unreal Engine development workflows.

@rnue/cli is a command line utility toolbelt.

Currently its main function is the link command that installs native TurboModules as plugins in your Unreal project.

Simple usage

The simplest way to start using @rnue/cli is by calling in in an rnue app:

npx @rnue/cli link

The link command will prompt you interactively for the options it needs in order to properly link the native modules to your Unreal project.

Once invoked the link command will perform the following operations:

Discover all native modules in the dependencies of a rnue app.
Validate requirements put forth by the configuration.
Place the native modules as Unreal plugins in the specified Unreal project.
Modify the .uproject file to enable the added plugins.
Write managed state to Saved/RNUE/LinkState.json.

Reference

You can also provide all the options as commandline options and run the command headlessly.

npx @rnue/cli link [uproject-path] [options]

Option	Description
`--uproject <path>`	Path to the Unreal project's `.uproject` file or the folder that contains it. This option overrides the positional path.
`--plugins-folder <path>`	The preferred plugins folder. This option is only relevant if the target `.uproject` file has defined a `AdditionalPluginDirectories` setting.
`--mode link\|copy`	Placement mode.
`--dry-run`	Show planned changes without writing files.
`--prune`	Remove plugins that `rnue` manages but no longer exist as dependencies of the `rnue` app. This option also restores their managed `.uproject` entries.
`--accept-uproject-rewrite`	Permit a noninteractive rewrite of the `.uproject` JSON document.

@rnue/cli link re-serializes the complete .uproject JSON document when plugin references change. This operation can change whitespace. Without --accept-uproject-rewrite, an interactive terminal will ask for approval. A noninteractive terminal will stop without writing anything to the target Unreal project.

Advanced usage

You can run @rnue/cli manually. A package script is more convenient for repeated use in a production environment.

Pin a specific `@rnue/cli` version as a development dependency

Install the package as a development dependency of the rnue app to make it discoverable by your package manager:

npm i --save-dev @rnue/cli@0.0.3

You can refer to it in the scripts section as rnue:

package.json

{
  "scripts": {
    "link:unreal": "rnue link"
  }
}

In order to be discovered, a native module must be listed as a dependency in the package.json of the rnue app. Additionally, a react-native.config.js file must be present in the native module's package.

Field	Default	Description
`pluginPath`	Required	An Unreal Engine plugin generated by @rnue/codegen.
`buildModules`	All descriptor modules	Unreal modules that the package exposes for build integration. Each name must exist in the plugin descriptor.
`turboModules`	`[]`	TurboModule names that this package provides. The linker will use this field to reject collisions.
`requiresPackages`	`{}`	Required JavaScript packages and semantic-version ranges. The linker will validate those against the application's dependencies listed in `package.json`.

Here is an example configuration:

react-native.config.js

"use strict";

module.exports = {
  dependency: {
    platforms: {
      unreal: {
        pluginPath: "./unreal/ExampleNative",
        buildModules: ["ExampleNative"],
        turboModules: ["ExampleNative"],
        requiresPackages: {},
      },
    },
  },
};

Configure the location of the target Unreal project

Create an rnue.config.ts file in the root of your rnue app:

Relative paths start from the directory that contains the configuration file.

rnue.config.ts

export default {
  link: {
    uprojectPath: "/Path/To/Game/MyGame.uproject",
    pluginsFolder: "/Path/To/Game/Plugins",
    mode: "link",
  },
};

You can also use environment variables in the config file to make this configuration portable between multiple development and build environments.

`rnue.config.ts` reference

Field	Default	Description
`uprojectPath`	Interactive prompt	A `.uproject` file or a directory that contains exactly one `.uproject` file.
`pluginsFolder`	Project `Plugins` directory or prompt	The project `Plugins` directory or an existing `AdditionalPluginDirectories` entry in the `.uproject` file. If this value is not provided and multiple options exist, the CLI will interactively prompt for a specific choice.
`mode`	`link`	`link` or `copy`. The plugin placement mode.

Running the link command

Run the package script from the rnue app:

npm exec -- rnue link

Managed state and safety

@rnue/cli link uses Saved/RNUE/LinkState.json to identify the plugin directories and project entries that it manages.

The linker will refuse to replace an unmanaged directory or a managed plugin that changed outside of rnue.

The linker stages plugin updates before installation. It restores applied updates when an operation fails.

--prune only removes plugins recorded in managed state. Without this option, undiscovered managed plugins remain in place.

The command can edit the following items:

Plugin directories under the selected destination
The Plugins entries in the .uproject file
Saved/RNUE/LinkState.json

The command does not edit Unreal source files, module rules, or target files. It does not add plugin search directories.

@rnue/cli

Supported alternatives for the configuration filename

Putting configuration in package.json

Order of configuration resolution

Placement Modes

On this page