DEV Community: rastersly

HTML to PDF that doesn't look broken: the CSS nobody documents

rastersly — Mon, 21 Sep 2026 11:43:38 +0000

Disclosure up front: I build a render API (rasterly) that does HTML to PDF among other things. This post is the stuff I wish someone had written before I spent a week on it, not a pitch. The rules below work with any Chromium-based renderer.

You have an HTML invoice. It looks perfect in the browser. You render it to PDF and a table row is sliced in half across the page break, the brand color is gone, and there's a mystery 1cm margin you never set. Here's why, and the small set of CSS rules that actually fixes it.

The renderer matters more than the HTML

Two families of HTML-to-PDF exist, and they behave completely differently:

Chromium's printToPDF (Playwright/Puppeteer page.pdf(), and hosted APIs built on it). This is a real browser print engine. It honors @page, break-inside, print media queries, and web fonts.
Lightweight HTML-to-image/PDF libraries (wkhtmltopdf, many "html to pdf" npm packages). These use older or partial engines and quietly ignore half of the print CSS spec.

If your PDFs look wrong and you're on a lightweight library, that's usually the whole problem. Everything below assumes a Chromium-based renderer, because that's the one that respects these rules.

The four rules that fix 90% of broken PDFs

1. Backgrounds disappear unless you ask for them. Print defaults to no background graphics, to save ink. Colors, background images, and shaded table headers vanish. In Chromium you turn them back on at render time:

await page.pdf({ printBackground: true, format: "A4" });

On a hosted API it's usually a print_background=true flag. This single setting is the most common "my PDF is missing the design" bug.

2. Control the page box with @page, not element margins. The paper size, orientation, and the physical margin around the printable area are set with the @page rule, in real units:

@page {
  size: A4;
  margin: 18mm 16mm;
}

Trying to fake page margins with body { padding } fights the engine and drifts across pages. Set the page box once with @page and let content flow inside it.

3. Stop rows and cards from splitting across pages. The ugliest break bug is a table row or a card cut in half by a page boundary. break-inside: avoid keeps an element whole:

tr, .card, .line-item { break-inside: avoid; }
thead { display: table-header-group; } /* repeat table headers on every page */

That table-header-group trick is the one people miss: it makes the table header reprint at the top of every page instead of appearing only on page one.

4. Fonts: embed or fall back visibly. A PDF renders on a server with no system fonts, so anything you don't load explicitly falls back to a default and your careful typography is gone. Load web fonts and, for print, prefer font-display: swap so text never renders invisibly while a font is pending.

A print stylesheet, in one block

Most document PDFs need exactly this:

@page { size: A4; margin: 18mm 16mm; }

@media print {
  body { -webkit-print-color-adjust: exact; print-color-adjust: exact; }
  tr, .line-item, .card { break-inside: avoid; }
  thead { display: table-header-group; }
  .page-break { break-before: page; }
  a::after { content: ""; } /* don't print the raw URL after every link */
}

print-color-adjust: exact is the CSS-side partner to printBackground — some engines want the flag, some want the CSS, so set both and stop guessing.

The full round trip

Here's the whole thing end to end against a hosted renderer (swap the host/header for whichever you use):

curl -X POST "https://api.rasterly.dev/v1/pdf" \
  -H "X-Api-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<style>@page{size:A4;margin:18mm}tr{break-inside:avoid}thead{display:table-header-group}</style><h1>Invoice INV-42</h1><table>...</table>",
    "format": "A4",
    "print_background": true
  }' \
  -o invoice.pdf

The same call with Playwright directly is page.setContent(html) then page.pdf({ printBackground: true, format: "A4" }). Hosted or self-run, the CSS is identical — that's the point of this post.

How to tell if it's your CSS or your renderer

Render the same HTML two ways: once through your current tool, once through headless Chromium (page.pdf). If Chromium gets the backgrounds, page breaks, and fonts right and your tool doesn't, the tool is the problem, not your markup. If both get it wrong, it's the four rules above.

I put a live HTML-to-PDF playground on my site if you want to throw a real invoice at it: rasterly.dev/use/pdf-generation-api. But the rules travel — paste that print stylesheet into whatever you already use and most "broken PDF" tickets go away.

Happy to dig into specific break or font issues in the comments.

Screenshot APIs in 2026: what you're actually paying for

rastersly — Sun, 20 Sep 2026 14:18:45 +0000

Disclosure up front: I build one of these APIs (rasterly). I've tried to keep the comparison fair and the numbers checkable — call out anything that reads as a plug.

Every few months someone on my team says "let's just run headless Chrome ourselves." Two weeks later there's a memory-leak cron, a font that renders as tofu in the container, and a Chromium version pinned three releases back because upgrading broke PDFs. So most teams end up renting the render instead. This post is about what you're actually paying for when you do.

What a "screenshot" really is

A screenshot API does one mechanical thing: boot a headless browser, navigate to a URL, wait for the page to settle, and hand back the pixels (or a PDF, or the extracted text). The interesting part is the word warm. A cold browser start is 300–800ms of pure overhead. A warm browser that's reused across requests turns a render into roughly one second of CPU — and that single fact is why prices are all over the map. Some vendors price on that cost. Some price on "it's a magic image service" and charge accordingly.

That's the lens for the whole market: is this priced like a CPU-second, or like a SaaS seat?

The runnable version

Every hosted option is basically the same shape — a URL, some options, a key. Here's the same job three ways:

# curl
curl "https://api.rasterly.dev/v1/screenshot?url=https://stripe.com&full_page=true&format=png" \
  -H "X-Api-Key: sk_live_..." -o shot.png

