Web page PDF rendering done right. Self-hosted service for rendering receipts, invoices, or any content.
JavaScript HTML Shell
Switch branches/tags
Nothing to show
Latest commit 195ee75 Nov 21, 2017
kimmobrunfeldt committed Nov 21, 2017 Merge pull request #46 from nicky9door/attachment-option
Option to receive rendering as an attachment download



Build Status

URL to PDF Microservice

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


WARNING: Don't serve this API publicly to the internet unless you are aware of the risks. It allows API users to run any JavaScript code inside a Chrome session on the server. It's fairly easy to expose the contents of files on the server. You have been warned!

⭐️ Features:

  • Converts any URL or HTML content to a PDF file
  • 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)

Usage is as simple as https://url-to-pdf-api.herokuapp.com/api/render?url=http://google.com. 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:

How it works

Local setup is identical except Express API is running on your machine and requests are direct connections to it.

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.


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.


Use scrollPage=true which tries to reveal all lazy loaded elements. Not perfect but better than without.


Render only the first page.


Render A5-sized PDF in landscape.


Add 2cm margins to the PDF.


Wait for extra 1000ms before render.


Wait for an element macthing the selector input appears.


Render HTML sent in JSON body

curl -o html.pdf -XPOST -d'{"html": "<body>test</body>"}' -H"content-type: application/json" https://url-to-pdf-api.herokuapp.com/api/render

Render HTML sent as text body

curl -o html.pdf -XPOST -d@page.html -H"content-type: text/html" https://url-to-pdf-api.herokuapp.com/api/render


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:

  1. page.setViewport(options) where options matches viewport.*.

  2. Possibly page.emulateMedia('screen') if emulateScreenMedia=true is set.

  3. Render url or html.

    If url is defined, page.goto(url, options) is called and options match goto.*. Otherwise page.goto(`data:text/html,${html}`, options) is called where html is taken from request body. This workaround was found from Puppeteer issue.

  4. Possibly page.waitFor(numOrStr) if e.g. waitFor=1000 is set.

  5. Possibly Scroll the whole page to the end before rendering if e.g. scrollPage=true is set.

    Useful if you want to render a page which lazy loads elements.

  6. page.pdf(options) where options matches pdf.*.

GET /api/render

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

These options are exactly the same as its POST counterpart, but options are expressed with the dot notation. E.g. ?pdf.scale=2 instead of { pdf: { scale: 2 }}.

The only required parameter is url.

Parameter Type Default Description
url string - URL to render as PDF. (required)
emulateScreenMedia boolean true Emulates @media screen when rendering the PDF.
ignoreHttpsErrors boolean false Ignores possible HTTPS errors when navigating to a page.
scrollPage boolean false Scroll page down before rendering to trigger lazy loading elements.
waitFor number or string - Number in ms to wait before render or selector element to wait before render.
viewport.width number 1600 Viewport width.
viewport.height number 1200 Viewport height.
viewport.deviceScaleFactor number 1 Device scale factor (could be thought of as dpr).
viewport.isMobile boolean false Whether the meta viewport tag is taken into account.
viewport.hasTouch boolean false Specifies if viewport supports touch events.
viewport.isLandscape boolean false Specifies if viewport is in landscape mode.
cookies[0][name] string - Cookie name (required)
cookies[0][value] string - Cookie value (required)
cookies[0][url] string - Cookie url
cookies[0][domain] string - Cookie domain
cookies[0][path] string - Cookie path
cookies[0][expires] number - Cookie expiry in unix time
cookies[0][httpOnly] boolean - Cookie httpOnly
cookies[0][secure] boolean - Cookie secure
cookies[0][sameSite] string - Strict or Lax
goto.timeout number 30000 Maximum navigation time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout.
goto.waitUntil string networkidle When to consider navigation succeeded. Options: load, networkidle. load = consider navigation to be finished when the load event is fired. networkidle = consider navigation to be finished when the network activity stays "idle" for at least goto.networkIdleTimeout ms.
goto.networkIdleInflight number 2 Maximum amount of inflight requests which are considered "idle". Takes effect only with