react-native-unimodules

This library contains the core unimodule infrastructure and a collection of unimodules and interfaces that are commonly depended on by other unimodules. You only need to install react-native-unimodules once and then you will be able to use most of the packages from the Expo SDK, like expo-camera, expo-media-library and many more, in any React Native project.

The easiest way to use the library is to initialize a "bare" project with expo-cli (npm i -g expo-cli) using expo init --template bare-minimum or expo init --template expo-template-bare-typescript if you prefer TypeScript. If you have an existing project you'd like to install it into, please read the following instructions.

📦 Installation

This project requires that you use CocoaPods on iOS, to set it up see this gist, or relevant parts of the this guide. React Native >= 0.60 ships with Cocoapods support by default, so this should be easy if you're already on that version.

npm install react-native-unimodules

Now you need to configure the library for iOS and/or Android.

🍎 Configure iOS

• Open ios/Podfile in your editor and make it look like this one on react-native <= 0.59 or like this one on react-native >= 0.60.
• Run pod install again
• Update your AppDelegate.h and AppDelegate.m according to to look like these.
  • If you use react-native-navigation, you will need to use its bridgeManagerDelegate option like in this gist.

Add permission usage description keys to Info.plist

In order to submit your app to the App Store, you will need to eventually add permission usage keys to your Info.plist. Even if you don't use the APIs described, you need to include the keys because code related to asking the permission will be bundled regardless, and Apple's static analysis tools will detect it and reject your app if the key isn't present. Including the key without using it has no impact to your users - iOS app permissions are requested at runtime and not listed in the app store listing as they are on Android. Test the permission prompts and customize the message as needed.

See a list of keys to add to Info.plist

<key>NSCalendarsUsageDescription</key>
<string>Allow $(PRODUCT_NAME) to access your calendar</string>
<key>NSCameraUsageDescription</key>
<string>Allow $(PRODUCT_NAME) to use the camera</string>
<key>NSContactsUsageDescription</key>
<string>Allow $(PRODUCT_NAME) to access your contacts</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Allow $(PRODUCT_NAME) to use your location</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>Allow $(PRODUCT_NAME) to use your location</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Allow $(PRODUCT_NAME) to use your location</string>
<key>NSMicrophoneUsageDescription</key>
<string>Allow $(PRODUCT_NAME) to access your microphone</string>
<key>NSMotionUsageDescription</key>
<string>Allow $(PRODUCT_NAME) to access your device's accelerometer</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>Give $(PRODUCT_NAME) permission to save photos</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Give $(PRODUCT_NAME) permission to access your photos</string>
<key>NSRemindersUsageDescription</key>
<string>Allow $(PRODUCT_NAME) to access your reminders</string>

Advanced configuration

Need to customize node_modules path?

If you need to customize the path to node_modules, for example because you are using yarn workspaces, then you can pass in a param for this: use_unimodules!(modules_paths: ['./path/to/node_modules'])

Need to exclude some unimodules that are being automatically linked?

If you need to exclude some of the unimodules that you are not using but they got installed by your other dependencies (like expo), then you can pass in exclude param for this. For example, if you want to exclude expo-face-detector, you may want to use this: use_unimodules!(exclude: ['expo-face-detector'])

🤖 Configure Android

• At the top of android/settings.gradle, add apply from: '../node_modules/react-native-unimodules/gradle.groovy' and then on the next line add includeUnimodulesProjects().
• Add apply from: '../../node_modules/react-native-unimodules/gradle.groovy' anywhere in android/app/build.gradle and then addUnimodulesDependencies() inside dependencies {} block.
• We recommend using Java 1.8, you can set this in android/app/build.gradle like this.
• Update minSdkVersion in android/build.gradle to 21.
• Update your MainApplication.java to according to this diff for react-native <= 0.59 and this diff for react-native >= 0.60.

Optional: Add permissions to AndroidManifest.xml

Add permissions you would like to use in your app to android/app/src/main/AndroidManifest.xml:

See a list of some Android permissions

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.READ_CONTACTS" />
<uses-permission android:name="android.permission.READ_CALENDAR" />
<uses-permission android:name="android.permission.WRITE_CALENDAR" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_SETTINGS" />

Advanced configuration

Need to customize node_modules path?

If you need to customize the path to node_modules, for example because you are using yarn workspaces, then you can pass in a param modulesPaths for both of these functions: includeUnimodulesProjects([modulesPaths: ['./path/to/node_modules']]), addUnimodulesDependencies([modulesPaths: ['./path/to/node_modules']])

Need to exclude some unimodules that are being automatically linked?

If you need to exclude some of the unimodules that you are not using but they got installed by your other dependencies (like expo), then you can pass in exclude param for this. For example, if you want to exclude expo-face-detector, you may want to use this: addUnimodulesDependencies([exclude: ['expo-face-detector']])

Need to customize configuration of unimodule dependencies?

You can also customize the configuration of the unimodules dependencies (the default is implementation, if you're using Gradle older than 3.0, you will need to set configuration: "compile" in addUnimodulesDependencies, like: addUnimodulesDependencies([configuration: "compile"]))

API

It's possible that you will not have to use any of the code provided by this package directly, it may be used only by other Unimodules that you install.

But it's likely that you will want to use something like FileSystem or Permissions, and to do that you can import the following modules like so:

import {
  Asset,
  Constants,
  FileSystem,
  Permissions,
} from 'react-native-unimodules';

You can import them directly from the specific Unimodule package if you like, but your linter may complain about importing a transitive dependency.

import * as Permissions from 'expo-permissions';