HTML to PDF Rails: Convert a Ruby on Rails View to a Real PDF

For a decade, "HTML to PDF in Rails" meant WickedPDF, and the pattern it popularized was genuinely good: you render a normal Rails view, in a normal layout, and get a PDF of it. The problem is not the gem, it is the engine underneath. WickedPDF shells out to wkhtmltopdf, and the wkhtmltopdf project was archived in 2023. It still runs, and plenty of production apps still use it, but nothing is being fixed, including security issues, and its rendering engine is an old WebKit fork that never learned modern CSS.

What that means in practice: a template written today with flexbox or CSS grid will not lay out correctly, web fonts are fragile, and JavaScript-driven content is a coin flip. If you have a WickedPDF app that works, there is no emergency, but treat it as a temporary state and pin your binary version. For anything new, start on a current engine. The wkhtmltopdf alternative page maps the replacements across every language, not just Ruby.

The two in-app successors both give you Chromium, and the difference between them is the stack you have to carry. Grover drives Chromium through Puppeteer, which means Node and a Chromium download live in your image alongside Ruby. It keeps the familiar shape, so a WickedPDF migration is mostly mechanical: you still build HTML with render_to_string and pass it in. Ferrum talks to Chromium directly over the Chrome DevTools Protocol from Ruby, so the Node layer disappears and there is one less wrapper between your call and the browser.

Both are solid, and if you are comfortable running a browser they are the cheapest way to get browser-quality output. Be clear-eyed about what running a browser means, though. Chromium is memory hungry, a crashed or leaked browser process will take a Puma worker with it, and sizing a pool for a Monday-morning batch of statements is a real capacity exercise rather than a one-line config. Teams usually discover this the first time a month-end job renders two thousand documents at once.

If you want browser fidelity but not a browser, the pattern stays the same and only the last step changes. Render your view to a string exactly as you would for Grover, then post it, or point the API at a live route in your app and let it load the page and run the JavaScript.

class InvoicesController < ApplicationController
  def show
    html = render_to_string(template: "invoices/show", layout: "pdf", formats: [:html])

    response = Faraday.post("https://api.sitepdf.com/v1/render") do |req|
      req.headers["Authorization"] = "Bearer #{ENV['SITEPDF_KEY']}"
      req.body = { html: html, format: "Letter", archive: "true" }
    end

    redirect_to JSON.parse(response.body)["pdf_url"], allow_other_host: true
  end
end

Your asset pipeline output, Tailwind classes, web fonts and any JavaScript charts render the way they do in Chrome, and the PDF text stays selectable and searchable rather than becoming a flat image. Nothing runs a browser inside your dyno or pod, so a spike in PDF volume does not become a memory incident in your web tier. The same call works from a Sidekiq job for background generation, which is where most Rails PDF work belongs anyway. Our HTML to PDF in Ruby guide covers the gem-by-gem detail including Prawn, and the PDF generator API page lists every parameter.

One honest caveat before you reach for any HTML renderer. If the document has no HTML version and never will, a shipping label, a boarding pass, a generated certificate, then Prawn is probably the right tool. It is pure Ruby, draws the page in code, has no browser or binary behind it, and is the fastest option because it skips a layout engine entirely. The trade is that you describe the document in Ruby rather than reusing a view, so it drifts from your web pages over time. Use Prawn when there is no page to mirror, and an HTML renderer when there is one.

A generated invoice, quote or statement leaves your Rails app and nothing verifiable stays behind. Add archive=true to the render call and Sitepdf also stores a timestamped, immutable snapshot of exactly what it rendered, retrievable by id later, so you can prove what a document said on a given date. The website archiving page explains how the record works, and if you are weighing running headless Chrome yourself, the Puppeteer alternative page runs that trade off honestly. Renders are transient by default; leave archiving off and we return the PDF and store nothing.