diff --git a/docs/config.md b/docs/config.md new file mode 100644 index 000000000..758faeca0 --- /dev/null +++ b/docs/config.md @@ -0,0 +1,175 @@ +--- +id: config +title: React Native Config Schema +--- + +The CLI command [`npx react-native config`](https://github.com/react-native-community/cli/blob/master/docs/commands.md#config) outputs project and dependencies configuration in JSON format to stdout. + +The following describes the schema for projects and dependencies provided by React Native for Windows. + +> See the [React Native CLI Platforms doc](https://github.com/react-native-community/cli/blob/master/docs/platforms.md) for a description of the schemas for iOS and Android. + +The schema fields are tagged with the following: + +| Tag | Description | +|:-------|:------------| +| *auto* | Item is always calculated by config. An override file should NEVER provide it. | +| *req* | Item is required. If an override file exists, it MUST provide it. If no override file exists, config will try to calculate it. | +| *opt* | Item is optional. If an override file exists, it MAY provide it. If no override file exists, config may try to calculate it. | + +## projectConfig + +`react-native config` will generate the following JSON for app projects that have a Windows implementation, as a target for auto-linking. This is done heuristically, so if the result isn't quite correct, app developers can provide a manual override file: `react-native.config.js`. + +### Schema: + +```js +{ + folder: string, + sourceDir: string, + solutionFile: string, + project: { + projectFile: string, + projectName: string, + projectLang: string, + projectGuid: string, + }, +} +``` + +### Top-Level Fields: + +The top-level object has the following fields: + +| Field | Type | Tag | Description | +|:------|:----:|:----:|:------------| +| folder | string | auto | Absolute path to the app root folder, determined by `react-native config`, ex: *'c:\path\to\my-app'* | +| sourceDir | string | req | Relative path to the windows implementation under *folder*, ex: *'windows'* | +| solutionFile | string | req | Relative path to the app's VS solution file under *sourceDir*, ex: *'MyApp.sln'* | +| project | object | req | Object describing the app's VS project | + +### Project Object Fields: + +The top-level `project` has the following fields: + +| Field | Type | Tag | Description | +|:------|:----:|:----:|:------------| +| projectFile | string | req | Relative path to the VS project file under *sourceDir*, ex: *'MyApp\MyApp.vcxproj'* for *'c:\path\to\my-app\windows\MyApp\MyApp.vcxproj'* | +| projectName | string | auto | Name of the project, determined from *projectFile*, ex: *'MyApp'* | +| projectLang | string | auto | Language of the project, `cpp` (for C++) or `cs` (for C#), determined from *projectFile* | +| projectGuid | string | auto | Project identifier, determined from *projectFile* | + +### Example `react-native.config.js` for a *MyApp*: + +```js +module.exports = { + project: { + windows: { + sourceDir: 'windows', + solutionFile: 'MyApp.sln', + project: { + projectFile: 'MyApp\\MyApp.vcxproj', + }, + }, + }, +}; +``` + +## dependencyConfig + +`react-native config` will generate the following JSON for each native module dependency under `node_modules` that has a Windows implementation, in order to support auto-linking. This is done heuristically, so if the result isn't quite correct, native module developers can provide a manual override file: `react-native.config.js`. + +### Schema: + +```js +{ + folder: string, + sourceDir: string, + solutionFile: string, + projects: [ + { + projectFile: string, + directDependency: bool, + projectName: string, + projectLang: string, + projectGuid: string, + cppHeaders: [], + cppPackageProviders: [], + csNamespaces: [], + csPackageProviders: [] + }, + ], + nugetPackages: [ + { + packageName: string, + packageVersion: string, + cppHeaders: [], + cppPackageProviders: [], + csNamespaces: [], + csPackageProviders: [], + }, + ], +} +``` + +### Top-Level Fields: + +The top-level object has the following fields: + +| Field | Type | Tag | Description | +|:------|:----:|:----:|:------------| +| folder | string | auto | Absolute path to the module root folder, determined by `react-native config`, ex: *'c:\path\to\app-name\node_modules\my-module'* | +| sourceDir | string | opt, req if projects defined | Relative path to the windows implementation under *folder*, ex: *'windows'* | +| solutionFile | string | opt | Relative path to the module's VS solution file under *sourceDir*, ex: *'MyModule.sln'* | +| projects | array | opt | Array of VS projects that must be added to the consuming app's solution file, so they are built | +| nugetPackages | array | opt | Array of nuget packages including native modules that must be added as a dependency to the consuming app. It can be empty, but by its nature it can't be calculated | + +### Project Object Fields: + +Objects in the `projects` array have the following fields: + +| Field | Type | Tag | Description | +|:------|:----:|:----:|:------------| +| projectFile | string | req | Relative path to the VS project file under *sourceDir*, ex: *'MyModule\MyModule.vcxproj'* for *'c:\path\to\app-name\node_modules\my-module\windows\MyModule\MyModule.vcxproj'* | +| directDependency | bool | req | Whether to add the project file as a dependency to the consuming app's project file. true for projects that provide native modules | +| projectName | string | auto | Name of the project, determined from *projectFile*, ex: *'MyModule'* | +| projectLang | string | auto | Language of the project, cpp or cs, determined from *projectFile* | +| projectGuid | string | auto | Project identifier, determined from *projectFile* | +| cppHeaders | array | opt | Array of cpp header include lines, ie: *'winrt/MyModule.h'*, to be transformed into `#include ` | +| cppPackageProviders | array | opt | Array of fully qualified cpp IReactPackageProviders, ie: *'MyModule::ReactPackageProvider'* | +| csNamespaces | array | opt | Array of cs namespaces, ie: *'MyModule'*, to be transformed into `using MyModule;` | +| csPackageProviders | array | opt | Array of fully qualified cs IReactPackageProviders, ie: *'MyModule.ReactPackageProvider'* | + +### Nuget Package Object Fields: + +Objects in the `nugetPackages` array have the following fields: + +| Field | Type | Tag | Description | +|:------|:----:|:----:|:------------| +| packageName | string | req | Name of the nuget package to install | +| packageVersion | string | req | Version of the nuget package to install | +| cppHeaders | array | req | Array of cpp header include lines, ie: *'winrt/NugetModule.h'*, to be transformed into `#include ` | +| cppPackageProviders | array | req | Array of fully qualified cpp IReactPackageProviders, ie: *'NugetModule::ReactPackageProvider'* | +| csNamespaces | array | req | Array of cs namespaces, ie: *'NugetModule'*, to be transformed into `using NugetModule;` | +| csPackageProviders | array | req | Array of fully qualified cs IReactPackageProviders, ie: *'NugetModule.ReactPackageProvider'* | + +### Example `react-native.config.js` for a *MyModule*: + +```js +module.exports = { + dependency: { + platforms: { + windows: { + sourceDir: 'windows', + solutionFile: 'MyModule.sln', + projects: [ + { + projectFile: 'MyModule\\MyModule.vcxproj', + directDependency: true, + } + ], + }, + }, + }, +}; +``` diff --git a/docs/native-modules-autolinking.md b/docs/native-modules-autolinking.md new file mode 100644 index 000000000..6aa2a4b73 --- /dev/null +++ b/docs/native-modules-autolinking.md @@ -0,0 +1,64 @@ +--- +id: native-modules-autolinking +title: Autolinking Native Modules +--- + +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: + +``` +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: + +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. + > 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 use the `autolink-windows` CLI command, ie: + +```cmd +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* | +| -h, --help | output usage information | + +### Skipping autolinking + +If you would like to skip the autolinking process during `run-windows` you can pass `--no-autolink` option: + +```cmd +npx react-native run-windows --no-autolink +``` diff --git a/website/.unbroken_exclusions b/website/.unbroken_exclusions index e3df07e82..80b3c6321 100644 --- a/website/.unbroken_exclusions +++ b/website/.unbroken_exclusions @@ -1,6 +1,51 @@ !node_modules !blog/2019- +URL not found https://mybuild.microsoft.com/sessions/b1306a79-b43b-43be-bd59-460b8db0c7a8 while parsing blog/2020-06-01-build2020recap.md (HTTP 404) +URL not found https://mybuild.microsoft.com/sessions/d10c502e-325d-4c77-9471-462b37744db1 while parsing blog/2020-06-01-build2020recap.md (HTTP 404) +URL not found https://mybuild.microsoft.com/sessions/53ccd339-7cc0-4e66-bdb9-3eee6b270658 while parsing blog/2020-06-01-build2020recap.md (HTTP 404) +URL not found https://mybuild.microsoft.com/sessions/cf5901a1-2cd2-4913-b4b7-f1af32db934a while parsing blog/2020-06-01-build2020recap.md (HTTP 404) + +File not found building-rnw.md while parsing versioned_docs/version-0.62/getting-started.md +File not found native-modules.md while parsing versioned_docs/version-0.62/getting-started.md +File not found rnw-dependencies.md while parsing versioned_docs/version-0.62/getting-started.md +File not found building-rnw.md while parsing versioned_docs/version-0.62/getting-started.md +File not found native-modules.md while parsing versioned_docs/version-0.62/getting-started.md +File not found rnw-dependencies.md while parsing versioned_docs/version-0.62/getting-started.md +File not found native-modules.md while parsing versioned_docs/version-0.62/IReactModuleBuilder-api-windows.md +File not found native-modules.md while parsing versioned_docs/version-0.62/IReactModuleBuilder-api-windows.md +File not found view-managers.md while parsing versioned_docs/version-0.62/IViewManager-api-windows.md +File not found view-managers.md while parsing versioned_docs/version-0.62/IViewManager-api-windows.md +File not found ikeyboardprops-api-windows.md while parsing versioned_docs/version-0.62/iviewwindowsprops-api-windows.md +File not found native-modules.md while parsing versioned_docs/version-0.62/native-modules-advanced.md +File not found native-modules.md while parsing versioned_docs/version-0.62/native-modules-advanced.md +File not found assets/native-module-dependencies.png while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found assets/native-modules-setup-new-cpp-project.png while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found assets/native-modules-setup-new-cs-project.png while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found assets/native-modules-setup-wrong-cpp-project.png while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found getting-started.md while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found native-modules.md while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found rnw-dependencies.md while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found view-managers.md while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found getting-started.md while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found native-modules-using.md while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found native-modules.md while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found project-structure.md while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found rnw-dependencies.md while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found view-managers.md while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found native-modules-setup.md while parsing versioned_docs/version-0.62/native-modules.md +File not found view-managers.md while parsing versioned_docs/version-0.62/native-modules.md +File not found native-modules-advanced.md while parsing versioned_docs/version-0.62/native-modules.md +File not found native-modules-setup.md while parsing versioned_docs/version-0.62/native-modules.md +File not found view-managers.md while parsing versioned_docs/version-0.62/native-modules.md +File not found win10-compat.md while parsing versioned_docs/version-0.62/rnw-dependencies.md +File not found win10-compat.md while parsing versioned_docs/version-0.62/rnw-dependencies.md +File not found getting-started.md while parsing versioned_docs/version-0.62/view-managers.md +File not found native-modules-setup.md while parsing versioned_docs/version-0.62/view-managers.md +File not found native-modules.md while parsing versioned_docs/version-0.62/view-managers.md +File not found getting-started.md while parsing versioned_docs/version-0.62/view-managers.md +File not found native-modules-setup.md while parsing versioned_docs/version-0.62/view-managers.md +File not found native-modules.md while parsing versioned_docs/version-0.62/view-managers.md File not found rnw-dependencies.md while parsing versioned_docs/version-0.61/building-rnw.md File not found building-rnw.md while parsing versioned_docs/version-0.61/getting-started.md File not found native-modules.md while parsing versioned_docs/version-0.61/getting-started.md @@ -25,7 +70,6 @@ File not found native-modules-advanced.md while parsing versioned_docs/version-0 File not found native-modules-setup.md while parsing versioned_docs/version-0.61/native-modules.md File not found view-managers.md while parsing versioned_docs/version-0.61/native-modules.md File not found flyout-component-windows.md while parsing versioned_docs/version-0.61/popup-component-windows.md -File not found e2e-test.md while parsing versioned_docs/version-0.61/rnw-dependencies.md File not found win10-compat.md while parsing versioned_docs/version-0.61/rnw-dependencies.md File not found getting-started.md while parsing versioned_docs/version-0.61/view-managers.md File not found native-modules-setup.md while parsing versioned_docs/version-0.61/view-managers.md @@ -37,7 +81,3 @@ File not found assets/technical-decision.png while parsing versioned_docs/versio File not found assets/wdio-internal-dependencies.png while parsing versioned_docs/version-0.60/e2e-test-more-about.md File not found assets/reveal-surface-animation.gif while parsing versioned_docs/version-0.60/windowsbrush-and-theme.md File not found assets/rnw-acrylic-surface.png while parsing versioned_docs/version-0.60/windowsbrush-and-theme.md -URL not found https://mybuild.microsoft.com/sessions/b1306a79-b43b-43be-bd59-460b8db0c7a8 while parsing blog/2020-06-01-build2020recap.md (HTTP 404) -URL not found https://mybuild.microsoft.com/sessions/d10c502e-325d-4c77-9471-462b37744db1 while parsing blog/2020-06-01-build2020recap.md (HTTP 404) -URL not found https://mybuild.microsoft.com/sessions/53ccd339-7cc0-4e66-bdb9-3eee6b270658 while parsing blog/2020-06-01-build2020recap.md (HTTP 404) -URL not found https://mybuild.microsoft.com/sessions/cf5901a1-2cd2-4913-b4b7-f1af32db934a while parsing blog/2020-06-01-build2020recap.md (HTTP 404) diff --git a/website/fix-unbroken.js b/website/fix-unbroken.js index 2d5e7f6a9..ed15cbb36 100644 --- a/website/fix-unbroken.js +++ b/website/fix-unbroken.js @@ -68,6 +68,13 @@ exclusions.push(normalizePath('!node_modules')); exclusions.push(normalizePath('!blog\\2019-')); exclusions.push(''); +// MyBuild Sessions +exclusions.push('URL not found https://mybuild.microsoft.com/sessions/b1306a79-b43b-43be-bd59-460b8db0c7a8 while parsing blog/2020-06-01-build2020recap.md (HTTP 404)'); +exclusions.push('URL not found https://mybuild.microsoft.com/sessions/d10c502e-325d-4c77-9471-462b37744db1 while parsing blog/2020-06-01-build2020recap.md (HTTP 404)'); +exclusions.push('URL not found https://mybuild.microsoft.com/sessions/53ccd339-7cc0-4e66-bdb9-3eee6b270658 while parsing blog/2020-06-01-build2020recap.md (HTTP 404)'); +exclusions.push('URL not found https://mybuild.microsoft.com/sessions/cf5901a1-2cd2-4913-b4b7-f1af32db934a while parsing blog/2020-06-01-build2020recap.md (HTTP 404)'); +exclusions.push(''); + // Redirected files exclusions redirectedFiles.forEach(redirectedFile => { exclusions.push(`File not found ${normalizePath(redirectedFile.target)} while parsing ${normalizePath(redirectedFile.source)}`); diff --git a/website/sidebars.json b/website/sidebars.json index c2ce6a713..b461cf08b 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -4,6 +4,7 @@ "getting-started", "rnw-dependencies", "parity-status", + "config", "windowsbrush-and-theme", "winui3", "releases" @@ -13,6 +14,7 @@ "view-managers", "native-modules-setup", "native-modules-using", + "native-modules-autolinking", "native-modules-marshalling-data", "native-modules-jsvalue", "native-modules-advanced"