How to Use PSPDFKit for React Native with Expo

This article was first published in February 2023 and was updated in February 2024.

Expo is a React Native platform that significantly simplifies the process of developing, building, and testing React Native apps.

But there’s one major downside with Expo, which is that it’s optimized to be used purely with JavaScript out of the box. Therefore, additional steps are needed for a developer to use any package that depends on native code. In fact, the native code isn’t even included in the project from the initial setup. To be able to run on the respective platform, the Expo Go app is used to provide the necessary platform base.

PSPDFKit for React Native is implemented on top of the existing native PSPDFKit Android and iOS SDKs. This means it won’t work in a project that runs in the Expo Go app.

In this blog post, you’ll learn how to add native module support to an Expo project by setting up a development build using the Expo Application Services (EAS) CLI to be able to use the PSPDFKit React Native package.

Prerequisites

To get started, set up your environment by installing the following tools if you don’t have them installed already:

• Android Studio

• Xcode (for macOS only)

• Expo CLI

• EAS CLI

Creating an Expo Project

You’ll start by creating a normal Expo project that can run in Expo Go. If you’re new to Expo, consider familiarizing yourself with the official Expo documentation.

Use the command below to create a new project:

npx create-expo-app pspdpfkit-expo

In this example, the project is named pspdfkit-expo, but you can change it to one of your choice. Test that your app is correctly set up by running npx expo start to launch the application.

Development Build

A development build allows you to run a React Native app outside the Expo Go client. It generates the respective platform modules with all the native code required for the app to run independently.

EAS configurations are stored in the eas.json file. Run the command below in your project’s root folder to generate and configure the file:

eas build:configure

You’ll be presented with a list of platforms to choose from. Select the option that best suits your app’s platforms. Then press Enter.

If you selected All, you’ll now have the eas.json file in your project. It looks like this:

{
	"cli": {
		"version": ">= 5.4.0"
	},
	"build": {
		"development": {
			"developmentClient": true,
			"distribution": "internal"
		},
		"preview": {
			"distribution": "internal"
		},
		"production": {}
	},
	"submit": {
		"production": {}
	}
}

Now the development build has been set up in your Expo project, and you can run the app outside Expo Go. To verify that the setup runs correctly, launch your app locally on an Android emulator or iOS simulator that doesn’t have the Expo Go client installed:

npx expo run:android

npx expo run:ios

When launching the app for the first time, you’ll need to confirm the application ID in the command-line prompt by pressing Enter on Windows or Command on macOS. Wait for the installation to complete, and you’ll see the app launched on the emulator/simulator. For more information on running your Expo app, see the Expo documentation.

Now that your project is set with native modules, you’ll add the PSPDFKit for React Native package.

Adding PSPDFKit for React Native

Install PSPDFKit for React Native from the official public GitHub repository:

npm install github:PSPDFKit/react-native

Alternatively, you can use yarn:

yarn add react-native-pspdfkit@github:PSPDFKit/react-native

A few more platform-specific setups are needed for the PSPDFKit native modules on Android and iOS.

Android

For Android, open android/build.gradle and add the following lines:

...
allprojects {
	repositories {
	mavenLocal()
+ 	maven { url 'https://my.nutrient.io/maven/' }
	}
}
...

Set the compileSDKVersion to 34 and the minSdkVersion to 21.

iOS

For iOS, open the Podfile in your iOS module and set the target SDK to iOS 15:

platform :ios, podfile_properties['ios.deploymentTarget'] || '15.0'

Next, open your project’s workspace in Xcode and make sure the deployment target is set to 15.0 or higher.

Additionally, change View controller-based status bar appearance to YES in your project’s Info.plist:

For a detailed setup, including information on setting the license, please refer to the getting started guides for PSPDFKit for React Native.

Opening a PDF

Now, you’ll open a PDF. To prepare the PDF, add a test PDF file to your Android’s android/app/src/main/assets folder. This folder usually doesn’t exist, so if that’s the case, you’ll need to create it first.

On iOS, add the downloaded PDF to your application bundle by dragging it into your project.

Next, to load the PDF, replace the entire contents in App.js with the following code snippet:

import React, { Component } from 'react';
import { Platform } from 'react-native';
import PSPDFKitView from 'react-native-pspdfkit';
import { NativeModules } from 'react-native';

const PSPDFKit = NativeModules.PSPDFKit;
PSPDFKit.setLicenseKey(null);
const DOCUMENT =
	Platform.OS === 'ios'
		? 'pspdfkit-react-native-quickstart-guide.pdf'
		: 'file:///android_asset/pspdfkit-react-native-quickstart-guide.pdf';

export default class PSPDFKitDemo extends Component {
	var pdfRef: React.RefObject<PSPDFKitView> = React.createRef();
	render() {
		return (
			<PSPDFKitView
				document={DOCUMENT}
				configuration={{
					showThumbnailBar: 'scrollable',
					pageTransition: 'scrollContinuous',
					scrollDirection: 'vertical',
				}}
				ref={pdfRef}
				fragmentTag="PDF1"
				style={{ flex: 1 }}
			/>
		);
	}
}

Now you can run your app using npx expo run:android or npx expo run:ios, and the PDF will be loaded from the path you provided.

PSPDFKit won’t work when you run the project using expo start because the Expo Go app will be used and the PSPDFKit package native modules won’t be accessible.

Conclusion

This post showed how to integrate the PSPDFKit for React Native library into an Expo project using a development build. For detailed documentation of PSPDFKit for React Native, check out the official PSPDFKit for React Native guides.