Microservices that convert web pages to PDF

Web page PDF rendering done right. Microservice for rendering receipts, invoices, or any content. Packaged to an easy API.

Features:

• Rendered with Headless Chrome, using Puppeteer. The PDFs should match to the ones generated with a desktop Chrome.
• Sensible defaults but everything is configurable
• Single-page app (SPA) support. Waits until all network requests are finished before rendering. A feature which even most of the paid services don’t have.
• Easy deployment to Heroku. We love Lambda but.. Deploy to Heroku button
• Renders lazy loaded elements (scrollPage option)
• Supports optional x-api-key authentication. (API_TOKENS env var)

The Usage is as simple as url-to-pdf-api.herokuapp.com/api/render?… . There’s also a POST /api/render if you prefer to send options in the body.

Why?

This microservice is useful when you need to automatically produce PDF files for whatever reason. The files could be receipts, weekly reports, invoices, or any content.

PDFs can be generated in many ways, but one of them is to convert HTML+CSS content to a PDF. This API does just that.

Shortcuts:

• Examples
• API
• I want to run this myself

How it works

Good to know

• By default, page’s @media print CSS rules are ignored. We set Chrome to emulate @media screen to make the default PDFs look more like actual sites. To get results closer to desktop Chrome, add &emulateScreenMedia=false query parameter. See more at Puppeteer API docs.

• Chrome is launched with --no-sandbox --disable-setuid-sandbox flags to fix usage in Heroku. See this issue.

• Heavy pages may cause Chrome to crash if the server doesn’t have enough RAM

Examples

Note: the demo Heroku app runs on a free dyno which sleep after idle. A request to sleeping dyno may take even 30 seconds.

Use the default @media print instead of @media screen.

Url-to-pdf-api.herokuapp.com/api/render?…

API

To understand the API options, it’s useful to know how Puppeteer is internally used by this API. The render code is really simple, check it out. Render flow:

GET /api/render

All options are passed as query parameters. Parameter names match Puppeteer options.

curl -o google.pdf https://url-to-pdf-api.herokuapp.com/api/render?url=http://google.comCopy the code

POST /api/render

All options are passed in a JSON body object. Parameter names match Puppeteer options.

{
  // Url to render
  url: "https://google.com".// If we should emulate @media screen instead of print
  emulateScreenMedia: true.// If true, page is scrolled to the end before rendering
  // Note: this makes rendering a bit slower
  scrollPage: false.// Passed to Puppeteer page.waitFor()
  waitFor: null.// Passed to Puppeteer page.setViewport()
  viewport: { . },

  // Passed to Puppeteer page.goto() as the second argument after url
  goto: { . },

  // Passed to Puppeteer page.pdf()
  pdf: { .}}Copy the code

curl -o google.pdf -XPOST -d'{"url": "http://google.com"}' -H"content-type: application/json" https://url-to-pdf-api.herokuapp.com/api/renderCopy the code

Development

To get this thing running, you have two options: run it in Heroku, or locally.

The code requires Node 8+ (async, await).

1. Heroku deployment

2. Local development

First, clone the repository and cd into it.

• cp .env.sample .env

• Fill in the blanks in .env

• source .env or bash .env

  Or use autoenv.

• npm install

• npm start Start express server locally

• Server runs at http://localhost:9000 or what $PORT env defines

Techstack

• Node 8+ (async, await), written in ES7
• Express.js app with a nice internal architecture, based on these conventions.
• Hapi-style Joi validation with express-validation
• Heroku + Puppeteer buildpack
• Puppeteer to control Chrome