Skip to content

Commit f0859cc

Browse files
Nitin-100Nitin Chaudhary
andauthored
docs: Add missing upgrade steps for React Native and metro-config (#1124)
## Description - Add step to check peer dependencies before upgrading - Add step to update react-native to match RNW peer dependency - Add step to update react-native-windows - Add step to update @react-native/metro-config dev dependency - Clarify importance of --overwrite flag for metro.config.js - Add Troubleshooting section for common upgrade issues: - Metro API mismatch error - ERR_UNSUPPORTED_ESM_URL_SCHEME on Windows These steps were discovered during testing migration from 0.80 to 0.81 where Metro would fail without the @react-native/metro-config update. ### Why Failure of upgrading apps from 0.80 to 0.81 ###### Microsoft Reviewers: [Open in CodeFlow](https://microsoft.github.io/open-pr/?codeflow=https://github.com/microsoft/react-native-windows-samples/pull/1124) Co-authored-by: Nitin Chaudhary <nitchaudhary@microsoft.com>
1 parent fb5086a commit f0859cc

File tree

1 file changed

+9
-5
lines changed

1 file changed

+9
-5
lines changed

docs/upgrade-app.md

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,14 +9,18 @@ title: Upgrading App to Latest Version of React Native Windows
99
Upgrading your app to new React Native Windows versions requires a small amount of effort, but we will try to streamline this process for you as much as possible in this guide. You have two main options for how to upgrade your React Native Windows app. You can use the [init-windows command](init-windows-cli.md) or manually upgrade using [Upgrade Helper](https://reactnative.dev/docs/upgrading#upgrade-helper).
1010

1111
### Steps to Upgrade An App to New React Native Windows Version via CLI
12-
1. In the root of your project, run the [init-windows command](init-windows-cli.md) (make sure you're using the correct template).
13-
2. In the root of your project, run the [autolink-windows command](autolink-windows-cli.md) to link any native modules used by your app.
14-
3. Step 1 will overwrite any changes you previously made to the native Windows code of your project and generate a new GUID. If you made changes to this code or wish to keep your previous GUID, you have two options:
12+
1. Check the required React Native version for your target RNW version by running `npm view react-native-windows@<target-version> peerDependencies`.
13+
2. Update React Native to match the required version by running `yarn add react-native@<required-version>`.
14+
3. Update React Native Windows to your target version by running `yarn add react-native-windows@<target-version>`.
15+
4. Update the `@react-native/metro-config` dev dependency to match your React Native version by running `yarn add --dev @react-native/metro-config@<react-native-version>`. This step is required to avoid Metro startup errors.
16+
5. In the root of your project, run the [init-windows command](init-windows-cli.md) (make sure you're using the correct template). The `--overwrite` flag updates `metro.config.js` and other configuration files required for the new version.
17+
6. In the root of your project, run the [autolink-windows command](autolink-windows-cli.md) to link any native modules used by your app.
18+
7. Step 5 will overwrite any changes you previously made to the native Windows code of your project and generate a new GUID. If you made changes to this code or wish to keep your previous GUID, you have two options:
1519

1620
1. Add those changes manually.
1721
2. If your project is a Git repository, open the project in Visual Studio Code and navigate to the Source Control tab. There, you can undo the specific overwrite edits that erased your changes.
18-
3. The upgrade script will not remove any files that were removed from the new template. To check if there are any files that require manual deletion, use [Upgrade Helper](https://react-native-community.github.io/upgrade-helper/). See the section below for the steps on how to use this tool.
19-
4. Your app is now ready to build!
22+
8. The upgrade script will not remove any files that were removed from the new template. To check if there are any files that require manual deletion, use [Upgrade Helper](https://react-native-community.github.io/upgrade-helper/). See the section below for the steps on how to use this tool.
23+
9. Your app is now ready to build!
2024

2125
### Steps to Manually Upgrade An App to New React Native Windows Version via Upgrade Helper
2226
1. Open [Upgrade Helper](https://react-native-community.github.io/upgrade-helper/) in your preferred browser.

0 commit comments

Comments
 (0)