Autolinking

Autolinking simply means executing in the RN frontend project:

npm install <library-with-native-dependencies> --save

After which native code or modules are automatically discovered, dependencies installed and compiled. For more about Autolinking, refer to:

In RNOH projects, to implement Autolinking functionality, it requires cooperation between RNOH framework, RN third-party libraries and RNOH project. The following sections describe the responsibilities and adaptation work for 3 roles. Choose the section based on your role.

You can also run AutolinkingSample to experience the entire process.

RNOH Framework (Framework Maintainers)

For this functionality, RNOH framework provides developers with a @rnoh/hvigor-plugin hvigor plugin (located in RNOH frontend project node_modules/@react-native-oh/react-native-harmony-cli/harmony directory). This plugin calls the link-harmony command in @react-native-oh/react-native-harmony-cli to complete HAR package installation, SO linking, Package registration and other manual linking operations.

The link-harmony command can be executed separately. Here are the parameters:

  • --harmony-project-path <path>: Specifies the relative path of harmony project, default is ./harmony;

  • --node-modules-path <path>: Specifies the relative path of node_modules, default is ./node_modules;

  • --cmake-autolink-path-relative-to-harmony <path>: Specifies the location where autolinking.cmake is generated, generated in harmony project, default is ./entry/src/main/cpp/autolinking.cmake;

  • --cpp-rnoh-packages-factory-path-relative-to-harmony <path>: Specifies the location where RNOHPackagesFactory.h is generated, generated in harmony project, default is ./entry/src/main/cpp/RNOHPackagesFactory.h;

  • --ets-rnoh-packages-factory-path-relative-to-harmony <path>: Specifies the location where RNOHPackagesFactory.ets is generated, generated in harmony project, default is ./entry/src/main/ets/RNOHPackagesFactory.ets;

  • --oh-package-path-relative-to-harmony <path>: Specifies the location of oh-package.json5, the link-harmony command modifies this file to install third-party HAR packages, default is ./oh-package.json5;

  • --exclude-npm-packages [string...]: Specifies the list of third-party libraries to skip Autolinking. By default link-harmony attempts to link all third-party libraries, but in some cases compilation errors may occur due to incorrect library configuration. Use this parameter to exclude such packages. Cannot be used with --included-npm-packages;

  • --include-npm-packages [string...]: Specifies the list of third-party libraries to execute Autolinking. By default link-harmony attempts to link all third-party libraries. Cannot be used with --excluded-npm-packages.

RN Third-party Libraries (Library Developers)

For RN third-party library developers, if you want the link-harmony command to automatically link your library, some adaptation work is needed. Here are the main changes, also refer to third-party-library-sample in AutolinkingSample.

package.json Changes

Library developers need to configure harmony.autolinking in package.json. harmony.autolinking usually requires an object with the following properties:

  • etsPackageClassName: ETS package class name. If not specified, it defaults to generating based on the name field in package.json. The rule is: [org name]+[package name]+Package, e.g., third-party-library-sample converts to ThirdPartyLibrarySamplePackage;

  • cppPackageClassName: C++ package class name. If not specified, follows the same generation rule as etsPackageClassName;

  • cmakeLibraryTargetName: Dynamic library name. If not specified, defaults to generating based on name field. The rule is: rnoh__+[org name]+[package name], e.g., third-party-library-sample converts to rnoh__third_party_library_sample;

  • ohPackageName: OHOS module name. Recommended to use the name field from HAR package's oh-package.json5. In some scenarios DevEco strictly validates this name. If not specified, defaults to generating based on name field. The rule is: @rnoh/+[org name]+--+[package name], e.g., third-party-library-sample converts to @rnoh/third-party-library-sample;

    {
     "harmony": {
       "autolinking": {
         "ohPackageName": "@rnoh/third-party-library-sample"
       }
     }
    }
    

    Multi-HAR package configuration (array format): When a library contains multiple HAR files, use array format to specify different ohPackage names for each HAR:

    {
      "harmony": {
        "autolinking": {
          "ohPackageName": [
            { "harName": "main.har", "packageName": "@scope/my-library" },
            { "harName": "sdk.har", "packageName": "@scope/my-library-sdk" }
          ]
        }
      }
    }
    
    • harName: HAR file name (only filename, no path)
    • packageName: Corresponding ohPackage name
    • Configuration order: The first HAR in the array is considered the main HAR, used for generating CMake add_subdirectory and import statements
    • Unmatched HARs use default naming: @rnoh/{npm-pkg-name}--{har-name}

    Remote dependency support: Array format supports configuring remote dependencies via version field, fetching HAR packages from OHPM repository:

    {
      "harmony": {
        "autolinking": {
          "ohPackageName": [
            { "harName": "local.har", "packageName": "@scope/local-lib" },
            { "harName": "remote.har", "packageName": "@ohos/remote-lib", "version": "1.0.0" }
          ]
        }
      }
    }
    
    • version: Optional field, specifies version number
      • With version: Generates version dependency (e.g., "@ohos/remote-lib": "1.0.0"), ohpm install downloads from remote repository
      • Without version: Generates file: path dependency (e.g., "@scope/local-lib": "file:../node_modules/..."), fetches from local node_modules
  • mainHarPath: Custom HAR scanning path, default is harmony. If HAR files are not in the default harmony directory, specify via this field:

    {
      "harmony": {
        "autolinking": {
          "mainHarPath": "custom/path/to/hars"
        }
      }
    }
    
    • Supports recursive scanning of all .har files in the specified directory and its subdirectories

If all names in your code follow the default rules and you have only a single HAR file, you can set harmony.autolinking to true.

HAR Package Requirements

  1. OHOS module needs a default export

    Like third-party-library-sample/harmony/library in AutolinkingSample, you need a default export in index.ets file:

    export { ThirdPartyLibrarySamplePackage as default } from './src/main/ets/ThirdPartyLibrarySamplePackage';
    
  2. HAR package location requirements

    • By default, HAR packages should be placed in [third-party-library]/harmony directory
    • If mainHarPath is configured, place them in the specified directory
    • Autolinking recursively scans all .har files in the directory and its subdirectories

Registering Custom TurboModule and ArkTS Components

In previous versions, custom ArkTS components required developers to pass them through wrappedCustomRNComponentBuilder parameter when creating RNInstance, which doesn't align with Autolinking design. Therefore, RNOH framework added the RNOHPackage class. Library developers can design their own ETS Package class by inheriting from RNOHPackage:

  • Override getUITurboModuleFactoryByNameMap method to register custom TurboModules in the module;

  • Override getAnyThreadTurboModuleFactoryByNameMap method to register custom Worker TurboModules in the module;

  • Override createWrappedCustomRNComponentBuilderByComponentNameMap method to register custom ArkTS components in the module.

RNOH Project (Developers Using RNOH Framework and RN Third-party Libraries)

Besides adapting RN third-party libraries, RNOH projects also need changes. Developers can refer to AutolinkingSample/NativeProject to read the following guidance.

  1. Install @rnoh/hvigor-plugin plugin (plugin location see above):