Creating new projects to test specific RNW versions

Warning: This page is meant to help RNW developers quickly create projects to test changes to RNW itself. If you're not working on RNW, please see the official Getting Started docs.

The official docs detail how to create new projects targeting the latest stable versions of RNW and is appropriate for all RNW customers. The steps below will help you create new projects to test specific versions of RNW and is intended specifically for RNW developers.

Creating a new RNW app project

Creating a new RNW app project using creaternwapp.cmd:

The creaternwapp.cmd utility script which automates the manual steps below (while also creating git commits at each stage of the process) and makes it relatively easy to create new RNW app projects for testing.

The script lets you specify the version of react-native-windows you want (defaults to latest) with the /rnw flag, and will take care of setting up an app project with the correct version of react-native. For example, to create a new app named MyApp targeting react-native-windows@canary, simply run:

creaternwapp.cmd /rnw canary MyApp

This will give you a new RNW app using the New Architecture cpp-app template. To create an RNW app using an old template, simply specify /lt like so:

creaternwapp.cmd /rnw canary /lt old/uwp-cpp-app MyApp

Normally, if you want to create an RNW app which uses your local RNW repo (instead of a published version), you would follow the steps below to yarn link your RNW repo. However, creaternwapp.cmd can set up the yarn linking for you. Simply specify /linkrnw at project creation like so:

creaternwapp.cmd /linkrnw MyApp

As usual, the script will make sure that all the correct package versions are used.

Note: By default, creating a new project with the cpp-app template against a published version of RNW will set up the new project to use the NuGet packages. However, when using /linkrnw to use your local RNW repo, the new project will build against the source in your RNW repo.

However you do it, with the project created, you should now be able to build and run your RNW app with yarn windows as usual.

Creating a new RNW app project manually

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. If you run the following, you'll get the concrete version of react-native-windows's canary tag:

npm show react-native-windows@canary version

Let's say it returned 0.0.0-canary.868. Remember that for later, then, determine which base version of react-native you should build the app from, again using the npm show command:

npm show react-native-windows@0.0.0-canary.868 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 RN app project:

npx --yes @react-native-community/cli@latest init MyApp --version 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 every react-native version. 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 wanted originally. 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 (using the concrete version you got earlier 0.0.0-canary.868). Make sure you're in the app's directory and run:

yarn add react-native-windows@0.0.0-canary.868

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. For this example, we're going to use the New Architecture cpp-app template, but it should work with older app templates as well. 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

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. For this example, we're going to use the New Architecture cpp-app template, but it should work with older app templates as well. 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

Using your local 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 project's directory, run:

     yarn link C:\code\rnw\vnext

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

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

Note: Linking creates a symlink from your project'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 project'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#)