Migrating from PDF.js Express to PDFTron

This guide will help you migrate an existing PDF.js Express project to work with the PDFTron SDK in 4 simple steps.

1. Install PDFTron via NPM

Run the following command in your Terminal or Command Line:

npm i @pdftron/webviewer

This will install the main JS entrypoint, as well as download some static assets required for WebViewer to run.

2. Copy static assets

Next, we must copy the static assets required for WebViewer to run. The files are located in node_modules/@pdftron/webviewer/public and must be moved into your current folder location of core, ui, and ui-legacy folders. The new PDFTron folders will replace these folders. Here is a guide to automate this process. As a reminder, if you are currently using an automated script to copy the files over, you need to update the script to copy the files from the PDFTron module rather than from the PDF.js Express module.

3. Remove PDF.js Express Modules

We will now want to remove the now not needed PDF.js Express modules and our dependency for it in the package.json file.

In package.json remove the line (your version number may differ):

 "@pdftron/pdfjs-express": "^8.0.0",

If you have installed the Express Utils package you will also want to remove this line as well:

"@pdftron/pdfjs-express-utils": "^X.X.X",

In the folder node_modules/@pdftron/ you can also delete the folders pdfjs-express and pdfjs-express-utils as they will be no longer needed.

or you can use the following command to remove packages that are not in your package.json dependencies:

npm prune

3. Change initiation

If you are importing PDF.js Express via:

import WebViewer from '@pdftron/pdfjs-express';

you will want to change it to:

import WebViewer from '@pdftron/webviewer'

Further, you should remove any of your code importing and using Express Utils such as the following:

import ExpressUtils from '@pdftron/pdfjs-express-utils'

const utils = new ExpressUtils({
  serverKey: 'your_server_key',
  clientKey: 'your_client_key'
})

When initiating the Webviewer do not forget to change your license key or the path if you placed your assets in a different folder then your old PDF.js Express assets.

WebViewer({
  path: 'UPDATE THIS PATH IF CHANGED ASSETS LOCATION',
  licenseKey: 'NEW LICENSE KEY HERE',
}, document.getElementById('viewer'))
  .then(instance => {

4. Updating merge and extraction code

One big difference between the PDFTron API and the PDF.js Express API is that the PDFTron Webviewer can merge annotations locally, no need for a REST API call!

To update your old merge code, you will need to change the following:

import ExpressUtils from '@pdftron/pdfjs-express-utils'

const utils = new ExpressUtils({
  serverKey: 'your_server_key',
  clientKey: 'your_client_key'
})

utils
  .setFile('https://yourwebsite.com/your_file.pdf')
  .setXFDF(xfdf_string);

const response = await utils.merge(); // merge XFDF
// const response = await utils.set(); // or set XFDF

const mergedFile = await response.getBlob();
await response.deleteFile(); // remove file from the server

to this:

const { documentViewer, annotationManager } = instance.Core;
const doc = documentViewer.getDocument();

// merges annotations to the document
const xfdf_string = await annotationManager.exportAnnotations();
doc.getFileData({ xfdf_string }).then(data => {
  
  const arr = new Uint8Array(data);
  // merged blob
  const blob = new Blob([ arr ], { type: 'application/pdf' });
})

For extracting merged annotations, PDFTron will automatically extract the annotations on file load, which means you can get the XFDF simply by changing this:

utils.setFile('https://yourwebsite.com/your_file.pdf'); // can be a URL (server or client)

const response = await utils.extract(); // extract XFDF
const { xfdf } = response;

to this:

const xfdf_string = await annotationManager.exportAnnotations();

You can read more about importing and exporting annotations with PDFTron here

Next steps