Edit

Native Platform: Using Native Libraries

This guide covers how to consume Native Modules (and/or Components) from a native library in a React Native for Windows app. For a higher-level overview of developing native, see Native Platform: Overview before reading this guide.

Note: The instructions below are generalized and should work with most native libraries, however specific libraries may have their own instructions and/or additional installation steps.

High-Level Overview

In order to use a native library in a React Native for Windows app, you'll need to:

1. Add the native library package as a Node.js dependency to the app
2. Use React Native for Windows' Native Module Autolinking to connect the library's Windows project to the app's Windows project
3. Call the native library's API surface from within the app's JavaScript code

Step by Step Guide

0. Setup

You'll need a React Native library project with Windows support initialized and implemented.

Note: The rest of this guide assumes you've at least followed the Native Platform: Native Modules guide to create and implement a new library project named testlib, and you're going to consume it via the provided app in its example folder.

1. Add the native library package as a Node.js dependency to the app

The first thing you'll need to do is add the native library's Node.js package as a dependency of your React Native app if it isn't already:

yarn add testlib

Note: While this is the standard way of adding the library package as a dependency of your app (especially if you publish the library to, and are consuming it from, a NPM feed) this is not how the provided example app consumes the library. The example app instead uses a custom entry in the dependencies object of its react-native.config.js configuration.

2. Use React Native for Windows' Native Module Autolinking

Now, before we can successfully consume the native library in our React Native for Windows app we need to run React Native for Windows' autolinking, i.e. the autolink-windows command, at least once, to properly connect the library's native Windows projects to our app's native Windows project:

yarn react-native autolink-windows

Note: For our example app, you can either run the given command from within the example folder, or run yarn example react-native autolink-windows directly from the library's root folder.

The command will (re-)generate several native files under the app's windows folder, (for the example app, under example\windows\testLibExample), including:

AutolinkedNativeModules.g.targets

AutolinkedNativeModules.g.cpp

AutolinkedNativeModules.g.props

AutolinkedNativeModules.g.h

<?xml version="1.0" encoding="utf-8"?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <!-- AutolinkedNativeModules.g.targets contents generated by "npx @react-native-community/cli autolink-windows" -->
  <ItemGroup>
    <!-- Projects from testlib -->
    <ProjectReference Include="$(ProjectDir)..\..\..\windows\testlib\testlib.vcxproj">
      <Project>{4AA0750A-2B4A-4DE1-BD39-B65A83AADE6B}</Project>
    </ProjectReference>
  </ItemGroup>
</Project>

// AutolinkedNativeModules.g.cpp contents generated by "npx @react-native-community/cli autolink-windows"
// clang-format off
#include "pch.h"
#include "AutolinkedNativeModules.g.h"

// Includes from testlib
#include <winrt/testlib.h>

namespace winrt::Microsoft::ReactNative
{

void RegisterAutolinkedNativeModulePackages(winrt::Windows::Foundation::Collections::IVector<winrt::Microsoft::ReactNative::IReactPackageProvider> const& packageProviders)
{ 
    // IReactPackageProviders from testlib
    packageProviders.Append(winrt::testlib::ReactPackageProvider());
}

}

<?xml version="1.0" encoding="utf-8"?>
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <!-- AutolinkedNativeModules.g.props contents generated by "npx @react-native-community/cli autolink-windows" -->
  <PropertyGroup>
  </PropertyGroup>
</Project>

// AutolinkedNativeModules.g.h contents generated by "npx @react-native-community/cli autolink-windows"
// clang-format off
#pragma once

namespace winrt::Microsoft::ReactNative
{

void RegisterAutolinkedNativeModulePackages(winrt::Windows::Foundation::Collections::IVector<winrt::Microsoft::ReactNative::IReactPackageProvider> const& packageProviders);

}

Note: The generated files include the necessary setup to connect all of the native libraries to the React Native for Windows app.

The AutolinkedNativeModules.g.targets (and AutolinkedNativeModules.g.props) files contain the build configuration such that the native Windows app project depends on each native Windows library project.

The AutolinkedNativeModules.g.cpp (and AutolinkedNativeModules.g.h) files define a function which returns the list containing each library's IReactPackageProvider (which in turn contains each library's Native Modules and/or Components), so that these libraries can be added to React Native's list of registered packages at runtime.

Note: By default, the usual run-windows command will also automatically run autolinking before building a React Native for Windows app.

3. Call the native library's API surface

With the native library properly connected to the React Native for Windows app, the app's JavaScript should now be able to call the library's JavaScript APIs at runtime and expect the native functionality to be available. That is, each time the library's JavaScript needs to access its Native Modules (and/or Components), they will already be ready and registered on the native side.

3.1 Use a Native Module's API

If your library implements and exports any APIs which use Native Modules, you can import and call them from your JavaScript.

For our example app, we can see the library's multiply function being imported and used in example\src\App.tsx:

import { Text, View, StyleSheet } from 'react-native';
import { multiply } from 'testlib';

const result = multiply(3, 7);

export default function App() {
  return (
    <View style={styles.container}>
      <Text>Result: {result}</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
});

3.2 Use a Native Component

If your library implements and exports any components which use Native Components, you can also import and use them from your JavaScript.

For our example app, if you followed the Native Platform: Native Components guide, we can see the library's CircleMask component being imported and used in this example\src\App.tsx:

import { Text, View, StyleSheet } from 'react-native';
import { multiply, CircleMask } from 'testlib';

const result = multiply(3, 7);

export default function App() {
  return (
    <View style={styles.container}>
      <CircleMask style={{ margin: 10 }}>
        <View
          style={{
            backgroundColor: '#006666',
            width: 100,
            height: 100,
            justifyContent: 'center',
            alignItems: 'center',
          }}
        >
          <Text>Result: {result}</Text>
        </View>
      </CircleMask>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
});

Note: The default example app provided is a New Architecture app and cannot be used to test Paper Native Components.

3.3 Verifying the functionality

To verify the functionality works end-to-end, you should be able to launch the provided example app with the run-windows command:

yarn react-native run-windows

Note: For our example app, you can either run the given command from within the example folder, or run yarn example react-native run-windows directly from the library's root folder.