Skip to content

Commit

Permalink
Update all raw references to CLI commands with links to the CLI comma…
Browse files Browse the repository at this point in the history
…nd page
  • Loading branch information
jonthysell committed Jun 26, 2024
1 parent 23911c3 commit c7ee826
Show file tree
Hide file tree
Showing 15 changed files with 42 additions and 37 deletions.
2 changes: 1 addition & 1 deletion docs/autolink-windows-cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ This guide will give you more information on the `autolink-windows` command of t

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` CLI command, unless the `--no-autolink` argument is used.
**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.
Expand Down
12 changes: 6 additions & 6 deletions docs/debugging-javascript.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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*
Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ npx react-native init-windows --overwrite

> **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.
> **Note:** Previous versions of the RNW Getting Started steps recommend the use of the `react-native-windows-init` command, which is being deprecated. While it's still available, information on the `react-native-windows-init` command is here: [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

Expand Down
4 changes: 2 additions & 2 deletions docs/hermes.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 4 additions & 4 deletions docs/native-code.md
Original file line number Diff line number Diff line change
Expand Up @@ -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#.

Expand All @@ -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 <u>**RNW apps are UWP apps**</u> and therefore have the following characteristics:

Expand Down Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docs/native-modules-autolinking.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ If you would like to run the autolinking process outside of the build, you can r

### 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
Expand Down
15 changes: 11 additions & 4 deletions docs/native-modules-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docs/native-modules-using.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion docs/nuget-update.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
16 changes: 7 additions & 9 deletions docs/nuget.md
Original file line number Diff line number Diff line change
@@ -1,31 +1,29 @@
---
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.

> Disclaimer: There are known compatibility issues with [community modules](supported-community-modules.md), as they still rely on building the shared code from source. So the solution still needs to have all the source projects which puts all the build performance problems back.
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 `<UseExperimentalNuGet>true</UseExperimentalNuGet>` 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.
<!--DOCUSAURUS_CODE_TABS-->
<!--C# projects-->
Expand Down
Loading

0 comments on commit c7ee826

Please sign in to comment.