-
Notifications
You must be signed in to change notification settings - Fork 217
[0.63] Autolinking docs #145
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
8 commits
Select commit
Hold shift + click to select a range
147c8ca
Autolinking docs
jonthysell c073a31
Merge branch 'master' into autolink
jonthysell dfdf247
Added table for config fields
jonthysell 9893f91
readability improvements
jonthysell 2e18721
Apply suggestions from code review
jonthysell b0af46c
Merge branch 'master' into autolink
jonthysell d35b720
updating exclusions
jonthysell 8bb9349
fix unbroken
jonthysell File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or 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,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 <winrt/MyModule.h>` | | ||
| | 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 <winrt/NugetModule.h>` | | ||
| | 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, | ||
| } | ||
| ], | ||
| }, | ||
| }, | ||
| }, | ||
| }; | ||
| ``` |
This file contains hidden or 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,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 | ||
| ``` | ||
This file contains hidden or 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 hidden or 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 hidden or 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
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Where do these files get generated, relative to the solution source directory?
Ideally they go into the Generated Files folder