Best practices for PDF.js Express

Preload the Web Viewer

If your website doesn't need to display the viewer immediately you can improve performance by preloading PDF.js Express Web Viewer so that it's immediately ready when you want to display a document. To do this you can load PDF.js Express without a document and hide the viewer. When it's time to display a document with PDF.js Express you can simply unhide the element and call loadDocument.

The reason this is worthwhile is that when PDF.js Express Web Viewer is instantiated it needs to load a number of JavaScript and CSS files and initialize the viewer UI. Depending on the network connection this can take a non-trivial amount of time which happens in the background when preloading.

Load documents with loadDocument

If you want to load multiple documents in your app you'll want to reuse PDF.js Express. This is better than removing the old iframe and creating a new instance of PDF.js Express because some browsers have trouble with this and may leak memory.

To reuse PDF.js Express just keep a reference to your PDF.js Express Web Viewer instance and call loadDocument with the new document URL. The old document will be removed from the viewer (automatically cleaning up its resources) and the new document will be loaded in.

WebViewer({
  ...
}, viewerElement)
  .then((instance) => {
    loadDocumentButton.on('click', () => {
      instance.loadDocument('mysite.com/myDocument.pdf', { documentId: 'id2' });
    });

    loadAnotherDocumentButton.on('click', () => {
      instance.loadDocument('mysite.com/myOtherDocument.pdf', { documentId: 'id2' });
    });
  });

WebViewer({
  ...
}, viewerElement)
  .then((instance) => {
    loadDocumentButton.on('click', () => {
      instance.UI.loadDocument('mysite.com/myDocument.pdf', { documentId: 'id2' });
    });

    loadAnotherDocumentButton.on('click', () => {
      instance.UI.loadDocument('mysite.com/myOtherDocument.pdf', { documentId: 'id2' });
    });
  });

Linearize PDF files

When viewing PDFs directly PDF.js Express is able to start rendering pages earlier when a PDF is linearized. Linearized PDF files are also known as "Fast Web View" which is often indicated in the document properties dialog of your favorite desktop PDF reader.

Support range requests

Range requests allow the browser to request specific bytes from a URL. For PDF.js Express to efficiently download and start rendering documents quickly it's important that the server hosting the document file (for example PDF) supports these requests.

When serving files statically from a server this generally works without any configuration. However if you're serving the files in some other way you may need to use a library to handle the range requests for you.

The range request specification isn't very complicated so it's also possible for you to implement the handling yourself.

Keep original files

If you are doing file conversions of any type then you should always keep track of the original source file. For example, if you allow your customers to upload various file types (Office, images, text) and you convert them all to PDF, then you should still retain the original file, and maintain in your database links between the original and converted file. This ensures maximum flexibility and maintenance.

Store annotations

PDF.js Express provides example implementations of annotation handlers for a few different languages which store all annotations as a single XFDF file on your server. This is one way to implement annotation handling, however if you have multiple users accessing the same document then timing issues can occur with one user overwriting the annotations of another.

One way to handle this to store the XFDF data for each annotation separately, for example as rows in a database. Then when PDF.js Express requests the annotation data for a document you can run a query to get all the annotations with that document id, append the data together and send it back to PDF.js Express.

This is similar to the approach that the realtime collaboration guide takes although that sample goes further and updates the data in real time. The important part to take away from it is the use of exportAnnotCommand and importAnnotCommand

PDF.js Express also offers a REST API that allows you to merge annotations into the underlying document or open and display pre-existing annotations when you import a new document into your viewer.