BreezyPDF provides a ruby client for integration into your Rails, Sinatra, Hanami, and other Rack based web applications, as well as non-web applications.


The ruby client is distributed via a minimum dependency ruby gem. This guide expects that you know how to install and work with gems.

Add it to your gem file.

gem 'breezy_pdf'

As a HTTP Middleware

BreezyPDF includes a Rack middleware which will automatically intercept HTTP GET requests to a resource, render the HTML at that given URL, and redirect the client to the URL which will eventually return the generated PDF.

Ruby on Rails

config.middleware.use BreezyPDF::Middleware


use BreezyPDF::Middleware


BreezyPDF has some extensive configuration options. This configuration should be done when your project is initialized.

Specifying your secret API key is the only required configuration.

Addtional configuration options not covered here can be found in the README of the gem's source code:

Ruby on Rails

BreezyPDF.setup do |config|
config.secret_api_key = "YOUR_SECRET_API_KEY"
# ...


BreezyPDF.setup do |config|
config.secret_api_key = "YOUR_SECRET_API_KEY"
# ...

Render your first PDF as an HTTP request

The default configuration options are optimized for rendering PDF's in your local development enviornment. You may or may not want to modify these settings for your production environment.

  • config.middleware_path_matchers = [/\.pdf/]

  • config.treat_urls_as_private = true

  • config.upload_assets = true

  • config.asset_selectors = %w(img script link[rel="stylesheet"])

  • config.asset_cache =

Let's assume you have an HTML report that lives at the path /reports/quarterly. BreezPDF will automatically intercept and convert the report to a PDF by adding a .pdf extension to the URL. Let's add a button in your HTML.

<a href="/reports/quarterly.pdf">Download PDF</a>

Clicking the link will redirect you to the PDF version of your Quarterly Report!

Configure how your page is rendered

BreezyPDF provides extensive control over how you might want your page to render. This can be done via meta tags anywhere within the HTML document. See the Metadata section for options.

Add a Loading/Progress/Busy Animation

Generation of your PDF may take a few seconds, so leaving your user hanging without any UI indication might not be the best.

<a href="/reports/quarterly.pdf" class="pdf-link">Download as PDF</a>
<script type="text/javascript">
$('.pdf-link').on('click', function(clickEv) {
var startTime = new Date();
var targetEl = $(;
var modalEl = $('#pdf-loading'); // An existing bootstrap modal in this example
var ajaxRequest = new XMLHttpRequest();
ajaxRequest.addEventListener('load', function(ev) {
window.location = ev.currentTarget.responseURL;
modalEl.modal('show');'GET', targetEl.attr('href'));

Pragmatic Usage

BreezyPDF facilitates generating PDF's outside of a HTTP request.

def invoice_mailer(user, invoice)
asset_host = Rails.env.production? ? Rails.application.config.action_controller.asset_host : "http://localhost:3000"
metadata = { width: 8.5, width: 11 }
html = ActionController::Renderer.render(template "invoices/show", assigns: { invoice: invoice }, locals: { current_user: user })
pdf =, html, metadata)
attachments["invoice-#{}.pdf"] =
@pdf_url = pdf.to_url