Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bitcrowd/chromic_pdf
Convenient HTML to PDF/A rendering library for Elixir based on Chrome & Ghostscript
https://github.com/bitcrowd/chromic_pdf
chrome-devtools chrome-headless invoice pdf pdf-converter pdf-generation
Last synced: 2 months ago
JSON representation
Convenient HTML to PDF/A rendering library for Elixir based on Chrome & Ghostscript
- Host: GitHub
- URL: https://github.com/bitcrowd/chromic_pdf
- Owner: bitcrowd
- License: apache-2.0
- Created: 2020-02-04T13:17:37.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2024-08-09T15:55:29.000Z (5 months ago)
- Last Synced: 2024-08-09T17:27:47.616Z (5 months ago)
- Topics: chrome-devtools, chrome-headless, invoice, pdf, pdf-converter, pdf-generation
- Language: Elixir
- Homepage:
- Size: 4.18 MB
- Stars: 399
- Watchers: 17
- Forks: 37
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- freaking_awesome_elixir - Elixir - A client for Chrome's DevTools API to generate PDFs (HTML to PDF). (PDF)
- fucking-awesome-elixir - chromic_pdf - A client for Chrome's DevTools API to generate PDFs (HTML to PDF). (PDF)
- awesome-elixir - chromic_pdf - A client for Chrome's DevTools API to generate PDFs (HTML to PDF). (PDF)
README
[](https://circleci.com/gh/bitcrowd/chromic_pdf)
[](https://hex.pm/packages/chromic_pdf)
[](https://hexdocs.pm/chromic_pdf/)
[](https://hex.pm/packages/chromic_pdf)
[](https://github.com/bitcrowd/chromic_pdf/blob/master/LICENSE)
[](https://github.com/bitcrowd/chromic_pdf/commits/master)
ChromicPDF is a HTML-to-PDF renderer for Elixir, based on headless Chrome.
## Features
* **Node-free**: In contrast to [many other](https://hex.pm/packages?search=pdf&sort=recent_downloads) packages, it does not use [puppeteer](https://github.com/puppeteer/puppeteer), and hence does not require Node.js. It communicates directly with Chrome's [DevTools API](https://chromedevtools.github.io/devtools-protocol/) 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`](https://chromedevtools.github.io/devtools-protocol/tot/Page#method-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](https://verapdf.org/) validator.
## Requirements
- Chromium or Chrome
- Ghostscript (optional, for PDF/A support and concatenation of multiple sources)
ChromicPDF is tested in the following configurations:
| Elixir | Erlang/OTP | Distribution | Chromium | Ghostscript |
| ------ | ---------- | --------------- | --------------- | ----------- |
| 1.15.7 | 26.2 | Alpine 3.18 | 119.0.6045.159 | 10.02.0 |
| 1.14.5 | 25.3.1 | Alpine 3.17 | 112.0.5615.165 | 10.01.1 |
| 1.14.0 | 25.1 | Debian Buster | 90.0.4430.212-1 | 9.27 |
| 1.11.4 | 22.3.4.26 | Debian Buster | 90.0.4430.212-1 | 9.27 |
## 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:
```elixir
def deps do
[
{:chromic_pdf, "~> 1.17"}
]
end
```
Next, start ChromicPDF as part of your application:
```elixir
# 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
### Main API
Here's how you generate a PDF from an external URL and store it in the local filesystem.
```elixir
# 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.
```elixir
ChromicPDF.print_to_pdfa({:url, "file:///example.html"}, output: fn pdf ->
# Send pdf via mail, upload to S3, ...
end)
```
### Template API
[ChromicPDF.Template](https://hexdocs.pm/chromic_pdf/ChromicPDF.Template.html) contains
additional functionality for controlling page dimensions of your PDF.
```elixir
[content: "
Hello Template
", size: :a4]
|> ChromicPDF.Template.source_and_options()
|> ChromicPDF.print_to_pdf()
```
### Multiple sources
Multiple sources can be automatically concatenated using Ghostscript.
```elixir
ChromicPDF.print_to_pdf([{:html, "page 1"}, {:html, "page 2"}], output: "joined.pdf")
```
### Examples
* There is an outdated example of how to integrate ChromicPDF in a Phoenix application, see [examples/phoenix](https://github.com/bitcrowd/chromic_pdf/tree/v1.14.0/examples/phoenix).
## 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`](https://verapdf.org/)
* For `pdfinfo` and `pdftotext`, you need `poppler-utils` (most Linux distributions) or [Xpdf](https://www.xpdfreader.com/) (OSX)
* For the odd ZUGFeRD test in [`zugferd_test.exs`](https://github.com/bitcrowd/chromic_pdf/tree/main/test/integration/zugferd_test.exs), you need to download [ZUV](https://github.com/ZUGFeRD/ZUV) and set the `$ZUV_JAR` environment variable.
## Acknowledgements
* The PDF/A conversion is inspired by the `pdf2archive` script originally created by [@matteosecli](https://github.com/matteosecli/pdf2archive) and later enhanced by [@JaimeChavarriaga](https://github.com/JaimeChavarriaga/pdf2archive/tree/feature/support_pdf2b).
## Copyright and License
Copyright (c) 2019–2023 Bitcrowd GmbH
Licensed under the Apache License 2.0. See [LICENSE](LICENSE) file for details.