Back-end developers love the safety provided by static type checking languages such as Java and C#. Frontend developers, in contrast, have long been stuck with the pros and cons of JavaScript, a dynamic programming language. Writing a JavaScript application for large codebases can be a major hassle due to difficulty testing and predicting behavior.

Enter TypeScript, Microsoft’s open-source solution to some of the drawbacks of dynamic languages. Since introduction in 2012, TypeScript steadily increased in popularity. Frontend developers may appreciate its improved legibility and optional static type checking -- to name just two features.

At PDFtron, we recognized TypeScript’s advantages as well -- so in this article, we go over how to create a PDF viewing app using PDF.js and TypeScript.

For those who may be interested, we’ll also cover how to use Typescript with two commercial PDF solutions: the open-source wrapper PDF.js Express and the powerful PDFTron WebViewer.

linkCreating the Codebase

The major components for this project include the static HTML file, served with the JavaScript file which is produced by the TypeScript compiler, as well as the PDF.js files and the TypeScript file.

We'll use the prebuilt PDF.js files to make things a little easier.

Let's start with making a new directory called pdfjs-typecript.

mkdir pdfjs-typescript
cd pdfjs-typescript

Within the directory, create a new file in the public folder called index.html. Next, add the following inside:

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>PDF.js Example</title>
  <script src="pdf.js"></script>
  <script> var exports = {}; </script>
  <script src="renderer.js"></script>
</head>
<body>
  <div>
    <span  class="outer">
    <div  class="grey-back">
      <div class="actions">
       <button id="prev" class="action_button">Previous</button>
       <button id="next" class="action_button">Next</button>
      </div>
      <div class="pg_num_display">
        <span>Page: <span id="page_num"></span> / <span id="page_count"></span></span>
      </div>
    </div>
    <div>
      <canvas id="pdf" class="grey-back"></canvas>
    </div>
    </span>
  </div>
</body>
</html>

Don't worry about the missing .js files the <script> tags refer to; we'll add them shortly. The class names have been assigned so you can apply styling later if you wish.

Download the latest stable PDF.js build from here. Then extract the zip file, and from within the build folder, copy the pdf.js and pdf.worker.js files into the pdfjs-typescript/ folder. We won't be making any changes to these files.

Now, it's time to take advantage of DefinitelyTyped a popular open-source repository of declaration files that provide type validation for various JavaScript libraries, including PDF.js!

We'll obtain the declaration file by running the following command:

npm install --save @types/pdfjs-dist

Navigate into the node_modules/@types/pdfjs-dist directory and add the following line at the top of the index.d.ts file:

export as namespace pdfjsLib

This will allow us to avoid the require method in the later-compiled .js file. Note that we don't have to add any actual references to this declaration file since it lives in node_modules/@types which makes it visible to other files in the project via the TypeScript compiler (more info about types here).

Next, we'll create a new file called renderer.ts. Notice that we have used the .ts extension used for TypeScript files; we will be using the TypeScript compiler to create the renderer.js file afterwards.

Inside renderer.ts, add the following code:

const scale = 1;
let canvas, ctx, prevButton, nextButton; 
var pdfDoc = null,
    pageNum = 1,
    pageRendering = false,
    pageNumPending = null;

/**
 * Get page info from document, resize canvas accordingly, and render page.
* @param num Page number.
*/
function renderPage(num: number) {
pageRendering = true;
// Using promise to fetch the page
pdfDoc.getPage(num).then(function(page) {
//   const canvas = document.getElementById('pdf') as HTMLCanvasElement;
//   const ctx = canvas.getContext('2d');
    var viewport = page.getViewport({ scale: scale, });
    canvas.height = viewport.height;
    canvas.width = viewport.width;
    // Render PDF page into canvas context
    var renderContext = {
    canvasContext: ctx,
    viewport: viewport,
    };
    var renderTask = page.render(renderContext);
    // Wait for rendering to finish
    renderTask.promise.then(function () {
    pageRendering = false;
    if (pageNumPending !== null) {
        // New page rendering is pending
        renderPage(pageNumPending);
        pageNumPending = null;
    }
    });
});
// Update page counters
document.getElementById('page_num').textContent = num.toString();
}

const loadingTask = pdfjsLib.getDocument("https://pdftron.s3.amazonaws.com/downloads/pl/Chart_.Vector.pdf");
loadingTask.promise.then(function(pdf){
  pdfDoc = pdf;
  document.getElementById('page_count').textContent = pdf.numPages.toString();
  canvas = document.getElementById("pdf") as HTMLCanvasElement;
  ctx = canvas.getContext("2d");
  prevButton = document.getElementById('prev').addEventListener('click', onPrevPage);
  nextButton = document.getElementById('next').addEventListener('click', onNextPage);
  renderPage(pageNum);
});

/**
 * If another page rendering in progress, waits until the rendering is
* finished. Otherwise, executes rendering immediately.
*/
function queueRenderPage(num) {
  if (pageRendering) {
    pageNumPending = num;
  } else {
    renderPage(num);
  }
}
/**
 * Displays previous page.
*/
function onPrevPage() {
  if (pageNum <= 1) {
    return;
  }
  pageNum--;
  queueRenderPage(pageNum);
}
/**
 * Displays next page.
*/
function onNextPage() {
  if (pageNum >= pdfDoc.numPages) {
    return;
  }
  pageNum++;
  queueRenderPage(pageNum);
}

Note: The code snippet above was adapted from the official mozilla/pdf.js github repository

We can now compile the renderer.ts file to produce the renderer.js file that the HTML page refers to:

tsc renderer.ts

linkAdding Styles (Optional)

Now that you’ve got a prototype application up and running, let's (optionally) add some styling. We'll create a file called index.css and add the following styles (based around class names in our HTML file):

And finally, we'll add a link to the style sheet inside the HTML file. Add the following line inside the <head> tag of index.html:

body {
    text-align: center
}

.grey-back {
    background-color: lightgrey;
}

.outer {
    display: inline-block;
    border: 2px solid darkgray;
}

.actions {
    display: inline-block;
    text-align: left;
}

.pg_num_display {
    display: inline-block;
    text-align: right;
}

button {
    -webkit-transition-duration: 0.4s;
    transition-duration: 0.4s;
}

button:hover {
    background-color: white; 
    color: black;
}

.action_button {
    background-color: grey;
    color: white;
}
<link rel="stylesheet" type="text/css" href="./index.css">

At this point, the project directory should look like this:

Directory structure

linkServing Your Application

The node package http-server is often used for preliminary testing of single-folder applications.

  1. Install the latest version of http-server using npm:

    npm install -g http-server

This will create a global installation which you can use to test other applications as well.

  1. Run http-server:

    http-server
  2. Open a browser and go to localhost:8080/index.html. The styled application should look like this:

    Style-pdfjs-app

That's it! You should now see your PDF displayed inside the PDF.js viewer.

linkAlternatives to PDF.js

PDF.js provides an easy way to add a PDF viewer to your app. However, you could run into some rendering inconsistencies or failures when working with some types of PDFs, while performance can be slow on mobile devices or older browsers. Learn more in our guide to evaluating PDF.js.

Additionally, implementing functionality beyond basic viewing such as annotations, signatures, or form fill may prove very challenging and time-intensive as there is currently very little API support with PDF.js.

If you seek to streamline implementation of additional features, you could consider PDF.js Express. Alternatively, if you need a more robust and reliable experience, including for example, editing capabilities, you can consider using the powerful PDFTron WebViewer, part of the PDFTron SDK.

linkImplementing with PDF.js Express

PDF.js Express wraps a modern react-based UI around the open source PDF.js rendering engine. It includes out-of-the-box features like annotations, form filling and e-signatures, and the viewer is commercially supported. It also comes with a large set of APIs for easy customization. Check out the demo to see it in action.

This section will walk you through adding a TypeScript declaration file to the PDF.js Express build.

You can download the package and explore the PDF.js Express documentation at https://pdfjs.express/.

To keep our codebases separate, let's create a new project directory called pdfjs-express-typescript. Once you've downloaded the PDF.js Express package, place the WebViewer folder from inside the .zip file into the pdfjs-express-typescript/ folder.

Next, we'll create a new file called index.html. PDF.js express simply needs a DOMElement to place an iframe containing the viewer, so we’ll put it in the body as follows:

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>PDF.js Express Example</title>
  <script src='./WebViewer/lib/webviewer.min.js'></script>
</head>
<body>
  <div id='viewer' style="text-align: center;"></div>
  <script src="index.js"></script>
</body>
</html>

Now let's make a new declaration file called express.d.ts. This will be where we add our custom TypeScript definitions. Add the following definitions to it. (You can add more definitions later if you wish.)

