@rnue/cli

@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:

1. Discover all native modules in the dependencies of a rnue app.
2. Validate requirements put forth by the configuration.
3. Place the native modules as Unreal plugins in the specified Unreal project.
4. Modify the .uproject file to enable the added plugins.
5. 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]

Advanced usage#

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

1. 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:

   npmpnpmyarnbun

   Copy

   bashCopy

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

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

   {
     "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.
   fabricComponents	[]	Fabric component names that this package provides. The linker uses 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:

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

2. 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.

   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.

   Supported alternatives for the configuration filename

   The following filenames are correctly discovered by @rnue/cli:

   • rnue.config.ts
   • rnue.config.mts
   • rnue.config.cts
   • rnue.config.js
   • rnue.config.mjs
   • rnue.config.cjs

   Putting configuration in package.json

   Another alternative is putting the configuration in package.json under the rnueConfig key:

   {
       "rnueConfig": {
           "link": {
               "uprojectPath": "/Path/To/Game/MyGame.uproject",
               "pluginsFolder": "/Path/To/Game/Plugins",
               "mode": "copy"
           }
       }
   }

   Order of configuration resolution

   The CLI resolves each configuration field in the following order:

   1. Command line options
   2. The nearest rnue.config.* file
   3. The nearest package.json file with a rnueConfig
   4. Interactively prompted options

   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.

   Placement Modes

   Mode	Behavior
   link	Creates a symbolic link from the plugin located in the JavaScript dependencies to the provided Unreal project Plugins folder. This is especially useful during active development of a native module.
   copy	The CLI creates a physical plugin copy. Run the linker again after the package source changes.

   On macOS and Linux, link creates a project-local plugin directory with links to package-owned entries. Unreal writes generated state inside the project.

   On Windows, link creates a directory junction to the package plugin.

3. Running the link command#

   Run the package script from the rnue app:

   npmpnpmyarnbun

   Copy

   bashCopy

   $ 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.