Using Modern JavaScript (ES6 / ECMAScript 2015+) with DocRaptor

Introduction

Up until around 2015, the vast majority of web browsers and JavaScript engines supported nearly all of the same features. For features that weren’t universally supported –such as those specific to legacy browsers like Internet Explorer 6 – it was common for web developers to address those differences individually. Doing so came with the territory.

This was known as having compatibility with the ECMAScript or es5 standards, which our underlying JavaScript engine, PhantomJS has.

Recently, however, a newer version of JavaScript – known as ECMAScript 2015 or es6 – has been rising in popularity. es6 introduces many new enhancements and features to JavaScript, including keywords such as class, const, let, Promise, and Set.

(You can look at a full list of es6 features here and here.) DocRaptor supports two JavaScript engines, PhantomJS is the primary engine we recommend. Our PhantomJS implementation has been specifically designed to provide support for popular JavaScript tools and libraries, such as Typekit and Highcharts.

While PhantomJS announced plans to implement es6, new changes to the project were recently put on hold.

PhantomJS continues to provide the flexibility and power required by the vast majority of our customers.

That having been said, we’ve seen an increase in customer support queries concerning es6 compatibility, so here’s a few strategies for handling es6 in your DocRaptor web pages:

Write es5 compatible code

By far the easiest way to ensure compatibility with DocRaptor and PhantomJS is to write your code using es5 from the start.

This means removing any syntax sugar and keywords specific to es6, such as class, let, const, Promise, and Set. Depending on their usage, those keywords can cause PhantomJS to silently fail, which could cause hours of frustration to the unsuspecting DocRaptor developer. (We’d like to avoid that.)

Certain es6 features also can’t be sufficiently shim’d or sham’d back to older browsers, which means they may not work even after applying shims, shams or polyfills.

While DocRaptor maintains compatibility with web browsers as best as it can, we still recommend testing your PDFs with us frequently during development to achieve best results, so writing code specifically for your PDFs is still preferred, which is why this tip is #1.

(Remember: you can use the test API parameter to generate as many test documents as you’d like, so don't be shy to do so until your documents look just right!)

Use shims and shams

Perhaps the next easiest way to get documents compatible with es5 is to use shims and shams. This means taking es6 keywords and features and defining substitutes for incompatible JavaScript engines and web browsers.

While developers should be careful about over-relying on shims and shams in production web applications, they might be useful to get documents generating until a more permanent solution is implemented.

The easiest way to get started with shims and shams is to simply include this code block from the es5 shims repository*:

<script src="https://cdnjs.cloudflare.com/ajax/libs/es5-shim/4.5.7/es5-shim.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/es5-shim/4.5.7/es5-sham.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/json3/3.3.2/json3.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/es6-shim/0.34.2/es6-shim.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/es6-shim/0.34.2/es6-sham.min.js"></script>
<script src="https://wzrd.in/standalone/es7-shim@latest"></script>

An alternative one-stop-shop polyfill:

<script src="https://cdn.polyfill.io/v2/polyfill.min.js?features=all"></script>

You’ll want to include this in your head element at the very top of your web page, before any other includes, since this will modify functionality of the JavaScript engine itself.

(I know a number of libraries recommend being included “first”, but shims, shams and polyfills really, actually should be the first things to run, and placing the includes in your head element ensures they run prior to any other content.)

* Since PhantomJS is es5-compatible, the es5 shims and shams shouldn’t be required.

Use es5 compatible versions of libraries

Another strategy for achieving es5 compatibility is to avoid using libraries that rely on es6. While many JavaScript libraries and frameworks maintain es5 compatibility, not all of them do.

You can find historical versions of many JavaScript libraries from their GitHub or NPM pages, or from CDNJS.

es5 to es6 upgrades are most-likely to be reflected in major version numbers (ex: 9.x to 10.x, as opposed to 9.x to 9.y). If you’re already using a CDN reference, sometimes changing the major version # in your code is sufficient to find historical versions of the same library, but I would still check the official version listings to make sure.

For PDFs you expect to have longevity, you may also want to download local copies of your preferred libraries to your own server, just in case the CDN eventually becomes unavailable. (While CDNs are often preferred to local copies due to their high reliability, sometimes online repositories can be deleted over extended periods of time!)

Use a tool like Babel to turn es6+ into es5-compatible code

For our hardcore web and PDF engineers, this next tip is a surefire way to achieve es5 compatibility, but it involves a bit more work.

Rather than dealing with es5 or es6 compatibility in the browser, using a tool like Babel on your dev machine or build server – prior to sending your code to DocRaptor or publishing to the web – can transform your code from es6+ to es5, ensuring 100% compatibility with es5 and PhantomJS.

The linked usage guide is extensive, and this option won’t be for everyone.

However, development teams who are already using Babel or webpack in their pipelines may find it an easy addition to target es5 in their configurations. (There’s a good chance if you use either of these tools that you are already doing this.)

Summary

At DocRaptor, making PDF generation a pleasant experience is our #1 priority. It’s why we continue to be the easiest, most seamless PDF API on the planet.

Until all es6 compatibility concerns can be fully addressed, however, we hope these tips and workarounds can serve to alleviate any concerns you may have.

That being said, if you have any additional tips & tricks you'd like to share, or have any other questions or concerns, feel free to contact us!

(You can also use the chat icon on the bottom-right of your web page. Don’t be afraid to say hi!)