View Source Read Me

CircleCI Module Version Hex Docs Total Download License Last Updated

ChromicPDF is a HTML-to-PDF renderer for Elixir, based on headless Chrome.

features

Features

  • Node-free: In contrast to many other packages, it does not use puppeteer, and hence does not require Node.js. It communicates directly with Chrome's DevTools API over pipes, offering the same performance as puppeteer, if not better.
  • Header/Footer: Using the DevTools API allows to apply the full set of options of the printToPDF function. Most notably, it supports header and footer HTML templates.
  • PDF/A: It can convert printed files to PDF/A using Ghostscript. Converted files pass the verapdf validator.

requirements

Requirements

  • Chromium or Chrome
  • Ghostscript (optional, for PDF/A support and concatenation of multiple sources)

ChromicPDF is tested in the following configurations:

ElixirErlang/OTPDistributionChromiumGhostscript
1.15.726.2Alpine 3.18119.0.6045.15910.02.0
1.14.525.3.1Alpine 3.17112.0.5615.16510.01.1
1.14.025.1Alpine 3.16102.0.5005.1829.56.1
1.14.025.1Debian Buster90.0.4430.212-19.27
1.11.422.3.4.26Debian Buster90.0.4430.212-19.27

installation

Installation

ChromicPDF is a supervision tree (rather than an application). You will need to inject it into the supervision tree of your application. First, add ChromicPDF to your runtime dependencies:

def deps do
  [
    {:chromic_pdf, "~> 1.15"}
  ]
end

Next, start ChromicPDF as part of your application:

# lib/my_app/application.ex
def MyApp.Application do
  def start(_type, _args) do
    children = [
      # other apps...
      ChromicPDF
    ]

    Supervisor.start_link(children, strategy: :one_for_one, name: MyApp.Supervisor)
  end
end

usage

Usage

main-api

Main API

Here's how you generate a PDF from an external URL and store it in the local filesystem.

# Prints a local HTML file to PDF.
ChromicPDF.print_to_pdf({:url, "https://example.net"}, output: "example.pdf")

The next example shows how to print a local HTML file to PDF/A, as well as the use of a callback function that receives the generated PDF as path to a temporary file.

ChromicPDF.print_to_pdfa({:url, "file:///example.html"}, output: fn pdf ->
  # Send pdf via mail, upload to S3, ...
end)

template-api

Template API

ChromicPDF.Template contains additional functionality for controlling page dimensions of your PDF.

[content: "<p>Hello Template</p>", size: :a4]
|> ChromicPDF.Template.source_and_options()
|> ChromicPDF.print_to_pdf()

multiple-sources

Multiple sources

Multiple sources can be automatically concatenated using Ghostscript.

ChromicPDF.print_to_pdf([{:html, "page 1"}, {:html, "page 2"}], output: "joined.pdf")

examples

Examples

  • There is an outdated example of how to integrate ChromicPDF in a Phoenix application, see examples/phoenix.

development

Development

This should get you started:

mix deps.get
mix test

For running the full suite of integration tests, please install and have in your $PATH:

  • verapdf
  • For pdfinfo and pdftotext, you need poppler-utils (most Linux distributions) or Xpdf (OSX)
  • For the odd ZUGFeRD test in zugferd_test.exs, you need to download ZUV and set the $ZUV_JAR environment variable.

acknowledgements

Acknowledgements

Copyright (c) 2019–2023 Bitcrowd GmbH

Licensed under the Apache License 2.0. See LICENSE file for details.