Skip to content

docs: Add missing upgrade steps for React Native and metro-config #1124

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Nitin-100 merged 1 commit into from
Jan 2, 2026
Merged

docs: Add missing upgrade steps for React Native and metro-config #1124

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 9 additions & 5 deletions docs/upgrade-app.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,18 @@ title: Upgrading App to Latest Version of React Native Windows
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).

### Steps to Upgrade An App to New React Native Windows Version via CLI
1. In the root of your project, run the [init-windows command](init-windows-cli.md) (make sure you're using the correct template).
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.
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:
1. Check the required React Native version for your target RNW version by running `npm view react-native-windows@<target-version> peerDependencies`.
2. Update React Native to match the required version by running `yarn add react-native@<required-version>`.
3. Update React Native Windows to your target version by running `yarn add react-native-windows@<target-version>`.
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.
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.
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.
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:

1. Add those changes manually.
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.
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.
4. Your app is now ready to build!
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.
9. Your app is now ready to build!

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