Upgrading a React Native Windows TurboModule to use the New Architecture

New Architecture has been released on React Native Windows from 0.76 onwards! It is crucial to ensure that community modules are also supported with this New Architecture to maintain compatibility and take advantage of new features. This guide provides step-by-step instructions to upgrade the module's version of React Native Windows, handle potential issues with example applications, and ensure the module builds and functions correctly with the New Architecture.

Steps to Upgrade a React Native Windows TurboModule:

1. Upgrade the module's version of React Native Windows to >= 0.76. React Native Windows officially supports usage of New Architecture apps from 0.76, so the module will need to be on a supported version.
2. Run the cpp-lib template in the root of the library (this may not necessarily be the root of the repo - look for a windows folder, the directory with it should be the root).
   • If the library has an example application included within the repo, the cpp-lib template will try to upgrade the example application using the cpp-app template. Sometimes this causes issues - if this is happening, or if the repo uses React Native Test App to generate the example application, temporarily delete the example application before running the cpp-lib template.
3. Check for naming issues with some of the overwritten files. For example, if the module you are upgrading is called FooBar, the template will automatically look for a solution file titled FooBar.sln and overwrite it. If it doesn't find one with that name, it will generate a new one. You should keep the new solution file, as the cpp-lib template now builds against the Nugets by default, so there is no need to include the projects in the solution file.
4. Restore the example directory - just run the following command: git checkout -- example.
5. The template will remove some of the includes in the project file needed to be able to run paper code - these should be added back in. Can be done by just looking at the diff and reverting. For example, the following is an example from the react-native-permissions repo:

   - <ItemGroup>
   -  <None Include="PropertySheet.props" />
   - </ItemGroup>
   + <ItemGroup>
   +  <ClCompile Include="RNPermissions.cpp" />
   + </ItemGroup>
   

6. The template will overwrite the module functionality in the {modulename}.cpp and .h files, and replaced with a basic multiply() function - these should be added back in.
7. Sometimes there will be two copies of certain files created (e.g pch files). Only one should be needed - as long as they contain all the headers needed, doesn’t matter which one.
8. Add an ifdef to ReactPackageProvider to decide the correct call to AddAttributedModules() based on whether RnwNewArch is set to true:

   #ifdef RnwNewArch      
     AddAttributedModules(packageBuilder, true);  
   #else      
     AddAttributedModules(packageBuilder);  
   #endif
   

9. Try building the solution file for the module. There may be some syntax errors, which you can resolve as appropriate.
10. Once the solution can build successfully, you can try to upgrade the example app to use the New Architecture. Depending on the setup, this can be done two ways:
    • If the app is a React Native Test App, it can be generated using the following command: yarn install-windows-test-app --use-fabric.
    • Otherwise, run the following command in the root of the example app directory: yarn react-native init-windows --template cpp-app --overwrite --logging.
11. Run the example application and compare the functionality and appearance to the app running Old Architecture.