// Node — save a full-page PNG
import { writeFile } from "node:fs/promises";

const res = await fetch(
  "https://api.rasterly.dev/v1/screenshot?" + new URLSearchParams({
    url: "https://stripe.com", full_page: "true", format: "png", scale: "2",
  }),
  { headers: { "X-Api-Key": process.env.RASTERLY_KEY } }
);
await writeFile("shot.png", Buffer.from(await res.arrayBuffer()));

# Python
import os, requests

r = requests.get(
    "https://api.rasterly.dev/v1/screenshot",
    params={"url": "https://stripe.com", "full_page": True, "format": "png"},
    headers={"X-Api-Key": os.environ["RASTERLY_KEY"]},
)
open("shot.png", "wb").write(r.content)

Swap the base URL and header name and this is Urlbox, ScreenshotOne, ApiFlash or Browserless too. Migration between them is mostly a find-and-replace, which is worth remembering when a vendor's price creeps up.

The five things that actually matter

Forget the feature matrices for a second. In production these are what bite:

Warm vs cold. Ask (or benchmark) whether renders reuse a browser. It's the difference between ~1s and ~3s per call, and it shows up directly in your bill.
Full-page + retina done right. full_page=true and scale=2/3 sound trivial; they're where lazy-loaded images and sticky headers break. Test on a real, heavy page, not example.com.
PDF page control. If you generate documents, you need @page, margins, and break-inside: avoid. Chromium honours these; lighter HTML-to-PDF tools mostly don't, and that's usually what makes a PDF look wrong.
SSRF protection. A "render any URL" endpoint is an SSRF cannon if it isn't locked down. Whatever you use, confirm it refuses localhost, private ranges, and 169.254.169.254. If you self-host, this is on you.
Pricing units. Per-render, per-1,000, monthly tiers, credits-that-cost-different-amounts-per-feature… normalize everything to dollars per 1,000 renders at your real volume before comparing. It's often a 10x spread.

Rough cost intuition

I won't quote competitors' live prices — they change, and you should check them yourself — but the shape is consistent: category-priced screenshot APIs tend to land in the low single-digit dollars per 1,000 renders at mid volume, sometimes higher. A CPU-cost-priced one lands in the cents. On rasterly that's $0.58 per 1,000 at the Growth tier and a free 100/month with no card; the point isn't the specific number, it's that a one-second render can be cents, so if you're paying dollars, know why.

Self-hosting Puppeteer/Playwright looks free until you price the cold starts, the memory headroom for full-page captures, the base image with the right fonts and codecs, and the human who babysits it. For a low, spiky volume it can win. For steady volume it usually doesn't.

How to actually pick

Just need a picture of a URL? Any of them work; sort by dollars-per-1,000 at your volume and by whether full-page/retina look right on your worst page.
Generating documents/invoices? Prioritise PDF page-control and font handling.
Feeding an LLM or agent? You'll want the page as Markdown/JSON too, not just an image — check whether one key covers screenshot + read/extract, or whether you're bolting on a second vendor.
Tiny or bursty volume? Self-hosting or a generous free tier may beat any paid plan.

See it before you sign up

The most useful thing I added to my own site is a page that just renders your URL live and shows the cost next to whatever vendor you're on, no signup:

rasterly.dev/proof?url=your-site.com — swap in your own domain.

If you're evaluating any screenshot API, do that with all of them: throw your ugliest real page at each, full-page, and compare the output and the per-1,000 side by side. The winner is usually obvious once you stop reading marketing pages and start rendering your own worst case.

Happy to answer questions on the rendering pipeline, PDF gotchas, or the pricing math in the comments.

I built a screenshot API that's 89% cheaper — here's the one trick

rastersly — Tue, 18 Aug 2026 13:13:02 +0000

Screenshot APIs are one of the most quietly overpriced corners of dev tooling. The big ones charge $250–500/mo — for what is, underneath, a headless browser opening a page and handing back the bytes. I wanted to know how cheap it could be, so I built one.

The one trick: reuse the browser

The naive way to build a screenshot API is one browser launch per request. Launching Chromium costs ~2–5 seconds and a chunk of RAM every single time — that's where the cost (and the pricing) comes from.

rasterly keeps one Chromium instance alive and opens a fresh context per request:

Cold start (first request): ~5s
Warm render: ~1s of CPU

A warm render costing about a second of CPU means the real per-render cost is cents, not dollars. So I price on that: from $0.90 per 1,000, versus ~$5/1,000 at the pricier incumbents.

Don't skip the SSRF guard

A screenshot API takes a URL from a stranger and opens it from your server. Without a guard, someone points it at http://169.254.169.254/… and reads your cloud metadata.

Every target is DNS-resolved first and refused if it lands on localhost, a private range, link-local, or cloud metadata. Enforced, not a setting.

PDF is basically free

Once you have a page open in Chromium, page.pdf() is right there — so PDF is a first-class format at the same endpoint and price as an image:

curl "https://api.rasterly.dev/v1/screenshot?url=https://stripe.com&format=pdf" \
  -H "X-Api-Key: ..." -o page.pdf

Try it — no signup

There's a live box on the landing page: paste a URL, and it hits the real API and streams the screenshot right back. Here it is rendering Hacker News in ~1.7s:

Go break it yourself → rasterly.dev

It's brand new and I'm a solo dev, so I'd love feedback — especially on the security side and on formats you'd actually need.

Prices and features mentioned were observed in August 2026 and are shown for comparison only; rasterly is an independent product, not affiliated with any other tool named.