Ggyangedocs(Docs): optimize the docs structure

RN Framework Version Upgrade Guide

This document provides guidance for two upgrade scenarios: Minor Version Upgrade (e.g., 0.72.x to 0.72.y) and Major Version Upgrade (e.g., 0.72.x to 0.77.x and 0.77.x to 0.82.x).

Minor Version Upgrade

Note: If you were previously using local dependencies, please first refer to How to switch from local dependencies to remote dependencies to make the switch.

According to the version number in Release Notes, upgrade the version of @rnoh/react-native-openharmony in the dependencies field of all oh-package.json5 files.
Click File->Sync and Refresh Project to install the new dependencies.
Upgrade the version of @react-native-oh/react-native-harmony in the package.json in the root directory of the RN project.
Re-run npm i in the root directory of the RN project.

How to switch from local dependencies to remote dependencies

In native project

Delete the dependencies field in entry/oh-package.json5, example:

{
...
  "dependencies": {
- "@rnoh/react-native-openharmony": "./libs/react_native_openharmony-X.X.X.X.har"
  },
...
}

In the entry directory, run the following command:

ohpm i @rnoh/react-native-openharmony@x.x.x

In RN project

Delete the dependencies field in the package.json in the root directory of the RN project, example:

...
  "dependencies": {
- "react-native-harmony": "file:../react-native-harmony/rnoh-react-native-harmony-x.x.x.tgz",
  },
...

In the AwesomeProject directory, run the following command to install the dependency:

npm i @react-native-oh/react-native-harmony@x.x.x

yarn add @react-native-oh/react-native-harmony@x.x.x

Modify the metro.config.js file, for example:

...
-  const {createHarmonyMetroConfig} = require('react-native-harmony/metro.config');
+  const {createHarmonyMetroConfig} = require('@react-native-oh/react-native-harmony/metro.config');
...
  module.exports = mergeConfig(getDefaultConfig(__dirname), createHarmonyMetroConfig({
-    reactNativeHarmonyPackageName: 'react-native-harmony',
+    reactNativeHarmonyPackageName: '@react-native-oh/react-native-harmony',
  }), config);

Note: If the imported package depends on other packages, please refer to How to import rnoh dependencies in third-party libraries or custom modules.

How to use local installation of HarmonyOS dependencies

In native project

Place the dependency package in a custom path, example: NativeProject/libs/react_native_openharmony-X.X.X.X.har.
Modify the dependencies field in entry/oh-package.json5, example:

{
...
  "dependencies": {
+ "@rnoh/react-native-openharmony": "./libs/react_native_openharmony-X.X.X.X.har"
  },
...
}

In RN project

Modify the dependencies field in the package.json in the root directory of the RN project, example:

...
  "dependencies": {
+ "react-native-harmony": "file:../react-native-harmony/rnoh-react-native-harmony-x.x.x.tgz",
  },
...

Ensure that there is a folder named react-native-harmony-cli in the parent directory where your rnoh-react-native-harmony-x.x.x.tgz file is located, and place the corresponding version of rnoh-react-native-harmony-cli-x.x.x.tgz file in that folder.
Modify the metro.config.js file, for example:

...
-  const {createHarmonyMetroConfig} = require('@react-native-oh/react-native-harmony/metro.config');
+  const {createHarmonyMetroConfig} = require('react-native-harmony/metro.config');
...
  module.exports = mergeConfig(getDefaultConfig(__dirname), createHarmonyMetroConfig({
-    reactNativeHarmonyPackageName: '@react-native-oh/react-native-harmony',
+    reactNativeHarmonyPackageName: 'react-native-harmony',
  }), config);

Note: If the imported package depends on other packages, please refer to How to import rnoh dependencies in third-party libraries or custom modules.

Major Version Upgrade

This section provides guidance for different major version upgrade scenarios:

Upgrading from 0.72.x to 0.77.x
Upgrading from 0.77.x to 0.82.x

Upgrading from 0.72.x to 0.77.x

This section describes how to upgrade a RN project for OpenHarmony from 0.72.x to 0.77.x

Upgrade RN project dependency versions

The following are required dependencies to upgrade:

{
    ...
    "dependencies": {
        "react": "18.3.1",
        "react-native": "0.77.1"
    },
    "devDependencies": {
        "@react-native-community/cli": "15.0.1",
        "@react-native/babel-preset": "0.77.1",
    },
}

If any of the above dependencies are missing in your 0.72 project, add them and ensure the versions match those listed.
metro-react-native-babel-preset is no longer needed due to upstream refactoring and can be removed.
The upstream community has also upgraded some development dependencies, which you may choose to follow:

{
    ...
    "devDependencies": {
        "@babel/core": "^7.25.2",
        "@babel/preset-env": "^7.25.3",
        "@babel/runtime": "^7.25.0",
        "@react-native-community/cli-platform-android": "15.0.1",
        "@react-native-community/cli-platform-ios": "15.0.1",
        "@react-native/eslint-config": "0.77.1",
        "@react-native/metro-config": "0.77.1",
        "@react-native/typescript-config": "0.77.1",
        "@types/jest": "^29.5.13",
        "@types/react": "^18.2.6",
        "@types/react-test-renderer": "^18.0.0",
        "eslint": "^8.19.0",
        "jest": "^29.6.3",
        "prettier": "2.8.8",
        "react-test-renderer": "18.3.1",
        "typescript": "5.0.4"
    }

}

