Skip to content

migration-guide.md

Latest commit

 

History

History
148 lines (90 loc) · 7.45 KB

migration-guide.md

File metadata and controls

148 lines (90 loc) · 7.45 KB
id version-0.81-migration-guide
title Migration Guide
original_id migration-guide

Architecture

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
  • React Native CLI ≥ 13.x
  • 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. 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 and examine the full migration changes in the pull request diff migrate calculator by anupriya13 · PR #1092. 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

Sample Diff: migrate calculator by anupriya13 · Pull Request #1092 · microsoft/react-native-windows-samples

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)

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

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

Commit Fabric to Paper for reference: migrate calculator by anupriya13 · Pull Request #1092 · microsoft/react-native-windows-samples

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.