|
| 1 | +# Native Module Setup |
| 2 | + |
| 3 | +>**This documentation and the underlying platform code is a work in progress. You can see the current state of working code here: [packages/microsoft-reactnative-sampleapps](../../packages/microsoft-reactnative-sampleapps)** |
| 4 | +
|
| 5 | +This guide will help set you up with the Visual Studio infrastructure to author your own stand-alone native module for React Native Windows. In this document we'll be creating the scaffolding for a `MyLibrary` native module. |
| 6 | + |
| 7 | +## Development Environment |
| 8 | + |
| 9 | +Install the tools specified in the *System Requirements* and *Dependencies* sections of [Getting Started Guide for React Native Windows (vnext)](./GettingStarted.md). |
| 10 | + |
| 11 | +If you're planning on writing in C++, you'll also want to download and install the [C++/WinRT Visual Studio Extension](https://marketplace.visualstudio.com/items?itemName=CppWinRTTeam.cppwinrt101804264). |
| 12 | + |
| 13 | +## New Project (optional) |
| 14 | + |
| 15 | +If you already have an existing native module project for iOS/Android, you can skip straight to [Manually Adding Windows Support](#manually-adding-windows-support). |
| 16 | + |
| 17 | +Otherwise, if you're creating a new project from scratch, the quickest way is to follow the official React Native instructions at https://facebook.github.io/react-native/docs/native-modules-setup. |
| 18 | + |
| 19 | +```cmd |
| 20 | +yarn global add create-react-native-module |
| 21 | +create-react-native-module MyLibrary |
| 22 | +``` |
| 23 | + |
| 24 | +Now you'll have a new native module project under `react-native-my-library`. Be sure to look at the command output for further steps you'll want to do before publishing the project. |
| 25 | + |
| 26 | +## Manually Adding Windows Support |
| 27 | + |
| 28 | +>**The plan is to automate this process as part of a CLI new library project template, see issues [3201](https://github.com/microsoft/react-native-windows/issues/3201) and [3203](https://github.com/microsoft/react-native-windows/issues/3203). However we are also documenting the manual process here for developers who are unable to use the CLI.** |
| 29 | +
|
| 30 | +### Updating your package.json |
| 31 | + |
| 32 | +In the directory for your native module project, you first need to update to `react-native` 0.60 and get the latest `react-native-windows`: |
| 33 | + |
| 34 | +```cmd |
| 35 | + |
| 36 | +yarn add react-native-windows@vnext --peer |
| 37 | +``` |
| 38 | + |
| 39 | +Next you'll want to create a `windows` subdirectory to hold the windows code: |
| 40 | + |
| 41 | +```cmd |
| 42 | +mkdir windows |
| 43 | +``` |
| 44 | + |
| 45 | +Now it's time to switch into Visual Studio and create a new project. |
| 46 | + |
| 47 | +### Creating the Visual Studio Project / Solution |
| 48 | + |
| 49 | +Open Visual Studio and select `Create a new project`. You're going to create a new `Windows Runtime Component` project, which produce a library that is compatible with Windows UWP apps. |
| 50 | + |
| 51 | +If you're planning on writing your native module in C#, you'll want to choose `Windows Runtime Component (Universal Windows)`. |
| 52 | + |
| 53 | +If you're planning on writing your native module in C++, you'll want to choose `Windows Runtime Component (C++/WinRT)`. Note, if you don't see that project type, make sure you installed the *C++/WinRT Visual Studio Extension* linked to above under [Development Environment](#development-environment). |
| 54 | + |
| 55 | +1. Set the `Project Name` to `MyLibrary`. |
| 56 | +1. Set the `Location` to the path of the `windows` subdirectory you created earlier. |
| 57 | +1. Set the `Solution Name` to `MyLibrary`. |
| 58 | +1. Click `Create`. |
| 59 | + |
| 60 | +Next you'll be prompted to select the versions of Windows you'll support. This should match the values for React Native Windows: |
| 61 | + |
| 62 | +1. Set the `Target version` to `Windows 10, version 1903 (10.0; Build 18362)`. |
| 63 | +1. Set the `Minimum version` to `Windows 10 Creators Update (10.0; Build 15063)`. |
| 64 | + |
| 65 | +You'll now have a new `MyLibrary` solution file at `windows\MyLibrary.sln` and a `MyLibrary` project under `windows\MyLibrary\`. Now it's time to add React Native Windows into the solution. |
| 66 | + |
| 67 | +### Adding React Native Windows to the Visual Studio Solution |
| 68 | + |
| 69 | +We're going to add several React Native Windows projects to your solution. So to avoid confusing them with your own code, we're first going to create a solution folder called `ReactNative`: |
| 70 | + |
| 71 | +1. Open the Solution Explorer sidebar. |
| 72 | +1. Right-click on `Solution 'MyLibrary'` at the top. |
| 73 | +1. Select `Add` > `New Solution Folder`. |
| 74 | +1. Name the folder `ReactNative`. |
| 75 | + |
| 76 | +Now we're going to add all of the following React Native Windows projects to that `ReactNative` folder. All of these projects are located under the `node_modules\react-native-windows` directory in the root of your `react-native-my-library` project directory. |
| 77 | + |
| 78 | +>*For more details about what these projects do, see [Project Structure](ProjectStructure.md).* |
| 79 | +
|
| 80 | +| VS Project | Project File | |
| 81 | +|:-----------|:-------------| |
| 82 | +| Chakra | `Chakra\Chakra.vcxitems` | |
| 83 | +| Common | `Common\Common.vcxproj` | |
| 84 | +| Folly | `Folly\Folly.vcxproj` | |
| 85 | +| JSI.Shared | `JSI\Shared\JSI.Shared.vcxitems` | |
| 86 | +| JSI.Universal | `JSI\Universal\JSI.Universal.vcxproj` | |
| 87 | +| Microsoft.ReactNative | `Microsoft.ReactNative\Microsoft.ReactNative.vcxproj` | |
| 88 | +| Microsoft.ReactNative.Cxx | `Microsoft.ReactNative.Cxx\Microsoft.ReactNative.Cxx.vcxitems` | |
| 89 | +| Microsoft.ReactNative.SharedManaged | `Microsoft.ReactNative.SharedManaged\Microsoft.ReactNative.SharedManaged.shproj` | |
| 90 | +| ReactCommon | `ReactCommon\ReactCommon.vcxproj` | |
| 91 | +| ReactUWP | `ReactUWP\ReactUWP.vcxproj` | |
| 92 | +| ReactWindowsCore | `ReactWindowsCore\ReactWindowsCore.vcxproj` | |
| 93 | + |
| 94 | +For each project, you'll do the following: |
| 95 | + |
| 96 | +1. Open the Solution Explorer sidebar. |
| 97 | +1. Right-click on the `ReactNative` folder. |
| 98 | +1. Select `Add` > `Existing Project...`. |
| 99 | +1. Select the project file and click `Open`. |
| 100 | + |
| 101 | +You now have all of the React Native Windows projects to your solution. Next we're going to reference them in our `MyLibrary` project. |
| 102 | + |
| 103 | +### Referencing React Native Windows in your Project |
| 104 | + |
| 105 | +The only project reference you **must** add is `Micrsoft.ReactNative`. To add the reference: |
| 106 | + |
| 107 | +1. Open the Solution Explorer sidebar. |
| 108 | +1. Right-click on your `MyLibrary` project. |
| 109 | +1. Select `Add` > `Reference`. |
| 110 | +1. Select `Projects` on the left-hand side. |
| 111 | +1. Check the box next to `Microsoft.ReactNative`. |
| 112 | +1. Click `OK`. |
| 113 | + |
| 114 | +After you've added the reference, you need to make sure it doesn't copy itself into your build (otherwise it'll cause build conflicts down the line when you're trying on consume your library): |
| 115 | + |
| 116 | +1. Open the Solution Explorer sidebar. |
| 117 | +1. Under your `MyLibrary` project, expand the `References`. |
| 118 | +1. Right-click on `Microsoft.ReactNative`. |
| 119 | +1. Select `Properties`. |
| 120 | +1. Under `Build`, Change `Copy Local` to `False`. |
| 121 | + |
| 122 | +Now, you're technically ready to go, but in order to improve the developer experience, it's also **highly recommended** to also add a reference to the appropriate helper shared project. These projects contain the attributes (C#) and macros (C++) as described in the [Native Modules](./NativeModules.md) and [View Managers](./ViewManagers.md). |
| 123 | + |
| 124 | +If you're writing in C#, you'll want to add `Microsoft.ReactNative.SharedManaged`: |
| 125 | + |
| 126 | +1. Open the Solution Explorer sidebar. |
| 127 | +1. Right-click on your `MyLibrary` project. |
| 128 | +1. Select `Add` > `Reference`. |
| 129 | +1. Select `Shared Projects` on the left-hand side. |
| 130 | +1. Check the box next to `Microsoft.ReactNative.SharedManaged`. |
| 131 | +1. Click `OK`. |
| 132 | + |
| 133 | +If you're writing in C++, you'll want to add `Microsoft.ReactNative.Cxx`: |
| 134 | + |
| 135 | +1. Open the Solution Explorer sidebar. |
| 136 | +1. Right-click on your `MyLibrary` project. |
| 137 | +1. Select `Add` > `Reference`. |
| 138 | +1. Select `Shared Projects` on the left-hand side. |
| 139 | +1. Check the box next to `Microsoft.ReactNative.Cxx`. |
| 140 | +1. Click `OK`. |
| 141 | + |
| 142 | +### Testing your Build |
| 143 | + |
| 144 | +To make sure that everything is working, you'll want to try building `MyLibrary`. First you'll want to make sure you've chosen a supported platform: |
| 145 | + |
| 146 | +1. At the top, change the `Solution Platform` to `x86`, `x64` or `ARM`. |
| 147 | +1. In the `Build` menu, select `Build Solution`. |
0 commit comments