Why HTML-to-PDF Breaks in Production (and What to Use Instead)

Almost every "generate a PDF" feature starts the same way. You already have HTML. You already have CSS. So you reach for the obvious move: render the page, screenshot it to PDF, ship it. Puppeteer, Playwright, wkhtmltopdf, a hosted "HTML to PDF API" — pick your flavor. In an afternoon you have an invoice coming out the other end and it looks fine. Then it goes to production. And "fine" slowly turns into a backlog of weird, hard-to-reproduce bugs. This is not an argument that HTML-to-PDF is useless. For a one-off export or an internal report, it's great. The argument is narrower: the moment PDF generation becomes a real, automated, customer-facing part of your product, "screenshot a web page" is the wrong abstraction — and the failure modes are predictable enough to list in advance. The core problem: a PDF is not a web page A browser renders for an infinite, scrollable, single-width viewport. A PDF is a stack of fixed, finite, printable pages. Those are different physics. HTML-to-PDF works by rendering your page in a headless browser and then slicing that continuous render into page-sized pieces. Everything that's hard about it comes from that one mismatch: you designed for a stream, and now you're forcing it into pages. Most of the bugs below are just that mismatch showing up in different costumes. Failure mode 1: pagination This is the big one. A browser has no concept of "page 2." So when your content is taller than one page, the engine has to guess where to cut — and it cuts wherever the pixel ruler lands. That means: a table row sliced in half across the page break a heading stranded alone at the bottom of a page, its content on the next a total row that floats away from the table it belongs to a signature block split from the line above it CSS has break-inside: avoid , break-before , and friends — and they help. But support is uneven across engines, they interact badly with flex/grid, and you end up hand-tuning rules per document until it looks right for the da