Tip: In VSCode, you can copy all devDependencies to the devDependencies of the project to be upgraded. Duplicate keys will be underlined; delete the old ones to complete the dependency addition and upgrade.

Upgrade/add RNOH frontend dependencies. Afterward, run npm i to install dependencies.
- Upgrade dependencies: "react-native-harmony" or "@xxx/react-native-harmony"
  
  Note: Keep the original package name. If the original react-native-harmony did not have an @organization prefix, do not add one when upgrading. If it had one, keep the previous "@xxx/react-native-harmony" name.
- Add devDependencies: "@react-native-oh/react-native-harmony-cli"
- For version numbers, see RNOH Version Planning
Modify two configurations (the second is optional). Only change the fields listed below:
1. babel.config.js
  - If the file exists, modify the presets field in module.exports, replacing 'module:metro-react-native-babel-preset' with 'module:@react-native/babel-preset'.
  - If the file does not exist, create it as follows:
```
module.exports = {
  presets: ['module:@react-native/babel-preset'],
};
```
2. (Optional) tsconfig.json
  - Add devDependencies "@react-native/typescript-config": "0.77.1" in package.json
  - Change the extends field in tsconfig.json to:
```
{
    "extends": "@react-native/typescript-config/tsconfig.json"
}
```
Build the frontend bundle
Update the @rnoh/react-native-openharmony dependency version in all oh-package.json5 files in the OpenHarmony project. For version numbers, see RNOH Version Planning
In the OpenHarmony project directory, run ohpm i or in DevEco Studio, click File->Sync and Refresh Project to install dependencies.
Build the application hap package, install, and test.

References:

Upgrading from 0.77.x to 0.82.x

This section describes how to upgrade a RN project for OpenHarmony from 0.77.x to 0.82.x

Upgrade RN project dependency versions

The following are required dependencies to upgrade:

{
    ...
    "dependencies": {
        "react": "19.1.1",
        "react-native": "0.82.1"
    },
    "devDependencies": {
        "@react-native-community/cli": "20.0.0",
        "@react-native/babel-preset": "0.82.1",
    },
}

If any of the above dependencies are missing in your 0.77 project, add them and ensure the versions match those listed.
The upstream community has also upgraded some development dependencies, which you may choose to follow:

{
    ...
    "devDependencies": {
        "@babel/core": "^7.25.2",
        "@babel/preset-env": "^7.25.3",
        "@babel/runtime": "^7.25.0",
        "@react-native-community/cli-platform-android": "20.0.0",
        "@react-native-community/cli-platform-ios": "20.0.0",
        "@react-native/eslint-config": "0.82.1",
        "@react-native/metro-config": "0.82.1",
        "@react-native/typescript-config": "0.82.1",
        "@types/jest": "^29.5.13",
        "@types/react": "^19.1.0",
        "@types/react-test-renderer": "^19.1.0",
        "eslint": "^8.19.0",
        "jest": "^29.7.0",
        "prettier": "3.3.0",
        "react-test-renderer": "18.3.1",
        "typescript": "^5.5.4"
    }
    
}

Tip: In VSCode, you can copy all devDependencies to the devDependencies of the project to be upgraded. Duplicate keys will be underlined; delete the old ones to complete the dependency addition and upgrade.

Upgrade/add RNOH frontend dependencies. Afterward, run npm i to install dependencies. If you encounter dependency conflict errors, you can adjust the version of the dependency library in package.json according to the error message to resolve.
- Upgrade dependencies: "react-native-harmony" or "@xxx/react-native-harmony"
  
  Note: Keep the original package name. If the original react-native-harmony did not have an @organization prefix, do not add one when upgrading. If it had one, keep the previous "@xxx/react-native-harmony" name.
- Ensure devDependencies includes: "@react-native-oh/react-native-harmony-cli"
Check and update configuration files
1. babel.config.js
  - Confirm that the presets field in module.exports uses 'module:@react-native/babel-preset'
```
module.exports = {
  presets: ['module:@react-native/babel-preset'],
};
```
When building the frontend bundle, if you encounter dependency conflict errors, you can modify configuration files such as package.json, metro.config.js, babel.config.js and adjust them according to the error prompts.

During the upgrade process, the upstream React Native community has introduced some breaking changes that developers need to adapt to. Common breaking changes include but are not limited to:

Refs Deprecation: String refs have been deprecated and will be officially removed in React 19. (https://github.com/facebook/react-native/commit/223e98cc4b656b94b48c88940114bfdc025f8ddf)
NewAppScreen Component Redesigned and Migrated: NewAppScreen has been redesigned and migrated to react-native/new-app-screen. (https://github.com/facebook/react-native/commit/3cf01020071c76f40499878674cc7aaf5dbe168a)
Changes to infolog: The infoLog has been removed from the react-native package. (https://github.com/facebook/react-native/commit/8a0cfec81584e966c9e6ea0f5e438022e0129bcd)
ReactNativeFeatureFlags Changes: ReactNativeFeatureFlags has been moved to src/private. (https://github.com/facebook/react-native/commit/fb4587780e8d6111139d73598a9a26ff392dee28)

Be sure to check the upstream community's detailed change notes to understand the complete list of breaking changes. For specific breaking change details, please refer to the upstream community documentation in the references section below.

References: