How PDF.js Works
In this article, we walk you through how PDF.js works to render PDFs, what technologies it uses, and implications for projects using PDF.js.
Pick a framework to get started
26 Nov 2019
In this article, we outline some key considerations when deploying a PDF.js viewer into your application. The three top considerations are:
When Mozilla introduced PDF.js in 2011, it was designed to be Firefox’s PDF Viewer -- allowing users to render PDFs in their web browsers. Out-of-the-box PDF.js comes with three layers:
Initially PDF.js was not intended for commercial use but contributions from the open-source community have extended its functionality. Some simple PDF.js customizations you can quickly deploy include:
In a recent survey, 57 unique organizations stated the most common feature they wanted to add to PDF.js were
Of these respondents, 71.4% tried to add some of these PDF.js features themselves but ultimately found it too difficult or time-intensive. If your requirements include extending a PDF.js viewer with this type of functionality, an important first step is to spend time understanding all the costs involved in adding these features.
If you are considering adding these features to your PDF.js Viewer, there are 3 key costs to investigate:
When customizing PDF.js there is a risk that documentation for the feature you want to add is non-existent, stale or incomplete. If no documentation exists, development occurs in uncharted territory, making it difficult to predict amount of developer resources needed and the turnaround time. A good first step is to read through closed PDF.js Github issues & open PDF.js Github issues to identify if the features you are interested in adding have been successfully deployed or if documentation is incomplete.
Depending on the functionality you hope to add, you might need to spend time getting acquainted with the PDF specification (over 1000 pages not including extensions and supplements). For example, if you plan to add annotations to a viewer, you will need to learn how to handle basic rendering instructions, including how to convert PDF annotation coordinates to canvas coordinates.
No API exists for adding features to the PDF.js Viewer UI. If you are planning on adding features like eSignatures or annotations to your viewer’s UI, you will need to account for the time it takes to familiarize yourself with the PDF.js code base.
Another important consideration is determining how often you rely on support during development. With an open-source solution, there is some uncertainty about response time when opening a new issue. Overall, PDF.js has many active contributors who typically respond within a day or two, particularly for simple issues. For more complex issues (e.g., adding annotation, signature, form filling, etc.) responses can take longer. And if your request falls outside the scope of the project, you are largely on your own.
|Form filling||Open Issue for 3 years|
|Direct annotation (Add, edit, and remove)||Out of scope|
|Signatures||Open for 7 years|
|Toggleable visual layers (via OCGs)||Open 8 years|
|Pinch zoom for mobile||Open 6 years|
|Night mode||Open 7 years|
PDF.js has over 6,000 forks and commits typically occur several times a week. Depending on the extent of your customization, these changes might have an impact on your project. Some of the customers we’ve worked with have encountered situations where their customizations break after PDF.js is updated. The best way to deal with this is to assign a developer to periodically monitor and test your PDF.js viewer customizations.
Can someone please fix this issue in pdf js. This issue has ruined our experience in an application that is in production. If we don't get a fix we will have to abandon pdf.js and move to a different product. I don't want to do that as I find pdf.js really simple in its UI and dependencies.
When assessing whether to undertake a custom pdf.js project, the first thing to look at is the overall cost. Once you’ve defined how much time will need to be invested by developer resources, this assessment ends up being a straightforward calculation:
Custom PDF.js cost assessment:
If the cost of using internal resources is lower than a commercial solution, then it would seem obvious to develop in-house. But there is one more cost to consider - the cost of using developer resources to work on something that is not your core differentiator - a cost known as opportunity cost.
“Opportunity cost is the loss of potential gain from other alternatives when one alternative is chosen.”
Opportunity cost is most commonly used when deciding how best to allocate resources to maximize gains. A simple example would be deciding how to allocate developer resources in your product roadmaps:
Option #1: develop feature 1 to increase new users by 2% Option #2: develop feature 2 to increase new users by 1% Option #3: develop custom PDF.js viewer results in $5,000 cost savings
Your approach to opportunity cost will likely be driven by your business strategy & philosophy. Some strategies focus resources on their key differentiators and outline the types of work they will not do. Other strategies emphasize developing software internally to avoid reliance on third-party software providers. Dropbox is an example of the latter strategy - they developed their own custom PDF.js viewer but eventually abandoned the project for another open-source solution:
“Integrating PDF.js with Dropbox was quite difficult, if not downright hacky. PDF.js was designed to be Firefox’s integrated PDF viewer, rather than a component of another product." ~Senior Developer, Dropbox”
Opportunity cost of long-term maintenance is another important consideration. If an unexpected bug is discovered or a major update occurs, a developer will need to be pulled off their current project to fix the issue. These unplanned delays can have a direct impact on product release schedules. It can also demotivate and defocus developers who need to jump from their current priority back to supporting the PDF.js project.
If you require a simple viewer without features like annotations, signatures or form filling, a PDF.js viewer will be a good fit out-of-the-box. If you plan on adding custom features to your viewer, however, it's important to understand all the different costs you will encounter. Having an understanding of these costs will help you determine if it makes sense to build your viewer internally or whether to get started with a commercial pdf.js viewer like PDF.js Express.