Using the new architecture templates

This document summarizes the current steps for creating a new RNW project using the (experimental) new architecture templates.

Creating a new RNW app project using the cpp-app template

1. Creating a new RN app project MyApp

First, we must determine the version of react-native-windows you wish to use. For this example, we'll say the canary build since that's where active development is occurring.

Then, determine which base version of react-native you should build the app from, using the npm show command:

npm show react-native-windows@canary peerDependencies.react-native

Note: Be sure to substitute the correct version of react-native-windows, i.e., if you're targeting latest, use npm show react-native-windows@latest peerDependencies.react-native instead.

Let's say the command returned 0.74.0-nightly-20231201-c30f2b620. Then, use @react-native-community/cli init to create your app project:

npx --yes @react-native-community/cli@0.74.0-nightly-20231201-c30f2b620 init MyApp --template @react-native-community/template@0.74.0-nightly-20231201-c30f2b620

Note: There was some lag between moving to the @react-native-community/template package and actually publishing versions which match the tag. If project creation fails because the template can't be found, you should try using next, then, after the project creation succeeds, change the version of react-native in package.json to the version you started with. See microsoft/react-native-windows#13446 for details.

You should now have a folder named MyApp with your base RN app.

2. Adding RNW to the base RN app

Next you'll need to add the version of react-native-windows as a dependency to your app (still canary in this case). Make sure you're in the app's directory and run:

yarn add react-native-windows@canary

3. Adding the template code from the RNW cpp-app template

Next, you'll use react-native init-windows to add the RNW code to your app. Make sure you're in the app's directory and run:

yarn react-native init-windows --template cpp-app --overwrite --logging

4. Run your app

You should now be able to run your app with react-native run-windows as usual. Make sure you're in the app's directory and run:

yarn react-native run-windows --logging

Upgrading an existing RNW app project using the cpp-app template

Note: If these steps to upgrade RN in-place doesn't work, you might try re-creating a fresh base RN project using the steps above.

1. Upgrade the existing app's version of RN and RNW

As with a new app project, first we must determine the version of react-native-windows you wish to use. For this example, we'll use 0.0.0-canary.761. Then, determine which base version of react-native you should upgrade to, using the npm show command:

npm show react-native-windows@0.0.0-canary.761 peerDependencies.react-native

Let's say the command returned 0.74.0-nightly-20231201-c30f2b620. Then, use yarn upgrade to upgrade your app's RN and RNW version:

yarn upgrade react-native@0.74.0-nightly-20231201-c30f2b620
yarn upgrade react-native-windows@0.0.0-canary.761

2. Re-run the template code from the RNW cpp-app template

Next, you'll use react-native init-windows to add the RNW code to your app. Make sure you're in the app's directory and run:

yarn react-native init-windows --template cpp-app --overwrite --logging

3. Run your app

You should now be able to run your app with react-native run-windows as usual. Make sure you're in the app's directory and run:

yarn react-native run-windows --logging

Debugging the cpp-app template with your local clone of the RNW repo

If you're working on some changes locally in your RNW repo, you can modify the procedures above as follows to use and test your local copy of RNW, instead of a published version off NPM. Assuming your RNW repo is at C:\code\rnw:

• To determine which version of react-native-windows to use, use the version number in your RNW repo, which can be quickly determined with:

  npm show C:\code\rnw\vnext version

• When using npm show to determine the version of react-native to use, instead use:

  npm show C:\code\rnw\vnext peerDependencies.react-native

• After adding RNW to the project with yarn add you'll then want to link it to your repo instead with yarn link:
  1. In your RNW repo's vnext directory, run yarn link. Note: This only needs to be done once for your machine.
  2. Then, in your app's directory, run:

     yarn link react-native-windows

Now your app should be using your local clone of RNW. Any code changes you make there will be available to your app.

Note: If you make changes to the cpp-app template itself, you'll need to re-run the react-native init-windows to apply those changes to your app's code.

Note: Linking creates a symlink from your app's node_modules\react-native-windows to your repo at C:\code\rnw\vnext. So when your app builds, the RNW source and outputs will be those within your RNW repo. Be careful if you're hopping back and forth between working with the RNW repo's code and the app's code, (i.e. don't forget to run yarn build in the RNW repo to build your TS changes into JS, and don't try to build say, Microsoft.ReactNative.sln and MyApp.sln at the same time.)

Using other templates with react-native init-windows

While the primary purpose of the init-windows command is to support the new architecture app template (cpp-app) you can do the steps above with any of the available templates by replacing --template cpp-app with --template XYZ, where XYZ can be:

Template	Name
cpp-app	React Native Windows Application (New Arch, C++, Win32, Hermes)
cpp-lib	React Native Windows Turbo Module (New Arch, C++)
old/uwp-cpp-app	React Native Windows Application (Old Arch, UWP, C++)
old/uwp-cpp-lib	React Native Windows Library (Old Arch, UWP, C++)
old/uwp-cs-app	React Native Windows Application (Old Arch, UWP, C#)
old/uwp-cs-lib	React Native Windows Library (Old Arch, UWP, C#)