PSPDFKit is a JavaScript PDF library for viewing, annotating, and editing PDFs directly in the browser. Use it to add PDF capabilities to any web app.
This guide assumes you’ve already configured PSPDFKit for your specific framework. If you haven’t, select the guide for your framework and configure PSPDFKit. Then return to this guide.
Nutrient's PWA must be served by a web server over HTTPS, so make sure your server is configured to serve pages in HTTPS. In development, however, Nutrient doesn't need HTTPS since browsers treat localhost as a secure origin.
Opening a PDF
To read the PDF, you’ll need a helper to read the selected file from disk using the FileReader API:
function registerFilePicker(element, callback) { function handler(event) { if (event.target.files.length == 0) { event.target.value = null; return; } var pdfFile = event.target.files[0]; if (pdfFile.type !== "application/pdf") { alert("Invalid file type, please load a PDF."); return; }
var reader = new FileReader(); reader.addEventListener("load", function(event) { var pdf = event.target.result; callback(pdf, pdfFile); }); reader.addEventListener("error", function(error) { alert(error.message); }); reader.readAsArrayBuffer(pdfFile); event.target.value = null; }
element.addEventListener("change", handler);
return function() { element.removeEventListener("change", handler); };}callback is a function that gets the pdf in the ArrayBuffer format so that you can load it directly with PSPDFKit. It also gets the selected File object.
Once you have this helper, you can add the code to initialize PSPDFKit for Web:
var pspdfkitInstance = null;var filePicker = document.querySelector('input[type="file"]');
registerFilePicker(filePicker, function(pdf, fileInfo) { if (pspdfkitInstance) { PSPDFKit.unload(pspdfkitInstance); }
PSPDFKit.load({ document: pdf, container: ".PSPDFKit-container", // See https://nutrient.io/api/web/PSPDFKit.Configuration.html#enableServiceWorkerSupport enableServiceWorkerSupport: true }).then(function(instance) { pspdfkitInstance = instance; });});Nutrient's advanced PWA example allows you to load PDF files from a remote server, and it uses IndexedDB to cache them locally for offline use. It also uses the History API to easily load files using URL.
Adding caching and offline capabilities with service workers
One of the most important features of PWAs is the ability to load fast and to work on slow network conditions, or even offline. To achieve this, you can use a service worker to cache the application shell and, when available, use the network only to fetch necessary data.
The service worker is a script you register in the application shell. It runs in the background, separate from a webpage. It can intercept and handle network requests, allowing you to cache responses programmatically.
In case you’re not familiar with service workers, we highly recommend you read this excellent introductory blog post.
Create the
serviceworker.jsfile with the following contents:./serviceWorker.js console.log("Hello from the Service Worker");Then, register it in your application shell:
./src/index.html <!DOCTYPE html><html><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no"/><title>PSPDFKit PWA</title><script>if ('serviceWorker' in navigator) {window.addEventListener('load', function () {navigator.serviceWorker.register('./serviceWorker.js')})}</script>This uses feature detection to determine whether service workers are supported and to register your
serviceWorker.jswhen the feature is available.You can now start your application and try it out in a web browser. In the Application tab of Chrome Dev Tools, you’ll see that your service worker has been registered and is active.
For local development, it’s a good idea to check the Update on reload option so that the service worker is updated every time the page reloads. You can clear the service worker storage any time from this panel using the Clear storage view.
Final touches
Now that your app has offline capabilities, you only need to add a web app manifest to make the application recognizable by the web browser and to describe how the app should behave when installed on users’ devices.
The web app manifest is a file whose name is
manifest.json. It contains metadata like the name of the app, the paths to icons and their sizes, the start URL, and the theme color. Now you’ll create a basic one for your PWA:Terminal window touch ./src/manifest.json{"name": "PSPDFKit for Web PWA","short_name": "PSPDFKit","icons": [{"src": "images/icons/icon-192x192.png","sizes": "192x192","type": "image/png"},{"src": "images/icons/icon-512x512.png","sizes": "512x512","type": "image/png"}],"start_url": "./index.html","display": "standalone","background_color": "#0089AA","theme_color": "#0089AA"}Finally, you need to register the manifest in the app pages — in your case,
index.html:<link rel="manifest" href="./manifest.json">You can verify the manifest in the Application tab of Chrome Dev Tools:
The web app manifest also makes it possible to display an App Install Banner or an Add to Home Screen dialog. You can follow the guidelines from Google to learn how to create and display one.
A note about progressive enhancement
By definition, PWAs are progressive, meaning they’re inclusive and they rely heavily on progressive enhancement. When building a PWA, it’s good to always keep this in mind and provide a basic experience for every user of the application.
Richer features should be built on top of an always-working barebones implementation. We highly recommend using feature detection to provide progressive enhancement so that applications won’t break in older browsers that don’t support a specific feature.
A Note about the Service Worker API
The Service Worker API is low level, flexible, and powerful. Because of this, it usually requires some boilerplate code to do common tasks like activate the service worker, intercept requests and cache responses, clear the cache, and precache files.
To simplify those tasks, Google developed Workbox, an open source library that abstracts away all the complexity and makes building PWAs easy. Before deploying to production, we recommend using Workbox to manage your service workers.
Workbox can help with doing more than precaching, and it allows you to configure how each resource should be cached and how routes should be handled.
Complex applications will likely need to use the network to fetch data before they can render content in the app shell. In those cases, it’s important to choose the correct caching strategy for your data.
Refer to the Workbox website to learn more about how to handle advanced use cases.
Limitations
Disk Quota
Web browsers define quotas either per origin (Chrome and Opera) or per API (e.g. IndexedDB, service workers). When storing files via web APIs, it’s a good idea to keep this in mind and ideally monitor the disk quota status to avoid failures. Apps can check how much quota they’re using with the Quota Management API.
Precached PSPDFKit Assets
In this guide, you saw how to precache all the PSPDFKit for Web assets, including the JavaScript fallback pspdfkit.asm.js. However, when the target browser supports WebAssembly, it’d be better to exclude this file from the precache manifest and vice versa: When the target browser doesn’t support WebAssembly, you shouldn’t precache the WASM module pspdfkit.wasm. For production applications, we recommend generating separate manifests and service workers and serving them conditionally.