/**
* Creates a WebViewer instance and embeds it on the HTML page.
* @name WebViewer
* @param {WVOptions} options A set of options required for the contstructor to create an instance properly
* @param {string} [options.annotationUser=Guest] Name of the user for annotations
* @param {string} [options.config] URL path to a custom JavaScript for customizations
* @param {string} [options.css] URL path to a custom CSS file for customizations
* @param {Array.<string>} [options.disabledElements] List of data-elements to be disabled in UI
* @param {boolean} [options.enableAnnotations=true] Enable annotations feature
* @param {boolean} [options.enableAzureWorkaround=false] Enable workaround of the issue in Azure related to range requests
* @param {boolean} [options.enableFilePicker=false] Enable file picker feature
* @param {boolean} [options.enableMeasurement=false] Enable measurement tools
* @param {boolean} [options.enableRedaction=false] Enable redaction tool
* @param {string} [options.extension] Extension of the document to be loaded
* @param {boolean} [options.forceClientSideInit=false] If set to true then when loading a document using WebViewer Server the document will always switch to client only rendering allowing page manipulation and the full API to be used.
* @param {boolean} [options.fullAPI=false] Enable PDFNet.js library functions
* @param {string} [options.initialDoc] URL path to a document to load on startup
* @param {boolean} [options.isAdminUser=false] Set user permission to admin
* @param {boolean} [options.isReadOnly=false] Set user permission to read-only
* @param {string} options.licenseKey License key for viewing documents
* @param {boolean} [options.mobileRedirect=true] Whether the mobile viewer should redirect to a new window or not
* @param {boolean} [options.path='WebViewer/lib']  Path to the WebViewer lib folder
* @param {string} [options.preloadWorker] Type of workers to be preloaded. Accepts `pdf`|`office`|`all`.
* @param {string} [options.ui=default] Type of UI to be used
* @param {object} [options.workerTransportPromise]
* @param {function} [options.workerTransportPromise.pdf] Promise that resolves to a PDF worker
* @param {function} [options.workerTransportPromise.office]  Promise that resolves to an office worker
* @param {HTMLElement} viewerElement A DOMElement that is needed to root the iframe of the WebViewer onto the  HTML page
* @return {Promise<WebViewerInstance>} returns a promise that resolves to a webviewer instance.
* @example // 5.1 and after
WebViewer({
  licenseKey: 'YOUR_LICENSE_KEY'
}, document.getElementById('viewer'))
  .then(function(instance) {
    var docViewer = instance.docViewer;
    var annotManager = instance.annotManager;
    // call methods from instance, docViewer and annotManager as needed

    // you can also access major namespaces from the instancs as follows:
    // var Tools = instance.Tools;
    // var Annotations = instance.Annotations;
  });
*/
declare function WebViewer(options: WVOptions, viewerElement: HTMLElement): Promise<WebViewerInstance>

/**
* @interface WVOptions
* An object from which you can choose options for the webviewer
* instance to be produced using the constructor. 
* See our guides and API for WebViewer at https://www.pdftron.com/documentation/web
* @example WebViewer({
* path: 'path/to/WebViewer/lib',  // This contains a default value of `WebViewer/lib`
* initialDoc: 'path/to/local/file OR URL', // (see more options in guides)
* enableAnnotations: true, // Allows you to toggle the use of annotations on the document
* // and many other options to explore
* } document.getElementById('viewer')).then(function(instance) {...})
*/
declare interface WVOptions {
  initialDoc: string;
  annotationUser?: string;
  config?: string;
  css?: string;
  disabledElements?: Array<any>;
  documentId?: string;
  enableAnnotations?: boolean;
  enableAzureWorkaround?: boolean;
  enableFilePicker?: boolean;
  enableOfflineMode?: boolean;
  enableRedaction?: boolean;
  enableMeasurement?: boolean;
  extension?: any;
  forceClientSideInit?: boolean;
  fullAPI?: boolean;
  isAdminUser?: boolean;
  isReadOnly?: boolean;
  l?: string;
  licenseKey?: string;
  mobileRedirect?: boolean;
  pdfBackend?: string;
  path?: string;
  preloadPDFWorker?: boolean;
  useDownloader?: boolean;
  ui?: string;
  workerTransportPromise?: {
    pdf?: (...params: Array<any>) => any;
    office?: (...params: Array<any>) => any;
  };
}

/**
* Creates a WebViewer instance and embeds it on the HTML page.
* @name WebViewer
* @class Main class.
* @param {object} options
* @param {HTMLElement} viewerElement DOM element that will contain WebViewer
*/
declare class WebViewerInstance {
  constructor(options: {
    initialDoc: string;
  }, viewerElement: HTMLElement);
}

