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
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:
(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
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.)
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!)