[Do Not Merge] Upgrade Website to 0.81 #1123
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,138 @@ | ||
| --- | ||
| id: version-0.81-getting-started | ||
| title: Get Started with Windows | ||
| original_id: getting-started | ||
| --- | ||
|
|
||
|  | ||
|
|
||
| This guide will help you get started on setting up your very first React Native for Windows app. | ||
|
|
||
| Make sure you have installed all of the [development dependencies](rnw-dependencies.md). | ||
|
|
||
| For information around how to set up React Native, see the [React Native Getting Started Guide](https://reactnative.dev/docs/getting-started). | ||
|
|
||
| ## Create a new React Native project | ||
|
|
||
| Call the following from the place where you want your project directory to live: | ||
|
|
||
| <!-- Note, make sure both `@react-native-community/cli@ABC` and `--version XYZ` are pointing to the correct NPM tags in the command below. --> | ||
|
|
||
| <!-- 1. For the next version (i.e. in docs/getting-started.md) use `next` for the CLI and `nightly` for the RN version --> | ||
| <!-- 2. For stable versions in versioned_docs use `latest` for the CLI and the semantic version, i.e. `^0.73.0` for the RN version --> | ||
|
|
||
| <!-- See https://www.npmjs.com/package/@react-native-community/cli?activeTab=versions for the CLI version tags. --> | ||
| <!-- See https://www.npmjs.com/package/react-native?activeTab=versions for the RN version tags. --> | ||
|
|
||
| ```bat | ||
| npx --yes @react-native-community/cli@latest init <projectName> --version "^0.81.0" | ||
| ``` | ||
|
|
||
| ### Navigate into this newly created directory | ||
|
|
||
| The command will create your project in a new sub-directory, which you must enter before continuing: | ||
|
|
||
| ```bat | ||
| cd <projectName> | ||
| ``` | ||
|
|
||
| ### Add React Native Windows to your project's dependencies | ||
|
|
||
| <!-- Note, make sure `version` is pointing to the correct react-native-windows NPM tag in the command below. --> | ||
|
|
||
| <!-- 1. For the next version (i.e. in docs/getting-started.md) use `canary` --> | ||
| <!-- 2. For other versions in versioned_docs use the version in the format `^0.XY.0` --> | ||
|
|
||
| Next you'll want to add `react-native-windows` as a dependency: | ||
|
|
||
| <!--DOCUSAURUS_CODE_TABS--> | ||
|
|
||
| <!--Using Yarn (Recommended)--> | ||
|
|
||
| ```bat | ||
| yarn add react-native-windows@^0.81.0 | ||
| ``` | ||
|
|
||
| <!--Using NPM--> | ||
|
|
||
| ```bat | ||
| npm install --save react-native-windows@^0.81.0 | ||
| ``` | ||
|
|
||
| <!--END_DOCUSAURUS_CODE_TABS--> | ||
|
|
||
| ### Initialize the React Native Windows native code and projects | ||
|
|
||
| Lastly, initialize the React Native for Windows application with the [init-windows command](init-windows-cli.md): | ||
|
|
||
| ```bat | ||
| npx react-native init-windows --overwrite | ||
| ``` | ||
|
|
||
| > **Architecture Note:** The default React Native for Windows template for *new* projects targets [React Native's New Architecture](https://reactnative.dev/architecture/landing-page). For more information, including options for continuing to use the Old Architecture, see [New vs. Old Architecture](new-architecture.md). | ||
|
|
||
| > **Metro Note:** React Native Windows overwrites the app project's `metro.config.js` file to enable Windows support. If you are starting a new project, overwriting React Native's default `metro.config.js` should have no impact. However, if you have previously modified your `metro.config.js` file, please make sure to back up and re-apply your modifications after adding React Native Windows. | ||
|
|
||
| ## Running a React Native Windows App | ||
|
|
||
| > Make sure a browser is launched and running before running a React Native Windows app. | ||
| > Also ensure your system meets all the [requirements](rnw-dependencies.md) to build a Windows app as well. | ||
|
|
||
| - Without Using Visual Studio | ||
|
|
||
| In your React Native Windows project directory, run the [run-windows command](run-windows-cli.md): | ||
|
|
||
| ```bat | ||
| npx react-native run-windows | ||
| ``` | ||
|
|
||
| A new Command Prompt window will open with the React packager as well as your React Native for Windows app. This step may take a while during first run since it involves building the entire project and all dependencies. You can now start developing! :tada: | ||
|
|
||
| - Using Visual Studio | ||
|
|
||
| - From the root of the project directory, run the [autolink-windows command](autolink-windows-cli.md), which will automatically link your app's dependencies: | ||
| ```bat | ||
| npx react-native autolink-windows | ||
| ``` | ||
| - Open the solution file in the application folder in Visual Studio (e.g., `AwesomeProject/windows/AwesomeProject.sln` if you used `AwesomeProject` as `<projectName>`) | ||
| - Select the `Debug` configuration and the `x64` platform from the combo box controls to the left of the `Run` button and underneath the `Team` and `Tools` menu item. | ||
| - Run `yarn start` (or `npm start`) from your project directory, and wait for the React Native packager to report success. | ||
| - Click the `Run` button to the right of the platform combo box control in VS, or select the `Debug`->`Start without Debugging` menu item. You now see your new app and Chrome should have loaded `http://localhost:8081/debugger-ui/` in a new tab. Press `F12` or `Ctrl+Shift+I` in Chrome to open its Developer Tools. :tada: | ||
|
|
||
| - With VS Code | ||
| - Open your applications folder in VS Code. | ||
| - Install the [React Native Tools](https://marketplace.visualstudio.com/items?itemName=msjsdiag.vscode-react-native) plugin for VS Code. | ||
| - Create a new file in the applications root directory, `.vscode/launch.json` and paste the following configuration: | ||
| ```json | ||
| { | ||
| "version": "0.2.0", | ||
| "configurations": [ | ||
| { | ||
| "name": "Debug Windows", | ||
| "cwd": "${workspaceFolder}", | ||
| "type": "reactnative", | ||
| "request": "launch", | ||
| "platform": "windows" | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
| - Press `F5` or navigate to the debug menu (alternatively press `Ctrl+Shift+D`) and in the Debug drop-down select "Debug Windows" and press the green arrow to run the application. | ||
|
|
||
| ## Authoring Native Modules | ||
|
|
||
| See [Native Platform: Overview](native-platform.md). | ||
|
|
||
| ## Building a standalone React Native Windows App | ||
|
|
||
| Follow these steps to build a version of your app that you can install or publish to the store. This version will package your bundle and assets into the APPX package so you don't need to run Metro. | ||
|
|
||
| - Open the solution in Visual Studio | ||
| - Select the Release configuration from the Configuration Manager drop-down. | ||
| - Build the solution. You can now launch without first launching Metro. | ||
| - If you want to build an APPX package to share or publish, use the **Project** > **Publish** > **Create App Packages...** option. | ||
|
|
||
| > The Debug configuration uses the Web Debugger by default, which means the application's JavaScript code runs in Chrome.<br> | ||
| > If you're getting different runtime behavior between the Release and Debug configurations, consider disabling the `UseWebDebugger` setting in [`App.cpp`](https://github.com/microsoft/react-native-windows/blob/6b415659aa017dbc41e3f28e817fb768a8e80435/vnext/template/cpp-app/src/App.cpp#L30) or [`App.xaml.cs`](https://github.com/microsoft/react-native-windows/blob/6b415659aa017dbc41e3f28e817fb768a8e80435/vnext/template/cs-app/src/App.xaml.cs#L20) to get the same behavior in the Debug configuration. | ||
|
|
||
| See also this article for additional details: https://techcommunity.microsoft.com/t5/windows-dev-appconsult/getting-started-with-react-native-for-windows/ba-p/912093# |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,148 @@ | ||
| --- | ||
| id: version-0.81-migration-guide | ||
| title: Migration Guide | ||
| original_id: migration-guide | ||
| --- | ||
|
|
||
|  | ||
|
|
||
| ### React Native Windows — Migration from Paper (Old Architecture) to Fabric (New Architecture) - Sample Calculator App | ||
|
|
||
|
|
||
| ### Introduction | ||
|
|
||
| React Native 0.80 introduced Fabric as the default renderer and completed the transition to the New Architecture (Fabric + TurboModules). For React Native Windows (RNW), this migration replaces the legacy Paper architecture with a modern rendering pipeline that improves performance and memory usage. | ||
|
|
||
| > **Note:** Starting with RNW v0.80, Fabric became the default renderer. This migration guide applies to migrating from Paper to Fabric for RNW versions supporting Fabric (starting RNW v0.74), including the current version 0.81. | ||
| ### Key Concepts | ||
|
|
||
|
|
||
| - Paper (Old Architecture): Legacy renderer that uses UIManager and bridge-based communication between JS and native. | ||
|
|
||
| - Fabric (New Architecture): Modern concurrent renderer built on React Fiber and JSI. | ||
|
|
||
| - TurboModules: New native module system that replaces the old bridge-based modules with JSI bindings. | ||
|
|
||
| - RNW cpp-app Template: Default Windows template for new-architecture (Fabric) apps using C++/WinAppSDK. | ||
|
|
||
| - RNW old-uwp/cpp-app Template: Legacy UWP template used for Paper-based (old architecture) apps. | ||
|
|
||
|
|
||
| ### Prerequisites | ||
|
|
||
| - Node.js ≥ 18.x | ||
|
Contributor
There was a problem hiding this comment. Node version should be changed to 20 |
||
| - React Native CLI ≥ 13.x | ||
|
Contributor
There was a problem hiding this comment. 
We should change these in previous doc too. |
||
| - Visual Studio 2022 (v17.10 or later) | ||
| - Windows SDK ≥ 10.0.22621.0 | ||
| - Existing RNW app running on RN < 0.81 (Paper architecture) | ||
|
|
||
| Run yarn install after every update of package.json file | ||
|
|
||
| ### RNW App Migration | ||
|
|
||
| About the App: | ||
|
|
||
| For the purposes of this migration guide, we will use the sample Calculator app from the [React-native-windows-samples repository](https://github.com/microsoft/react-native-windows-samples). This Calculator app demonstrates a straightforward React Native for Windows project implemented in C++/WinRT, making it well-suited for illustrating the steps required to move from the legacy Paper architecture to the modern Fabric architecture. The app covers basic UI, native modules, and integration patterns typical in RNW projects, providing a practical reference as you follow each migration step. | ||
|
|
||
| You can view the Calculator app's source code at [react-native-windows-samples/samples/Calculator/cppwinrt](https://github.com/microsoft/react-native-windows-samples/tree/9e5d850e843acc2ff060fbd64673511cc67265f9/samples/Calculator/cppwinrt) and examine the full migration changes in the pull request diff [migrate calculator by anupriya13 · PR #1092](https://github.com/microsoft/react-native-windows-samples/pull/1092/files#diff-12ccc26d0186ecea507053fb04c1d4eac13aea210e5e1e95332e9add88940971). This real-world example enables you to compare the project structure and dependencies before and after the migration, making it easier to understand and replicate the process in your own RNW apps. | ||
|
|
||
|
|
||
|
|
||
| Repo: [react-native-windows-samples/samples/Calculator/cppwinrt at main · microsoft/react-native-windows-samples](https://github.com/microsoft/react-native-windows-samples/tree/main/samples/Calculator/cppwinrt) | ||
|
|
||
| Sample Diff: [migrate calculator by anupriya13 · Pull Request #1092 · microsoft/react-native-windows-samples](https://github.com/microsoft/react-native-windows-samples/pull/1092/files#diff-12ccc26d0186ecea507053fb04c1d4eac13aea210e5e1e95332e9add88940971) | ||
|
|
||
| Before you migrate confirm few things on your Paper project re-confirm that your project is using Paper architecture by checking the package.json init-window section | ||
|
|
||
|
|
||
| ### Steps Followed to Migrate to New Architecture (Fabric) | ||
| - Upgrade Dependencies: Update package.json to use React Native 0.81 and run: | ||
| ```bash | ||
| npm install | ||
| ``` | ||
| or | ||
| ```bash | ||
| yarn install | ||
| ``` | ||
| (Reference - [react-native-windows-samples/samples/Calculator/cppwinrt/package.json at 9e5d850e843acc2ff060fbd64673511cc67265f9 · microsoft/react-native-windows-samples](https://github.com/microsoft/react-native-windows-samples/blob/9e5d850e843acc2ff060fbd64673511cc67265f9/samples/Calculator/cppwinrt/package.json)) | ||
|
|
||
| - Delete the Existing Windows Directory: | ||
| ```bash | ||
| rm -rf windows | ||
| ``` | ||
|
|
||
| - Update Template in package.json: Set `"template": "cpp-app"` to use the new architecture template. | ||
|
|
||
| - Run: | ||
| ```bash | ||
| yarn install | ||
| ``` | ||
|
|
||
| - Reinitialize the Windows Project: | ||
| ```bash | ||
| npx react-native init-windows --template cpp-app | ||
| ``` | ||
|
|
||
| - Run the Application: | ||
| ```bash | ||
| npx @react-native-community/cli run-windows | ||
| ``` | ||
|
|
||
|
|
||
| You will see new files created / updated inside windows directory | ||
|
|
||
| No JS/TSX changes needed in src as Calculator uses basic components. | ||
|
|
||
| Commit Paper to Fabric: [migrate calculator by anupriya13 · Pull Request #1092 · microsoft/react-native-windows-samples](https://github.com/microsoft/react-native-windows-samples/pull/1092/commits/773c0ddec708083ab3fbd93dca08acfe0aa408aa) | ||
|
|
||
| ### Reverting to Old Architecture (Paper) | ||
|
|
||
| In case you encounter issues migrating to Fabric or due to unsupported controls or properties in Fabric please refer to below steps to revert back to Paper architecture. If you encounter missing properties, please open an issue: https://github.com/microsoft/react-native-windows/issues | ||
|
|
||
| - Delete the Windows Directory: | ||
| ```bash | ||
| rm -rf windows | ||
| ``` | ||
|
|
||
| - Update Template in package.json: Set `"template": "old/uwp-cpp-app"`. (Reference -[react-native-windows-samples/samples/Calculator/fabric/package.json at 9e5d850e843acc2ff060fbd64673511cc67265f9 · microsoft/react-native-windows-samples](https://github.com/microsoft/react-native-windows-samples/blob/9e5d850e843acc2ff060fbd64673511cc67265f9/samples/Calculator/fabric/package.json)) | ||
|
|
||
| - Run: | ||
| ```bash | ||
| yarn | ||
| ``` | ||
|
|
||
| - Reinitialize the Old Architecture Project: | ||
| ```bash | ||
| npx react-native init-windows --template old/uwp-cpp-app | ||
| ``` | ||
|
|
||
| - Run the App: | ||
| ```bash | ||
| npx @react-native-community/cli run-windows | ||
| ``` | ||
|
|
||
|
|
||
|
|
||
| Commit Fabric to Paper for reference: [migrate calculator by anupriya13 · Pull Request #1092 · microsoft/react-native-windows-samples](https://github.com/microsoft/react-native-windows-samples/pull/1092/commits/450baba033b9c1f0e9b9e882bee91954f03767a1) | ||
|
|
||
| ### Third-Party Modules and Community Libraries [Out of Scope for Calculator] | ||
|
|
||
| When migrating to the New Architecture (Fabric), it's important to verify that all third-party or community modules used in your project are compatible with the new architecture. Modules developed for the old Paper bridge may not function correctly without Fabric support. | ||
|
|
||
| Before using any external module: | ||
|
|
||
| Check the module's documentation or GitHub repository for Fabric or TurboModule support. | ||
|
|
||
| Prefer modules that explicitly state compatibility with React Native 0.81 or higher (or 0.80+ for Fabric compatibility). | ||
|
|
||
| If the module is not updated, consider alternative libraries or maintain your own fork until Fabric support is added. | ||
|
|
||
| ### Flyout / Popup Behavior Update [Out of Scope for Calculator] | ||
|
|
||
| In the New Architecture RNW, the Flyout and Popup components have been updated to align with the Modal API for better cross-platform consistency. Any previous usage of Flyout or Popup should be reviewed and replaced with the new Modal-based implementation, ensuring proper layering, dismissal, and accessibility behavior. | ||
|
|
||
| ### Conclusion | ||
|
|
||
| Migrating from Paper to Fabric in React Native Windows modernizes your project, improves performance, and prepares your app for future React Native releases. Reverting to the old architecture is simple if required. | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This needs to be updated