Why and How to Fork the PSPDFKit for React Native Repository

PSPDFKit for React Native is an SDK for viewing, annotating, and editing PDFs. It offers developers the ability to quickly add PDF functionality to any React Native application. We provide our React Native SDK as a source-available repository that’s hosted on GitHub, and it bridges some of the most common APIs exposed by PSPDFKit’s native Android and iOS SDKs. This makes implementing common use cases in React Native easy.

However, sometimes there are custom use cases that aren’t so straightforward to implement, and they require you to fork and customize our React Native SDK’s repository.

In this blog post, we’ll focus on the process of forking the PSPDFKit for React Native SDK repository and cover how to use that custom fork. Additionally, we’ll talk about how to keep your forked repository up to date when our React Native SDK repository changes.

Why Fork the PSPDFKit for React Native Repository?

To implement custom use cases in React Native, you may have to drill down to the native layer and write Objective-C or Java code. There are a lot of design pattern, paradigm, and philosophy differences between iOS and Android development, and because of this, it’s difficult to find common abstractions that work identically for both platforms.

For instance, the view hierarchy in our Viewer component for iOS is quite different from the view hierarchy in Android. So, if you want to customize something related to the view hierarchy, it’s easier to do it in native code rather than bridging everything over to React Native.

Another scenario where you may need to go into the native layer is if your use case requires you to run some code early in your app’s lifecycle. In such a case, you should do it directly in the native part of your app. A use case for this could be customizing your app’s appearance (theming) on iOS. But there are limitations in when and how React Native instantiates third-party libraries. For example, we have access to PSPDFKit for React Native and its APIs only after the app has launched (application(_:didFinishLaunchingWithOptions:) on iOS). This makes it impossible for our React Native code to perform any tasks like theming immediately after the app launches.

The last and the most important reason you’d want to fork our repository is if your use case requires a feature that’s available in PSPDFKit for Android and iOS but not yet in PSPDFKit for React Native.

How to Fork the React Native Repository

The following steps outline how to fork the React Native repository.

• Navigate to the PSPDFKit for React Native repository.

• Fork the repository to your personal account or your organization’s account.

• Make the following changes to your forked repository:

  • In the package.json file, replace the url under repository with your own repository:

    "repository": {
          "type": "git",
    -     "url": "https://github.com/PSPDFKit/react-native.git"
    +     "url": "https://github.com/yourRepo/react-native.git"
       },

  • In the package.json file, replace homepage:

    -  "homepage": "https://github.com/PSPDFKit/react-native",
    +  "homepage": "https://github.com/yourRepo/react-native",

  • In the react-native-pspdfkit.podspec file, replace the s.source URL with your own repository:

    -  s.source = { :git => 'https://github.com/PSPDFKit/react-native' }
    +  s.source = { :git => 'https://github.com/yourRepo/react-native' }

• Your forked repository is now ready to be customized!

Making Customizations

The next step is to make additional changes and customize the code. For examples and tutorials on how to customize your repository, refer to our blog posts on extending React Native APIs:

• How to Bridge Native iOS Code to React Native — This blog post explains how to bridge native iOS code to add a custom annotation deletion button to the toolbar.

• How to Extend React Native APIs — We give examples of how to call native iOS code from React Native, listen to event callbacks, and customize the UI using native code.

• Advanced Techniques for React Native UI Components — This blog shares techniques for Android to call both simple methods such as saveCurrentDocument and methods with return values such as getAnnotations from React Native.

• How to Extend React Native APIs for Windows — In this post, we explain the process of extending the React Native APIs for Windows to accomplish tasks such as PDF manipulation, listening to event callbacks, and customizing the UI.

Using Your Custom React Native Repository

Now that you’ve customized code, you’ll want to know how to use it. If you followed our Getting Started guide for React Native, you’ll have come across the step where you add the PSPDFKit for React Native dependency using Yarn:

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

To use your custom repository, replace the GitHub URL in the line above with the URL of your own custom fork:

yarn add github:yourRepo/react-native

After adding this dependency, you must run yarn install once to install this dependency. And voilà! You’ll now be able to use any native customizations you may have made in your React Native app!

Keeping Your Custom Fork Updated

Even though you’re using your own custom fork of the React Native SDK, you might still want to fetch any newer changes from our repository. We’re constantly updating our hybrid SDKs by adding more APIs and documentation and fixing bugs. So, whenever there’s an update of our React Native SDK, we recommend pulling any changes to your custom fork as well. In addition to you getting the newest, most updated code, it also enables us to be faster on support by eliminating the need to roll back to previous versions when testing or replicating issues.

To keep your repository in sync with ours, perform the following steps:

• Before you can sync your fork with an upstream repository, you must configure a remote that points to the upstream repository in Git.

• Change the current working directory to your local project.

• Fetch the branches and their respective commits from the upstream repository using git fetch upstream.

• Check out your fork’s main / master branch with git checkout main.

• Merge the changes from upstream/master into your local main / master branch with git merge upstream/main.

• Optionally, push the changes from your local branch to your GitHub remote.

If you prefer, you can instead follow the steps to sync a fork from GitHub’s web UI, as opposed to the command line.

Conclusion

PSPDFKit for React Native is designed to be fully customizable so that you can add the functionality your project requires. This post covered the process of forking and maintaining the fork for a React Native library repository. We hope it’ll help you streamline the process of customization so that you can implement complex use cases in your app.

If you have any questions about PSPDFKit for React Native, please don’t hesitate to reach out to us. We’re happy to help.