Contributing to the CLI

Where stuff lives

Parts of the CLI:

1. Code to identify the correct version of react-native-windows to install, and install it:
   [Root]\packages\react-native-windows-init
2. Template code: The code that actually creates the files needed to to run a create and run react-native-windows app here:
   [Root]\packages\@react-native-windows\cli
3. Code for run-windows and other commands run through react-native <foo> Also in [Root]\packages\@react-native-windows\cli

How to test local changes to the project init CLI:

1. If you are making changes to the react-native-windows-init code, you can build the code locally using yarn build, then manually call into the CLI by using node <root>\packages\react-native-windows-init\lib-commonjs\Cli.js -- You can pass parameters to that as usual, or use node --inspect-brk ... to allow you to attach to the call using VSCode.
2. If you are making changes to the vnext part of the CLI, you can install RNW from your local enlistment by supplying the --version parameter to the react-native-windows-init command. For example:
   npx react-native-windows-init --version file:d:\rnw\vnext

Testing changes in @react-native-windows\cli

Since the cli script will load all scripts under local-cli folder from the version that you are deploying any changes there (like the templates) will not be picked up since they will be used from the version of the react-native-windows package installed. You can pass the path to the package as the version to test this.

1. node <root>\node_modules\react-native-windows-init\bin.js --language cpp --version file:<root>\vnext See #4946

Note: that yarn does a copy of all the files under vnext to install react-native-windows. Unlike when the package has been published, this will include all the native built files which would normally be excluded by npmignore. You should delete the build, target and packages folder from vnext. Otherwise the command will have to copy GBs of data to install react-native-windows from your local path

A Faster way to test the react-native-windows-init CLI:

While the above may be the safest way, it is also the slowest as per the note. It will copy all files in your vnext folder over to your node_modules folder of the test project. If you have a bunch of flavors build this can add up. I had about 29gigs of outputs. This made it extremely slow to copy each time. It will also create a unique copy in the yarn cache folder potentially causing your disk to run out of space, as running this 20 times requires ~600gigs. There is now an alternative way to 'link' in the package from your enlistment folder. This has the added benefit that changes to other files in the package like in the PropertySheets folder are immediately visible and don't require rerunning the project init to pick up.

1. Navigate to the <root>/vnext folder in your repo
2. Run yarn link

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

3. node <root>\packages\react-native-windows-init\lib-commonjs\Cli.js --useDevMode and any other options

Testing react-native-windows-init E2E with only local CLI bits

Starting in 0.63 the functionality of the CLI was divided into different packages. When you run npx react-native-windows-init, by default all of the right packages get downloaded from npm. However, if you're making changes to one or more parts of the "new project" flow locally in your repo, it's important to make sure that only your local packages get used, not the ones from npm. Here are step-by-step examples on how to create a new project ensuring it's really using just your repo's files.

First, let's assume your local repo is d:\rnw and you've already committed your changes locally.

0. Clean up your local repo

1. Start with a "clean" repo, ie. only files that are checked-in + a fresh JS build:

cd d:\rnw
git clean -f -d -e node_modules/ -x
yarn install && yarn build

2. Set up yarn link for the following packages (plus any others you've modified):

cd d:\rnw\vnext
yarn link
cd d:\rnw\packages\react-native-windows-init
yarn link
cd d:\rnw\packages\@react-native-windows\cli
yarn link

Now let's create a new React Native project.

Example 1: An app named "testapp"

1. Create the initial project

Replace <version> below with the react-native version your local repo is using d:\rnw\vnext\package.json.

cd c:\code
npx react-native init testapp --version <version>
cd c:\code\testapp
git init . && git add . && git commit -m "new project"

Note: The git steps are optional, but very useful later for being able to compare changes once we run react-native-windows-init.

2. Link the local dependencies to the packages you linked earlier:

cd c:\code\testapp
yarn link "react-native-windows"
yarn link "react-native-windows-init"
yarn link "@react-native-windows/cli"

3. Run your local react-native-windows-init to create the windows project

cd c:\code\testapp
node node_modules\react-native-windows-init\bin.js --overwrite --verbose --version file:d:\rnw\vnext

4. Run your local react-native run-windows to build the windows project

cd c:\code\testapp
npx --no-install react-native run-windows --logging

Example 2: A library named "testlib"

1. Create the initial project

cd c:\code
npx create-react-native-module --module-name "testlib" testlib
cd c:\code\testlib
git init . && git add . && git commit -m "new project"

Note: The git steps are optional, but very useful later for being able to compare changes once we run react-native-windows-init.

2. Update lib's dependencies

When using create-react-native-module, the project it creates targets older versions of react native, so you'll need to upgrade it before continuing. Replace <react-version> and <react-native-version> with the react and react-native versions your local repo is using in d:\rnw\vnext\package.json.

cd c:\code\testlib
yarn install
yarn upgrade react@<react-version> --dev
yarn upgrade react-native@<react-native-version> --dev

3. Link the local dependencies to the packages you linked earlier:

cd c:\code\testlib
yarn link "react-native-windows"
yarn link "react-native-windows-init"
yarn link "@react-native-windows/cli"

4. Run your local react-native-windows-init to create the windows project

cd c:\code\testlib
node node_modules\react-native-windows-init\bin.js --overwrite --verbose --version file:d:\rnw\vnext

5. Run your local react-native run-windows to build the windows project

cd c:\code\testlib
npx react-native run-windows --no-packager --no-launch --no-deploy --logging --no-autolink

How to debug other CLI commands:

The easiest way to to debug is using VS Code. You just need to create a configuration within your template app directory that tells VS Code to launch the CLI in an instance of node and debug node on startup. Here's an example launch.json with a single configuration:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "react-native windows",
      "program": "${workspaceRoot}/node_modules/react-native/cli.js",
      "args": ["run-windows"],
      "stopOnEntry": true
    }
  ],
  "compounds": []
}