diff --git a/.spelling b/.spelling index 31ae39caf..16aabf3cb 100644 --- a/.spelling +++ b/.spelling @@ -2,6 +2,8 @@ accessors APIs Appium +autolink +autolink-windows autolinked autolinking bool @@ -14,6 +16,7 @@ Chakra changelog CocoaPods codegen +codegen-windows comboboxes config configJson @@ -35,11 +38,12 @@ functor HomeBrew hostname i.e. +init-windows initializer interop iOS -KeyEvents ItemGroup +KeyEvents lifecycle macOS middleware @@ -72,6 +76,7 @@ repo repos RNW-on-WinUI roadmap +run-windows runtime runtimes schemas diff --git a/docs/autolink-windows-cli.md b/docs/autolink-windows-cli.md new file mode 100644 index 000000000..d6dd492a1 --- /dev/null +++ b/docs/autolink-windows-cli.md @@ -0,0 +1,37 @@ +--- +id: autolink-windows-cli +title: react-native autolink-windows +--- + +This guide will give you more information on the `autolink-windows` command of the React Native Windows CLI. + +## `autolink-windows` + +The `autolink-windows` CLI command is used to link the native code and build systems for a React Native for Windows app with any native community modules it uses. + +**Note:** Autolinking runs automatically as part of running the [run-windows command](run-windows-cli.md), unless the `--no-autolink` argument is used. + +### Usage +Runs Windows-specific autolinking for your RNW project. + +```bat +npx react-native autolink-windows +``` +### Options + +Here are the options that `react-native autolink-windows` takes: +| Option | Input Type | Description | +|-----------------------|------------|--------------------------------------------------| +| `--logging` | boolean | Verbose output logging | +| `--check` | boolean | Only check whether any autolinked files need to change | +| `--sln` | string | Override the app solution file determined by 'react-native config', i.e. `windows\myApp.sln` | +| `--proj` | string | Override the app project file determined by 'react-native config', i.e. `windows\myApp\myApp.vcxproj` | +| `--no-telemetry` | boolean | Disables sending telemetry that allows analysis of usage and failures of the react-native-windows CLI | +| `-h`, `--help` | boolean | Display help for command | + +This sends telemetry to Microsoft by default. You can prevent the telemetry from being sent by using the `--no-telemetry` command line option. See below for more details. + +The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices. + +This data collection notice only applies to the process of running the react-native-windows CLI commands. + \ No newline at end of file diff --git a/docs/codegen-windows-cli.md b/docs/codegen-windows-cli.md new file mode 100644 index 000000000..f6660c862 --- /dev/null +++ b/docs/codegen-windows-cli.md @@ -0,0 +1,33 @@ +--- +id: codegen-windows-cli +title: react-native codegen-windows +--- + +This guide will give you more information on the `codegen-windows` command of the React Native Windows CLI. + +## `codegen-windows` + +The `codegen-windows` CLI command is used to generate some necessary Windows-specific native code for native modules. + +### Usage +Runs Windows-specific codegen for native modules. + +```bat +npx react-native codegen-windows +``` +### Options + +Here are the options that `react-native codegen-windows` takes: +| Option | Input Type | Description | +|-----------------------|------------|--------------------------------------------------| +| `--logging` | boolean | Verbose output logging | +| `--check` | boolean | Only check whether any codegen files need to change | +| `--no-telemetry` | boolean | Disables sending telemetry that allows analysis of usage and failures of the react-native-windows CLI | +| `-h`, `--help` | boolean | Display help for command | + +This sends telemetry to Microsoft by default. You can prevent the telemetry from being sent by using the `--no-telemetry` command line option. See below for more details. + +The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices. + +This data collection notice only applies to the process of running the react-native-windows CLI commands. + \ No newline at end of file diff --git a/docs/debugging-javascript.md b/docs/debugging-javascript.md index 14085b94c..d2e2e0289 100644 --- a/docs/debugging-javascript.md +++ b/docs/debugging-javascript.md @@ -63,7 +63,7 @@ InstanceSettings.UseDirectDebugger = true; 2. Then simply re-build and launch your RNW app as usual. -> For a new RNW app created using `react-native-windows-init`, `UseDirectDebugger` defaults to `false`. +> For a new RNW app `UseDirectDebugger` defaults to `true` for Debug builds, and `false` for Release builds. #### Option 2: Using the Developer Menu @@ -127,7 +127,7 @@ You can direct debug RNW apps using the (default) Chakra JS engine with [Visual 2. For C# RNW apps, open the *Debug* tab, set the *Debugger type > Application process* to *Script*, then close the properties 4. Click on *Debug* in the menu bar and select *Start Debugging* 4. **Option B:** Attach Visual Studio to the app that's already running - 1. Make sure that your native app and Metro is already running (i.e. `npx react-native run-windows`) + 1. Make sure that your native app and Metro is already running (i.e. using the [run-windows command](run-windows-cli.md)) 2. Click on *Debug* in Visual Studio's menu bar and select *Attach to Process...* 3. Find and select the native process for your app (not Metro) 4. Make sure *Attach to:* is set to *Automatic: Script code* or *Script code* @@ -154,7 +154,7 @@ You can direct debug RNW apps using the Hermes JS engine with [Visual Studio](ht > **Important:** Launching the app and starting direct debug with Hermes isn't supported in Visual Studio. 4. **Option B:** Attach Visual Studio to the app that's already running - 1. Make sure that your native app and Metro is already running (i.e. `npx react-native run-windows`) + 1. Make sure that your native app and Metro is already running (i.e. using the [run-windows command](run-windows-cli.md)) 2. Click on *Debug* in Visual Studio's menu bar and select *Attach to Process...* 3. Make sure *Connection type:* is set to *JavaScript and TypeScript (Chrome DevTools/V8 Inspector)* > If you don't see *JavaScript and TypeScript (Chrome DevTools/V8 Inspector)*, make sure you've installed the *Node.js development* workload for your version of Visual Studio. @@ -204,7 +204,7 @@ You can direct debug RNW apps using the Hermes JS engine with [VS Code](http://c "type": "node" } ``` - 3. Make sure that your native app and Metro is already running (i.e. `npx react-native run-windows`) + 3. Make sure that your native app and Metro is already running (i.e. using the [run-windows command](run-windows-cli.md)) 4. Open the *Run and Debug* sidebar by clicking on the button in the sidebar or by pressing `Ctrl+Shift+D` 5. Make sure the new config is selected at the top of the *Run and Debug* sidebar 6. Click on the ▶️ button or press `F5` in VS Code @@ -258,7 +258,7 @@ You can direct debug RNW apps using the Hermes JS engine with [VS Code](http://c "request": "attach" } ``` - 3. Make sure that your native app and Metro is already running (i.e. `npx react-native run-windows`) + 3. Make sure that your native app and Metro is already running (i.e. using the [run-windows command](run-windows-cli.md)) 4. Open the *Run and Debug* sidebar by clicking on the button in the sidebar or by pressing `Ctrl+Shift+D` 5. Make sure the new config is selected at the top of the *Run and Debug* sidebar 6. Click on the ▶️ button or press `F5` in VS Code @@ -326,7 +326,7 @@ InstanceSettings().UseDirectDebugger(false); 2. Then simply re-build and launch your RNW app as usual. -> For a new RNW app created using `react-native-windows-init`, `UseWebDebugger` defaults to `true` for Debug builds, and `false` for Release builds. +> Unless otherwise specified, for a new RNW app, `UseWebDebugger` defaults to `false`. ### Step 2: Connect a debugger diff --git a/docs/getting-started.md b/docs/getting-started.md index b213ae0cb..12b111188 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -9,7 +9,7 @@ Make sure you have installed all of the [development dependencies](rnw-dependenc For information around how to set up React Native, see the [React Native Getting Started Guide](https://reactnative.dev/docs/getting-started). -## Install React Native for Windows +## Create a new React Native project Remember to call `react-native init` from the place you want your project directory to live. @@ -27,23 +27,47 @@ npx --yes react-native@nightly init --version "nightly" ### Navigate into this newly created directory -Once your project has been initialized, React Native will have created a new sub directory where all your generated files live. +React Native will have created your project in a new sub-directory, which you must enter before continuing. ```bat -cd projectName +cd ``` -### Install the Windows extension +### Add React Native Windows to your project's dependencies -Lastly, install the React Native for Windows packages. + + + + + + + + + + +```bat +yarn add react-native-windows@canary +``` + + + +```bat +npm install --save react-native-windows@canary +``` + + + +### Initialize the React Native Windows native code and projects + +Lastly, initialize the React Native for Windows application with the [init-windows command](init-windows-cli.md): ```bat -npx --yes react-native-windows-init --overwrite +npx react-native init-windows --overwrite ``` -> The --overwrite flag copies a custom `metro.config.js` file. If you are starting a new app, this should have no impact. If you are adding Windows to your existing app and you have modified the `metro.config.js` file, please back up your changes, run the command and copy over to take effect. +> **Note:** RNW templates contain a customized `metro.config.js` file, which is meant to merge cleanly into the default config provided by the standard React Native project template. If you are starting a new app, overwriting `metro.config.js` should have no impact. However, if you are adding Windows to an existing app with an already modified `metro.config.js` file, please make sure to back up and re-apply your modifications after adding RNW. -For information on the options that `react-native-windows-init` takes see [React Native Windows Init CLI](https://microsoft.github.io/react-native-windows/init-cli). +> **Note:** Previous versions of the RNW Getting Started steps recommend the use of the `react-native-windows-init` command, which is being phased out. For documentation of that command, see: [React Native Windows Init CLI](https://microsoft.github.io/react-native-windows/init-cli). ## Running a React Native Windows App @@ -52,19 +76,17 @@ For information on the options that `react-native-windows-init` takes see [React - Without Using Visual Studio - In your React Native Windows project directory, run: + In your React Native Windows project directory, run the [run-windows command](run-windows-cli.md): ```bat npx react-native run-windows ``` - For information on the options that `@react-native-windows/cli` takes see [React Native Windows CLI](run-windows-cli.md). - - A new Command Prompt window will open with the React packager as well as a `react-native-windows` app. This step may take a while during first run since it involves building the entire project and all dependencies. You can now start developing! :tada: + A new Command Prompt window will open with the React packager as well as your React Native for Windows app. This step may take a while during first run since it involves building the entire project and all dependencies. You can now start developing! :tada: - Using Visual Studio - - From the root of the project directory, run the following script which will automatically link your app's dependencies: + - From the root of the project directory, run the [autolink-windows command](autolink-windows-cli.md), which will automatically link your app's dependencies: ```bat npx react-native autolink-windows ``` diff --git a/docs/hermes.md b/docs/hermes.md index 39251a631..639bfd692 100644 --- a/docs/hermes.md +++ b/docs/hermes.md @@ -107,10 +107,10 @@ Follow steps 1-7 from above, and then ### Enable debugging/profiling on release builds -We keep the inspector turned off on release builds by default. If you want to debug or profile release builds, set the MSBuild property `EnableHermesInspectorInReleaseFlavor` to `'true'` when building the platform. +We keep the inspector turned off on release builds by default. If you want to debug or profile release builds, set the MSBuild property `EnableHermesInspectorInReleaseFlavor` to `'true'` when building the platform with the [run-windows command](run-windows-cli.md), i.e.: ```bash -npx react-native run-windows --msbuild EnableHermesInspectorInReleaseFlavor=true +npx react-native run-windows --msbuildprops EnableHermesInspectorInReleaseFlavor=true ``` ### Known Issues diff --git a/docs/init-windows-cli.md b/docs/init-windows-cli.md new file mode 100644 index 000000000..6a915cb1a --- /dev/null +++ b/docs/init-windows-cli.md @@ -0,0 +1,49 @@ +--- +id: init-windows-cli +title: react-native init-windows +--- + +This guide will give you more information on the `init-windows` command of the React Native Windows CLI. + +## `init-windows` + +The `init-windows` CLI command is used to initialize a new React Native for Windows project inside an existing React Native project. + +### Usage +Initializes a new RNW project from a given template. + +```bat +npx react-native init-windows +``` +### Options + +Here are the options that `react-native init-windows` takes: +| Option | Input Type | Description | +|-----------------------|------------|--------------------------------------------------| +| `--logging` | boolean | Verbose output logging | +| `--template` | string | Specify the template to use | +| `--name` | string | The native project name. Defaults to the name property in `app.json` or `package.json` | +| `--namespace` | string | The native project namespace, expressed using dots as separators, i.e. `Level1.Level2.Level3`. Defaults to the same as name | +| `--overwrite` | boolean | Overwrite any existing files without prompting | +| `--no-telemetry` | boolean | Disables sending telemetry that allows analysis of usage and failures of the react-native-windows CLI | +| `-h`, `--help` | boolean | Display help for command | + +### Templates + +The following templates are available for use with `init-windows` by replacing `--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#) | + +This sends telemetry to Microsoft by default. You can prevent the telemetry from being sent by using the `--no-telemetry` command line option. See below for more details. + +The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices. + +This data collection notice only applies to the process of running the react-native-windows CLI commands. + \ No newline at end of file diff --git a/docs/native-code.md b/docs/native-code.md index 31de90676..d0439d171 100644 --- a/docs/native-code.md +++ b/docs/native-code.md @@ -5,7 +5,7 @@ title: Working with native code on Windows ## What is a React Native for Windows app? -When you create a React Native for Windows app with the CLI, you will get a [Universal Windows Platform app](https://docs.microsoft.com/windows/uwp/get-started/universal-application-platform-guide) (aka UWP app). +When you create a React Native for Windows app targeting React Native's old architecture, you will get a [Universal Windows Platform app](https://docs.microsoft.com/windows/uwp/get-started/universal-application-platform-guide) (aka UWP app). The Universal Windows Platform allows you to access a set of common functionality on all Windows devices via the [Windows Runtime](https://docs.microsoft.com/windows/uwp/winrt-components/) (WinRT). WinRT APIs can be accessed from C++ (via [C++/WinRT](https://docs.microsoft.com/windows/uwp/cpp-and-winrt-apis/)), or via .NET C#. @@ -17,9 +17,9 @@ The current publicly supported version of .NET ([.NET UWP](https://docs.microsof Whether you are new to Windows development, or you are a Win32 desktop app veteran, the following FAQs should answer some common questions. -When you add Windows support to a react native app via the steps described in the [Install the windows extension](getting-started.md#install-the-windows-extension) section, the react-native-windows CLI will create a UWP app for you. +When you add Windows support to a React Native app via the steps described in [Get Started with Windows](getting-started.md), you will get a UWP app. -> **Note:** By default the `react-native-windows-init` command creates a C++ app, however you can choose to create a C# app instead. The choice of language can impact your performance and your capacity to consume native modules, so if either of those issues are important to you, it's highly recommended that you read [Choosing C++ or C# for native code](native-code-language-choice.md). +> **Note:** By default the [init-windows command](init-windows-cli.md) creates a C++ app, however it is possible to create a C# app instead. The choice of language can impact your performance and your capacity to consume native modules, so if either of those issues are important to you, it's highly recommended that you read [Choosing C++ or C# for native code](native-code-language-choice.md). Regardless of the language of your app **RNW apps are UWP apps** and therefore have the following characteristics: @@ -57,7 +57,7 @@ Any libraries you use should be built as WinRT components. In other words, you c - Libraries built for .NET desktop framework cannot be directly accessed by UWP. You can create a .NET Standard library that calls into the .NET framework one, and call from the UWP app into the .NET Standard middleware. ### Local testing and inner loop -For internal development, you can deploy your app for test purposes by side-loading and deploying via [loose-file registration](https://docs.microsoft.com/windows/uwp/debug-test-perf/loose-file-registration). When building in **Debug** mode (which is the default), `npx react-native run-windows` performs loose-file registration of your app in order to install it locally. When running `npx react-native run-windows` with the `--release` switch, the CLI will install the real package onto your local machine. This requires the app to be signed and for the certificate it uses for signing to be trusted by the machine the app is going to be installed on. See [Create a certificate for package signing](https://docs.microsoft.com/windows/msix/package/create-certificate-package-signing) and [Intro to certificates](https://docs.microsoft.com/windows/uwp/security/certificates). +For internal development, you can deploy your app for test purposes by side-loading and deploying via [loose-file registration](https://docs.microsoft.com/windows/uwp/debug-test-perf/loose-file-registration). When building in **Debug** mode (which is the default), the [run-windows command](run-windows-cli.md) performs loose-file registration of your app in order to install it locally. When building with the `--release` switch, the CLI will install the real package onto your local machine. This requires the app to be signed and for the certificate it uses for signing to be trusted by the machine the app is going to be installed on. See [Create a certificate for package signing](https://docs.microsoft.com/windows/msix/package/create-certificate-package-signing) and [Intro to certificates](https://docs.microsoft.com/windows/uwp/security/certificates). ### Debugging crashes and reporting issues If your app is "hard crashing" (the native code hits an error condition and your app closes), you will want to investigate the native side of the code. If the issue is in the `Microsoft.ReactNative` layer, please file a bug in the [React Native for Windows](https://github.com/microsoft/react-native-windows) repo, and provide a native stack trace, and ideally a crash dump with symbols. diff --git a/docs/native-modules-autolinking.md b/docs/native-modules-autolinking.md index 3c0b98b61..8565ab52e 100644 --- a/docs/native-modules-autolinking.md +++ b/docs/native-modules-autolinking.md @@ -26,7 +26,7 @@ The information provided by `config` is described in [React Native Config Schema ## Autolinking process -Autolinking is performed automatically as a part of the `run-windows` command: +Autolinking is performed automatically as a part of the [run-windows command](run-windows-cli.md): 1. At build time, autolinking is performed first, before `msbuild.exe` is invoked and the build actually started. It uses the information provided by `config` to both generate and modify certain native files consumed by your app project. 1. The `AutolinkedNativeModules.g.targets` file contains the necessary references to the dependency projects that must be built. @@ -41,26 +41,11 @@ Autolinking is performed automatically as a part of the `run-windows` command: ### Manually run autolinking -If you would like to run the autolinking process outside of the build, you can use the `autolink-windows` CLI command, i.e.: - -```bat -npx react-native autolink-windows -``` - -| Options | | -|:--------|:-| -| `--logging` | Verbose output logging | -| `--check` | Only check whether any autolinked files need to change | -| `--sln` [string] | Override the app solution file determined by `react-native config`, e.g. *`windows\myApp.sln`* | -| `--proj` [string] | Override the app project file determined by `react-native config`, e.g. *`windows\myApp\myApp.vcxproj`* | -| `--no-telemetry` [boolean] | Disables sending telemetry that allows analysis of usage and failures of the react-native-windows CLI | -| `-h`, `--help` | output usage information | - -This sends telemetry to Microsoft by default. You can prevent the telemetry from being sent by using the `--no-telemetry` command line option. See the `@react-native-windows/cli` [README](https://github.com/microsoft/react-native-windows/tree/main/packages/%40react-native-windows/cli#data-collection) for more details. +If you would like to run the autolinking process outside of the build, you can run the [autolink-windows command](autolink-windows-cli.md) manually at any time. ### Skipping autolinking -If you would like to skip the autolinking process during `run-windows` you can pass `--no-autolink` option: +If you would like to skip the autolinking process during [run-windows command](run-windows-cli.md) you can pass `--no-autolink` option: ```bat npx react-native run-windows --no-autolink diff --git a/docs/native-modules-setup.md b/docs/native-modules-setup.md index 08b10f437..34c1ff58d 100644 --- a/docs/native-modules-setup.md +++ b/docs/native-modules-setup.md @@ -28,7 +28,7 @@ Once your development environment has been correctly configured, you have severa If you are only planning on adding a native module to your existing React Native Windows app, i.e.: 1. You followed the [Getting Started](getting-started.md) guide, where -1. You ran `npx react-native-windows-init` to add Windows to your project, and +1. You used the [init-windows command](init-windows-cli.md) to add Windows to your project, and 1. You are just adding your native code to the app project under the `windows` folder. Then you can simply open the Visual Studio solution in the `windows` folder and add the new files directly to the app project. @@ -93,16 +93,23 @@ Again, take the result of that command (let's say it's `0.x.y`) and use it to up yarn upgrade react-native@0.x.y --dev ``` -Now you should be ready to add Windows support with `react-native-windows-init`. The process is similar to adding Windows support to an app project, but you'll need to specify `--projectType lib`: +Next add `react-native-windows` to your dependencies: ```bat -npx react-native-windows-init --version latest --projectType lib --overwrite +yarn add react-native-windows@latest +yarn install +``` + +Now you should be ready to add Windows support with the [init-windows command](init-windows-cli.md). The process is similar to adding Windows support to an app project, but you'll need to specify a library template: + +```bat +npx react-native init-windows --template old/uwp-cpp-lib --overwrite ``` This defaults to a C++/WinRT project. If you want to create a C# based native module project, use: ```bat -npx react-native-windows-init --version latest --projectType lib --language cs --overwrite +npx react-native init-windows --template old/uwp-cs-lib --overwrite ``` That's it, you should be able to open `windows\NativeModuleSample.sln` and start working on your project. diff --git a/docs/native-modules-using.md b/docs/native-modules-using.md index e469652ac..d91366f00 100644 --- a/docs/native-modules-using.md +++ b/docs/native-modules-using.md @@ -5,7 +5,7 @@ title: Using Community Native Modules Community native modules are usually distributed as npm packages. To understand more about npm packages you may find [this guide](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry) useful. -Consuming native modules requires updating your app's native build files to depend on the module's native build files, called "linking". Many modules support "autolinking", where these updates are done automatically when running `npx react-native run-windows`. Others may require you to link the module manually. +Consuming native modules requires updating your app's native build files to depend on the module's native build files, called "linking". Many modules support "autolinking", where these updates are done automatically when running the [run-windows command](run-windows-cli.md). Others may require you to link the module manually. This document outlines the general steps to manually link a module (`react-native-foo`) to your project. diff --git a/docs/nuget-update.md b/docs/nuget-update.md index f583fe233..6a9975d9a 100644 --- a/docs/nuget-update.md +++ b/docs/nuget-update.md @@ -5,7 +5,7 @@ title: Updating NuGet packages >**This documentation and the underlying platform code is a work in progress.** -The versions of the [NuGet](nuget.md) packages used in your project must match the version of the react-native-windows npm package. +The versions of the [NuGet](nuget.md) packages used in your project must match the version of the `react-native-windows` npm package. For React Native for Windows versions >= 0.68, the default app template takes care of this for you automatically. However if you're not using the supported template, the steps below may help you consume the NuGet packages manually. # Determine npm version You can find the npm version by opening `package.json` at the root of your project and looking in the dependencies section: diff --git a/docs/nuget.md b/docs/nuget.md index 5597f404c..21eedbb05 100644 --- a/docs/nuget.md +++ b/docs/nuget.md @@ -1,11 +1,11 @@ --- id: NuGet -title: Using react-native-windows NuGet packages +title: Using Microsoft.ReactNative NuGet packages --- >**This documentation and the underlying platform code is a work in progress.** -The default for react-native-windows has been to build all code from source. This includes building all the code shipped by the react-native-windows team in the npm package from source. This code can be quite large and take a long time to build as well as require a high-performance computer. Some configurations have problems building this code with only 8 GB of memory. Especially if you are used to working only with managed code, this can be a big surprise. +The default for React Native Windows has been to build all code from source. This includes building all the code shipped by the team in the npm package from source. This code can be quite large and take a long time to build as well as require a high-performance computer. Some configurations have problems building this code with only 8 GB of memory. Especially if you are used to working only with managed code, this can be a big surprise. Starting with version 0.64 the team offers experimental NuGet packages that can be used as a replacement of compiling the sources. @@ -13,19 +13,17 @@ Starting with version 0.64 the team offers experimental NuGet packages that can The benefit of using NuGet packages is that you get improved compilation times for your Windows project and can develop on a less powerful computer. -The other benefit will be that it will be easier to update your projects to future versions or react-native-windows. +The other benefit will be that it will be easier to update your projects to future versions of `react-native-windows`. # How to enable on new projects -When you enable react-native-windows on your new project, you can pass `--experimentalNuGetDependency true`: + When creating a new project in [Get Started with Windows](getting-started.md), the templates used by the [init-windows command](init-windows-cli.md) default to building against source. Follow the instructions below if you wish to try using the NuGet packages. -1. Follow the instructions to create a new project in [Getting Started](getting-started.md) except use: -1. `npx react-native-windows-init --overwrite --experimentalNuGetDependency true` instead when adding windows support to your project - -Of course all the other flags still work. +> Note: The formerly recommended [React Native Windows Init CLI](https://microsoft.github.io/react-native-windows/init-cli) still supports an `--experimentalNuGetDependency true` flag to set up a new project which uses the NuGet packages, but as that command is planned for deprecation, it's not recommended. # How to update a previously created project +The steps below will help you modify your RNW project so you can consume the RNW NuGet packages. -> Note: It may be easier to attempt upgrading your app with `react-native-windows-init` as if it were a new project (described above), to get the correct changes applied to your project. See [Upgrading App to Latest Version of React Native Windows](upgrade-app.md). Otherwise, you can try applying the manual steps below. +> Note: If you're in the process of upgrading your app to a new version of RNW (See [Upgrading App to Latest Version of React Native Windows](upgrade-app.md)), and you've already set the `true` flag (as per below), the [init-windows command](init-windows-cli.md) will try to respect that setting so you shouldn't have to re-apply the manual steps below after the upgrade. diff --git a/docs/react-native-windows-cli.md b/docs/react-native-windows-cli.md new file mode 100644 index 000000000..7f430bf25 --- /dev/null +++ b/docs/react-native-windows-cli.md @@ -0,0 +1,32 @@ +--- +id: react-native-windows-cli +title: React Native Windows CLI +--- + +When React Native for Windows is added to a React Native project, a variety of Windows-specific developer commands are added to the `react-native` CLI. + +> The following commands are provided by the the `@react-native-windows/cli` NPM package. + +## `react-native autolink-windows` + +Runs Windows-specific autolinking for your RNW project. + +See the [react-native autolink-windows docs](autolink-windows-cli.md) for detailed usage information. + +## `react-native codegen-windows` + +Runs Windows-specific codegen for native modules. + +See the [react-native codegen-windows docs](codegen-windows-cli.md) for detailed usage information. + +## `react-native init-windows` + +Initializes a new RNW project from a given template. + +See the [react-native init-windows docs](init-windows-cli.md) for detailed usage information. + +## `react-native run-windows` + +Builds your RNW app and starts it on a connected Windows desktop, emulator, or device. + +See the [react-native run-windows docs](run-windows-cli.md) for detailed usage information. diff --git a/docs/releases.md b/docs/releases.md index 2a399b590..995ae2b57 100644 --- a/docs/releases.md +++ b/docs/releases.md @@ -10,6 +10,6 @@ For every major version update of `react-native`, React Native for Windows relea `canary` builds are built directly from our main branch. These builds provide no guarantees around upstream React version, breaking changes, or overall stability. These builds should be used for development or to test bleeding edge functionality but should not be relied upon for production use. Master builds are versioned as `0.0.0-canary.x`. -`preview` builds are the first released by stable branches. These builds aim to become increasingly polished over time and have fewer breaking changes than in canary. react-native-windows-init will work out of the box with preview builds when none else are available, but will warn users before installing them. Preview builds are versioned as `0.x.0-preview.y`, where x matches the minor release of React Native. +`preview` builds are the first released by stable branches. These builds aim to become increasingly polished over time and have fewer breaking changes than in canary. Preview builds are versioned as `0.x.0-preview.y`, where x matches the minor release of React Native. `latest` builds corresponding to our "released" version. Breaking changes should not be made to stable branches after promotion to latest. Caution must be taken to not compromise the stability of our non-prerelease branches. Only low risk changes critical to customer scenarios should be back-ported. Released builds are versioned as `0.x.y` where x matches the minor release of React Native. diff --git a/docs/run-windows-cli.md b/docs/run-windows-cli.md index eb6477801..71c5ec921 100644 --- a/docs/run-windows-cli.md +++ b/docs/run-windows-cli.md @@ -1,16 +1,16 @@ --- id: run-windows-cli -title: React Native Windows CLI +title: react-native run-windows --- -This guide will give you more information on the React Native Windows CLI. +This guide will give you more information on the `run-windows` command of the React Native Windows CLI. -## `@react-native-windows/cli` +## `run-windows` -`@react-native-windows/cli` is a CLI used to build and run React Native for Windows apps. +The `run-windows` CLI command is used to build and run React Native for Windows apps. ### Usage -Run this from an existing React Native for Windows app to build and deploy. +Builds your RNW app and starts it on a connected Windows desktop, emulator, or device. ```bat npx react-native run-windows @@ -23,35 +23,33 @@ Here are the options that `react-native run-windows` takes: | Option | Input Type | Description | |-----------------------|------------|--------------------------------------------------| | `--release` | boolean | Specifies a Release build | -| `--root` | string | Override the root directory for the windows build which contains the windows folder. (default: `E:\\test63`) | -| `--arch` | string | The build architecture (`ARM64`, `x86`, `x64`). defaults to system architecture | +| `--root` | string | Override the root directory for the project which contains the `windows` folder | +| `--arch` | string | The build architecture, i.e. `ARM64`, `x86`, `x64`. Defaults to system architecture | | `--singleproc` | boolean | Disables multi-proc build | | `--emulator` | boolean | Deploys the app to an emulator | | `--device` | boolean | Deploys the app to a connected device | | `--target` | string | Deploys the app to the specified `GUID` for a device | -| `--remote-debugging` | boolean | **(Deprecated)** Deploys the app in remote debugging mode. | -| `--logging` | boolean | Enables logging | -| `--no-packager` | boolean | Do not launch packager while building | -| `--bundle` | boolean | Enable Bundle configuration and it would be `ReleaseBundle`/`DebugBundle` other than `Release`/`Debug` | +| `--remote-debugging` | boolean | **(Deprecated)** Deploys the app in remote debugging mode | +| `--logging` | boolean | Verbose output logging | +| `--no-packager` | boolean | Do not launch the packager while building | +| `--bundle` | boolean | Enable Bundle configuration, i.e. `ReleaseBundle`/`DebugBundle` rather than `Release`/`Debug` | | `--no-launch` | boolean | Do not launch the app after deployment | | `--no-autolink` | boolean | Do not run autolinking | | `--no-build` | boolean | Do not build the solution | | `--no-deploy` | boolean | Do not deploy the app | -| `--deploy-from-layout`| boolean | Force deploy from layout, even in release builds | -| `--sln` | string | Override the app solution file determined by 'react-native config', e.g. `windows\myApp.sln` | -| `--proj` | string | Override the app project file determined by 'react-native config', e.g. `windows\myApp\myApp.vcxproj` | -| `--msbuildprops` | string | Comma separated props to pass to MSBuild, e.g. `prop1=value1,prop2=value2` | +| `--deploy-from-layout`| boolean | Force deploy from layout even in Release builds | +| `--sln` | string | Override the app solution file determined by 'react-native config', i.e. `windows\myApp.sln` | +| `--proj` | string | Override the app project file determined by 'react-native config', i.e. `windows\myApp\myApp.vcxproj` | +| `--msbuildprops` | string | Comma separated props to pass to MSBuild, i.e. `prop1=value1,prop2=value2` | | `--buildLogDirectory` | string | Optional directory where MSBuild log files should be stored | | `--info` | boolean | Dump environment information | | `--direct-debugging` | number | Enable direct debugging on specified port | -| `--useWinUI3` | boolean | Targets `WinUI` 3.0 (Preview) instead of UWP XAML. | -| `--useHermes` | boolean | Use Hermes instead of Chakra as the JS engine (supported on 0.64+) | | `--no-telemetry` | boolean | Disables sending telemetry that allows analysis of usage and failures of the react-native-windows CLI | -| `-h`, `--help` | boolean | output usage information | +| `-h`, `--help` | boolean | Display help for command | -This sends telemetry to Microsoft by default. You can prevent the telemetry from being sent by using the `--no-telemetry` command line option. See the below for more details. +This sends telemetry to Microsoft by default. You can prevent the telemetry from being sent by using the `--no-telemetry` command line option. See below for more details. The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices. -This data collection notice only applies to the process of running the react-native-windows CLI (run-windows and related tools like autolinking). +This data collection notice only applies to the process of running the react-native-windows CLI commands. \ No newline at end of file diff --git a/docs/upgrade-app.md b/docs/upgrade-app.md index 1775cabc6..488126b6a 100644 --- a/docs/upgrade-app.md +++ b/docs/upgrade-app.md @@ -3,11 +3,11 @@ id: upgrade-app title: Upgrading App to Latest Version of React Native Windows --- ## Upgrading A React Native Windows App -Upgrading your app to new React Native Windows versions requires a small amount of effort, but we will try to streamline this process for you as much as possible in this guide. You have two main options for how to upgrade your React Native Windows app. You can use the [React Native Windows CLI](https://github.com/microsoft/react-native-windows/blob/7b3510aebdbc79189278206a53e26213897d6ff8/packages/react-native-windows-init/README.md) or manually upgrade using [Upgrade Helper](https://reactnative.dev/docs/upgrading#upgrade-helper). +Upgrading your app to new React Native Windows versions requires a small amount of effort, but we will try to streamline this process for you as much as possible in this guide. You have two main options for how to upgrade your React Native Windows app. You can use the [init-windows command](init-windows-cli.md) or manually upgrade using [Upgrade Helper](https://reactnative.dev/docs/upgrading#upgrade-helper). ### Steps to Upgrade An App to New React Native Windows Version via CLI -1. In the root of your project, run `npx react-native-windows-init --version 0.XX.X --overwrite`. -2. In the root of your project, run `npx react-native autolink-windows` to link any native modules used by your app. +1. In the root of your project, run the [init-windows command](init-windows-cli.md) (make sure you're using the correct template). +2. In the root of your project, run the [autolink-windows command](autolink-windows-cli.md) to link any native modules used by your app. 3. Step 1 will overwrite any changes you previously made to the native Windows code of your project and generate a new GUID. If you made changes to this code or wish to keep your previous GUID, you have two options: 1. Add those changes manually. diff --git a/docs/view-managers.md b/docs/view-managers.md index 59ca3a24e..2457ab2ea 100644 --- a/docs/view-managers.md +++ b/docs/view-managers.md @@ -37,7 +37,7 @@ Once you have set up your development environment and project structure, you are If you are only planning on adding a native module to your existing React Native Windows app, i.e.: 1. You followed [Getting Started](getting-started.md), where -1. You ran `npx react-native-windows-init --overwrite` to add Windows to your project, and +1. You used the [init-windows command](init-windows-cli.md) to add Windows to your project, and 1. You are just adding your native code to the app project under the `windows` folder. Then you can simply open the Visual Studio solution in the `windows` folder and add the new files directly to the app project. diff --git a/website/pages/en/init-cli.js b/website/pages/en/init-cli.js index 85cee68dd..d1b29b154 100644 --- a/website/pages/en/init-cli.js +++ b/website/pages/en/init-cli.js @@ -20,8 +20,7 @@ class InitCli extends React.Component { React Native Windows Init CLI

- This guide will give you more information on the React Native Windows - CLI. + This guide will give you more information on the React Native Windows Init CLI.

react-native-windows-init

diff --git a/website/sidebars.json b/website/sidebars.json index 5f3ee7e63..a23127096 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -3,7 +3,7 @@ "The Basics (Windows)": [ "getting-started", "rnw-dependencies", - "run-windows-cli", + "react-native-windows-cli", "parity-status", "config", "windowsbrush-and-theme", @@ -13,6 +13,12 @@ "setup-ci", "app-publishing" ], + "CLI Commands (Windows)": [ + "autolink-windows-cli", + "codegen-windows-cli", + "init-windows-cli", + "run-windows-cli" + ], "Native Modules (Windows)": [ "native-modules", "view-managers",