Note: This declaration file defines the constructor method which returns a promise to an instance of the main class. We can later add further definitions depending on the use case. In the future, there may also be a complete declaration file for PDF.js Express.

Now we need to create the actual TypeScript file that will be compiled into JavaScript.. We also need to be able to refer to this declaration file since this declaration file is no longer in the visible domain. We can do this by adding the <reference path/> tag at the top of our program. Just create a new file called index.ts and add the following at the top:

/// <reference path='./express.d.ts'/>

Anything typed in this file will now be able to use the definitions we previously added. We can then create an instance of the PDF.js Express web viewer in this file using the following:

WebViewer({
  path: './WebViewer/lib',
  initialDoc: 'https://pdftron.s3.amazonaws.com/downloads/pl/Chart_.Vector.pdf' // path/to/local OR URL
}, document.getElementById('viewer')).then(function(instance) {
  // Call all the APIs (which you can also define in the express.d.ts file)
});

The final step is to compile the index.ts file and serve the directory:

tsc index.ts
http-server

This is what the directory will look like afterwards:

express-directory

When you serve, you'll get to use a bunch of functionality with the added bonus of being wrapped in a slick UI:

express-viewer

If you are having issues when you serve the PDF.js Express project, clear your browser's cache to get rid of the pdf.js project files.

You can now view, annotate, sign, fill PDF forms, and more!

linkImplementing in WebViewer

WebViewer is a pure client-side JavaScript library which provides a complete solution to view, annotate and edit documents. It is compatible with TypeScript and has a complete type declaration file -- over 30k lines of definitions! It uses an in-house rendering engine and offers a vast range of functionality far beyond the scope of PDF.js. You can try out the demo here.

The WebViewer declaration file is greatly beneficial to anyone wanting to quickly understand the SDK and what the plethora of classes, methods and enums bring to the table. You can download webviewer.d.ts here

Once again, let's create a new project directory called webviewer-typescript. Once you've downloaded the WebViewer package, place the WebViewer folder from inside the WebViewer.zip file into the public folder.

Just like PDF.js Express, WebViewer only requires a DOMElement to work its magic, which makes it compatible with all JavaScript frameworks. Our index.html file only needs the following:

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>PDF.js Express Example</title>
  <script src='./WebViewer/lib/webviewer.min.js'></script>
</head>
<body style="text-align: center">
  <div id='viewer' style="height: 700px"></div>
  <script src="index.js"></script>
</body>
</html>

You'll notice that the contents of this HTML file are identical to the one we made for PDF.js Express, so switching between these products is extremely easy.

Download the declaration file and place it inside the webviewer-typescript/ folder. Then, create the index.ts file and add a reference to the declaration file:

/// <reference path='./webviewer.d.ts'/>

Now we can access all of the WebViewer API. Try typing in the following code to see the constructor options brought to you by TypeScript.

WebViewer({
  path: './WebViewer/lib',
  initialDoc: 'https://pdftron.s3.amazonaws.com/downloads/pl/demo-annotated.pdf' // path/to/local OR URL
}, document.getElementById('viewer')).then(function(instance) {
  // Call all the APIs and enjoy the power of static type checking and auto-fill
  // some namespaces from the declaration file:
  var Annotations = instance.Annotations
  var Actions = instance.Actions
  var Tools = instance.Tools

  // the setTheme method can also be used for custom colors with an object input
  instance.setTheme('dark');
});

We can now compile and serve the application:

tsc index.ts
http-server

You can see what the directory will look like after compilation beneath. Just like with the HTML file, the directory structure is identical to that of PDF.js Express!

webviewer-directory

Since we set the theme to dark mode, we'll get the cool-looking dark UI:

webviewer-example

Again, if you are having issues when you serve the WebViewer project, remember to clear your browser's cache and try once more.

Note: The current iteration of the declaration file is in its beta and feedback to improve the definitions is highly appreciated.

linkConclusion

It's easy to see how TypeScript enhances the developer experience. You can learn more about TypeScript and how it works here.

However, you may find adding functionality beyond basic viewing and rendering to be time-intensive.

Towards that end, we provide developers a couple more options:

Those who want to streamline implementation of basic annotations, form fill, and signatures can consider the the open-source wrapper PDF.js Express. Alternatively, if the UX needs to be a competitive differentiator, you could use a more robust commercial solution: the PDFTron WebViewer, including hundreds of unique features such as page manipulation, redaction, editing, file comparison, file conversion, and more.

The full source code for each of the implementations is available:

If you have any questions about implementing your project, please feel to contact us and we will be happy to help!