-
Notifications
You must be signed in to change notification settings - Fork 202
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
d8a9ecc
commit 049e90d
Showing
10 changed files
with
291 additions
and
7 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,135 @@ | ||
| --- | ||
| id: version-0.77-getting-started | ||
| title: Get Started with Windows | ||
| original_id: getting-started | ||
| --- | ||
|
|
||
| This guide will help you get started on setting up your very first React Native for Windows app. | ||
|
|
||
| Make sure you have installed all of the [development dependencies](rnw-dependencies.md). | ||
|
|
||
| For information around how to set up React Native, see the [React Native Getting Started Guide](https://reactnative.dev/docs/getting-started). | ||
|
|
||
| > **Interested in migrating to [React Native's New Architecture](https://reactnative.dev/architecture/landing-page)?** New Architecture support in React Native for Windows is now available to preview in 0.76. Note there are several key changes, so if you’d like to be an early adopter, check out the information in the [New Architecture Guide](new-architecture.md). | ||
| ## Create a new React Native project | ||
|
|
||
| Remember to call `@react-native-community/cli init` from the place you want your project directory to live. | ||
|
|
||
| <!-- Note, make sure both `@react-native-community/cli@ABC` and `--version "XYZ"` are pointing to the correct NPM tags in the command below. --> | ||
|
|
||
| <!-- 1. For the next version (i.e. in docs/getting-started.md) use "next" for the CLI and "nightly" for the RN version --> | ||
| <!-- 2. For the latest stable version in versioned_docs use "latest" for both the CLI and RN version --> | ||
| <!-- 3. For older stable versions you'll have to look up the CLI version, but for the RN version use the stable tag name, i.e. "0.73-stable" --> | ||
|
|
||
| <!-- See https://www.npmjs.com/package/@react-native-community/cli?activeTab=versions for the CLI version tags. --> | ||
| <!-- See https://www.npmjs.com/package/react-native?activeTab=versions for the RN version tags. --> | ||
|
|
||
| ```bat | ||
| npx --yes @react-native-community/cli@next init <projectName> --version "latest" | ||
| ``` | ||
|
|
||
| ### Navigate into this newly created directory | ||
|
|
||
| React Native will have created your project in a new sub-directory, which you must enter before continuing. | ||
|
|
||
| ```bat | ||
| cd <projectName> | ||
| ``` | ||
|
|
||
| ### Add React Native Windows to your project's dependencies | ||
|
|
||
| <!-- Note, make sure "version" is pointing to the correct react-native-windows NPM tag in the command below. --> | ||
|
|
||
| <!-- 1. For the next version (i.e. in docs/getting-started.md) use "canary" --> | ||
| <!-- 2. For other versions in versioned_docs use the version in the format "^0.XY.0" --> | ||
|
|
||
| <!--DOCUSAURUS_CODE_TABS--> | ||
|
|
||
| <!--Using Yarn (Recommended)--> | ||
|
|
||
| ```bat | ||
| yarn add react-native-windows@^0.77.0 | ||
| ``` | ||
|
|
||
| <!--Using NPM--> | ||
|
|
||
| ```bat | ||
| npm install --save react-native-windows@^0.77.0 | ||
| ``` | ||
|
|
||
| <!--END_DOCUSAURUS_CODE_TABS--> | ||
|
|
||
| ### 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 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. | ||
| ## Running a React Native Windows App | ||
|
|
||
| > Make sure a browser is launched and running before running a React Native Windows app. | ||
| > Also ensure your system meets all the [requirements](rnw-dependencies.md) to build a Windows app as well. | ||
| - Without Using Visual Studio | ||
|
|
||
| In your React Native Windows project directory, run the [run-windows command](run-windows-cli.md): | ||
|
|
||
| ```bat | ||
| npx react-native run-windows | ||
| ``` | ||
|
|
||
| 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 [autolink-windows command](autolink-windows-cli.md), which will automatically link your app's dependencies: | ||
| ```bat | ||
| npx react-native autolink-windows | ||
| ``` | ||
| - Open the solution file in the application folder in Visual Studio (e.g., `AwesomeProject/windows/AwesomeProject.sln` if you used `AwesomeProject` as `<projectName>`) | ||
| - Select the `Debug` configuration and the `x64` platform from the combo box controls to the left of the `Run` button and underneath the `Team` and `Tools` menu item. | ||
| - Run `yarn start` (or `npm start`) from your project directory, and wait for the React Native packager to report success. | ||
| - Click the `Run` button to the right of the platform combo box control in VS, or select the `Debug`->`Start without Debugging` menu item. You now see your new app and Chrome should have loaded `http://localhost:8081/debugger-ui/` in a new tab. Press `F12` or `Ctrl+Shift+I` in Chrome to open its Developer Tools. :tada: | ||
| - With VS Code | ||
| - Open your applications folder in VS Code. | ||
| - Install the [React Native Tools](https://marketplace.visualstudio.com/items?itemName=msjsdiag.vscode-react-native) plugin for VS Code. | ||
| - Create a new file in the applications root directory, `.vscode/launch.json` and paste the following configuration: | ||
| ```json | ||
| { | ||
| "version": "0.2.0", | ||
| "configurations": [ | ||
| { | ||
| "name": "Debug Windows", | ||
| "cwd": "${workspaceFolder}", | ||
| "type": "reactnative", | ||
| "request": "launch", | ||
| "platform": "windows" | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
| - Press `F5` or navigate to the debug menu (alternatively press `Ctrl+Shift+D`) and in the Debug drop-down select "Debug Windows" and press the green arrow to run the application. | ||
|
|
||
| ## Authoring Native Modules | ||
|
|
||
| See [Native Modules and React Native Windows](native-modules.md). | ||
|
|
||
| ## Building a standalone React Native Windows App | ||
|
|
||
| Follow these steps to build a version of your app that you can install or publish to the store. This version will package your bundle and assets into the APPX package so you don't need to run Metro. | ||
|
|
||
| - Open the solution in Visual Studio | ||
| - Select the Release configuration from the Configuration Manager drop-down. | ||
| - Build the solution. You can now launch without first launching Metro. | ||
| - If you want to build an APPX package to share or publish, use the **Project** > **Publish** > **Create App Packages...** option. | ||
|
|
||
| > The Debug configuration uses the Web Debugger by default, which means the application's JavaScript code runs in Chrome.<br> | ||
| > If you're getting different runtime behavior between the Release and Debug configurations, consider disabling the `UseWebDebugger` setting in [`App.cpp`](https://github.com/microsoft/react-native-windows/blob/6b415659aa017dbc41e3f28e817fb768a8e80435/vnext/template/cpp-app/src/App.cpp#L30) or [`App.xaml.cs`](https://github.com/microsoft/react-native-windows/blob/6b415659aa017dbc41e3f28e817fb768a8e80435/vnext/template/cs-app/src/App.xaml.cs#L20) to get the same behavior in the Debug configuration. | ||
| See also this article for additional details: https://techcommunity.microsoft.com/t5/windows-dev-appconsult/getting-started-with-react-native-for-windows/ba-p/912093# |
53 changes: 53 additions & 0 deletions
53
website/versioned_docs/version-0.77/native-modules-autolinking.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,53 @@ | ||
| --- | ||
| id: version-0.77-native-modules-autolinking | ||
| title: Autolinking Native Modules | ||
| original_id: native-modules-autolinking | ||
| --- | ||
|
|
||
| Autolinking is a mechanism that allows your React Native app project to discover and use native modules and view managers provided by React Native libraries. | ||
|
|
||
| This document covers autolinking for the Windows platform. It is an extension to the [React Native CLI Autolinking doc](https://github.com/react-native-community/cli/blob/master/docs/autolinking.md). | ||
|
|
||
| Add a library using your favorite package manager and run the build: | ||
|
|
||
| ```bat | ||
| yarn add react-native-webview | ||
| npx react-native run-windows | ||
| ``` | ||
|
|
||
| That's it. No more editing native files to use native code. | ||
|
|
||
| ## How does it work | ||
|
|
||
| From the [React Native CLI Autolinking doc](https://github.com/react-native-community/cli/blob/master/docs/autolinking.md#how-does-it-work): | ||
|
|
||
| > Each platform defines its own [`platforms`](https://github.com/react-native-community/cli/blob/master/docs/platforms.md) configuration. It instructs the CLI on how to find information about native dependencies. This information is exposed through the [`config`](https://github.com/react-native-community/cli/blob/master/docs/commands.md#config) command in a JSON format. It's then used by the scripts run by the platform's build tools. Each script applies the logic to link native dependencies specific to its platform. | ||
| The information provided by `config` is described in [React Native Config Schema](config.md). | ||
|
|
||
| ## Autolinking process | ||
|
|
||
| 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.props` and `AutolinkedNativeModules.g.targets` file contains the necessary references to the dependency projects that must be built. | ||
| > Your app's solution file may also be modified to ensure the dependency projects will be built. | ||
| 1. The `AutolinkedNativeModules.g.(cpp|cs)` files contain a `RegisterAutolinkedNativeModulePackages` method which registers all of the specified `IReactPackageProvider`s from the dependencies. | ||
| 1. At build time, while `msbuild.exe` is running, but before compiling your app project, a check will verify that the autolinked files are up-to-date, and warn you if they aren't. | ||
| > If you're using `run-windows` this check should always pass. However, if you've manually edited the generated files, or changed your npm dependencies and are building manually with Visual Studio, then the check might fail. See [manually run autolinking](#manually-run-autolinking). | ||
| 1. At runtime, when your app is starting up it will call `RegisterAutolinkedNativeModulePackages`, registering the native dependencies with React Native, making them available to JS code. | ||
|
|
||
| ## Alternatives | ||
|
|
||
| ### Manually run autolinking | ||
|
|
||
| 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 command](run-windows-cli.md) you can pass `--no-autolink` option: | ||
|
|
||
| ```bat | ||
| npx react-native run-windows --no-autolink | ||
| ``` |
32 changes: 32 additions & 0 deletions
32
website/versioned_docs/version-0.77/native-modules-vs-turbo-modules.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,32 @@ | ||
| --- | ||
| id: version-0.77-native-modules-vs-turbo-modules | ||
| title: Native Modules vs Turbo Modules | ||
| original_id: native-modules-vs-turbo-modules | ||
| --- | ||
|
|
||
| If you've worked with React Native, you may be familiar with the concept of Native Modules, which allow JavaScript and platform-native code to communicate over the React Native "bridge", which handles cross-platform serialization via JSON. | ||
|
|
||
| TurboModules are the next iteration of Native Modules that provide a few extra benefits, in particular these modules use JSI, a JavaScript interface for native code, which allows for more efficient communication between native and JavaScript code than the bridge. | ||
|
|
||
| ### How to migrate to TurboModules | ||
|
|
||
| Modules running as TurboModules will be available in the JS from `TurboModuleRegistry.get('<modulename>')` instead of `NativeModules.<modulename>`. So your JavaScript will have to be updated before switching. Ideally while you are at it, you should switch your modules to use [Spec files](https://reactnative.dev/docs/the-new-architecture/pillars-turbomodules#2-javascript-specification). This will make your modules compatible with codegen. | ||
|
|
||
| >**Note:** `TurboModuleRegistry` will fallback to returning a native module instead of a turbo module if there is a native module registered from the native code. So you can update your JavaScript before updating your native code. | ||
| Starting in version 0.71, JS/TS spec files can codegen C++ spec files that can verify that the native implementation matches the definition in JS. In addition modules can now be run as TurboModules instead of as a Native Module simply by using adding an additional parameter to your call to `AddAttributedModules`: | ||
|
|
||
| ```cpp | ||
| AddAttributedModules(packageBuilder, true); | ||
| ``` | ||
| Alternatively if you are registering modules more manually by calling `IReactPackageBuilder.AddModule`, you can call `IReactPackageBuilder.AddTurboModule` instead. | ||
| ### Additional differences running as Native Module vs TurboModule | ||
| After creating a spec in JS, you should see JS type errors showing that constants should be accessed using `MyModule.getConstants().myconst` instead of `MyModule.myconst`. If you fail to update you accesses of `myconst` the field will continue to work when the module is running as a Native Module, since Native Modules promote all the constants to fields on the module. This behavior does not happen with TurboModules, so the `myconst` field will be undefined. Calls using `getConstants().myconst` will work both for Native Modules and TurboModules. | ||
| ### Web Debugging Behavior | ||
| TurboModules cannot run when using Remote Debugging / Web Debugging. React-Native-Windows will attempt to run a TurboModule as a native module when running in that mode, but if the module is using JSI directly, that fallback may not work. | ||
51 changes: 51 additions & 0 deletions
51
website/versioned_docs/version-0.77/rnm-getting-started.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,51 @@ | ||
| --- | ||
| id: version-0.77-rnm-getting-started | ||
| title: Get Started with macOS | ||
| original_id: rnm-getting-started | ||
| --- | ||
|
|
||
| This guide will help you get started on setting up your very first React Native for macOS app. | ||
|
|
||
| >** Latest stable version available for React Native for macOS is 0.76** | ||
| For information around how to set up: | ||
| - React Native for iOS and Android: See [React Native Getting Started Guide](https://reactnative.dev/docs/getting-started) | ||
| - React Native for Windows: See [React Native for Windows Getting Started Guide](https://microsoft.github.io/react-native-windows/docs/getting-started) | ||
|
|
||
| ## Install React Native for macOS | ||
|
|
||
| Remember to call `react-native init` from the place you want your project directory to live. Be sure to use the same minor version between React Native and React Native macOS. We'll use `^0.71.0` | ||
|
|
||
| ``` | ||
| npx react-native@latest init <projectName> --version 0.76.0 | ||
| ``` | ||
|
|
||
| ### 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. | ||
|
|
||
| ``` | ||
| cd <projectName> | ||
| ``` | ||
|
|
||
| ### Install the macOS extension | ||
|
|
||
| Install the React Native for macOS packages. | ||
|
|
||
| ``` | ||
| npx react-native-macos-init | ||
| ``` | ||
|
|
||
| ## Running a React Native macOS App | ||
|
|
||
| - **Without using Xcode**: | ||
| In your React Native macOS project directory, run: | ||
|
|
||
| ``` | ||
| npx react-native run-macos | ||
| ``` | ||
|
|
||
| - **Using Xcode**: | ||
| Open `macos\test.xcworkspace` in Xcode or run `xed -b macos`; `yarn start`. Hit the Run button. | ||
|
|
||
| A new Command Prompt window will open with the React packager as well as a `react-native-macos` 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! 🎉 |
Oops, something went wrong.