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've made any local changes to your RNW repo and want to test on a new project, the basic process is to use the yarn link command in your project's folder to let it know that you want to use your local RNW repo's packages instead of a version downloaded from NPM.

Note: If you haven't followed the steps above to create our project, you'll need to make sure that your new project is set to use the same version of react-native-windows (and react-native) as your local RNW repo. So when you're following the steps to yarn add react-native-windows@VERSION make sure you're specifying the same version in your vnext\package.json file.

Then, after the yarn add, if your RN project is using Classic Yarn (v1.x) you must do the following:

1. Build your RNW repo with yarn build
2. Run yarn link in <root>\vnext to link react-native-windows

   If you get an error that another folder has already registered it simply run yarn unlink and then try again.

3. Open the target RN project (app/lib) folder
4. Run yarn link react-native-windows

Otherwise, if you're using the newer Yarn:

1. Build your RNW repo with yarn build
2. Open the target RN project (app/lib) folder (that doesn't have RNW yet)
3. Run yarn link <root>\vnext

In either case, now your project's node_modules\react-native-windows should be a symlink to your local RNW repo. This means any changes to RNW in your repo will be used by your app, including changes to react-native-windows or the CLI commands in @react-native-windows/cli. You will be able to test and debug them as described above.

In this way, you can even test the new project command, react-native init-windows in this project folder. The command is even smart enough to know that your using a local RNW repo and will switch to building by source (instead of NuGets, which you won't have) by default.

Important: When linking your RNW repo, remember when the app builds, all RNW library files will be in your local RNW repo's build output folders. So be careful with linking and building more than one app at a time as they can overwrite one another. It's best to do your testing, then delete the test project app after you're done.

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#)