Migrating from other PDF APIs
Port from PDFShift, DocRaptor, API2PDF, HTML/CSS to PDF — what maps cleanly, what doesn't, and a few worked diffs.
Migrating from other PDF APIs
The big trade-off when moving to gpdf-api is that we don't accept HTML/CSS. We accept JSON. That's why we're 10–30× faster than browser-based services, but it does mean some of your existing template work has to be rewritten.
This page is a practical "where do I start" guide.
The mental model shift
| HTML/CSS PDF service | gpdf-api |
|---|---|
| HTML in, PDF out | JSON-template tree in, PDF out |
| Headless Chromium | Pure-Go layout engine |
| Per-render Chromium spin-up | One process, in-memory render |
@page rules in CSS |
template.page JSON |
media print styling |
Style hints in template nodes |
External <img src> follows redirects |
Same — but only https:// and capped at 8 MB |
Fonts via @font-face |
Bundled CJK + custom upload |
The most common surprise: there's no position: absolute, no flexbox, no z-index. Layout is row-and-column on a 12-column grid plus explicit page breaks. That covers ~99% of business documents (invoices, quotes, statements, reports). It does not cover free-form magazine-style design — for that, keep your existing service.
From PDFShift / DocRaptor / API2PDF
These services all take an HTML URL or HTML body. The mapping is:
| Their concept | gpdf-api |
|---|---|
| HTML body | template.body (rebuild as JSON nodes) |
| HTML URL | Not supported — you must own the document. |
margin CSS |
template.page.margin |
@page :first |
template.page.firstPage |
<header> / <footer> printed on every page |
template.header / template.footer |
page-break-before: always |
{ "page-break": true } |
Inline <img> |
image node |
<table> |
table node |
| Web fonts | Custom font upload, then style.font |
Worked example: PDFShift invoice
PDFShift request:
POST https://api.pdfshift.io/v3/convert/pdf
{
"source": "<html>...<h1>Invoice</h1>...<table>...</table>...</html>",
"format": "A4",
"margin": "20mm"
}
gpdf-api equivalent:
POST https://api.gpdf.dev/v1/pdf
{
"template": {
"page": { "size": "A4", "margin": "20mm" },
"body": [
{ "text": "Invoice", "style": { "fontSize": 22, "weight": "bold" }},
{ "spacer": "8mm" },
{ "table": {
"columns": [{ "span": 8 }, { "span": 4, "align": "right" }],
"rows": [
[{ "text": "Consulting" }, { "text": "$2,400.00" }]
]
}}
]
}
}
Lines of CSS gone, lines of JSON to maintain about the same. Render time goes from ~700 ms (Chromium spin-up) to ~13 ms.
From WeasyPrint / WkHtmlToPdf (self-hosted)
Same shape as the SaaS examples above — port the HTML structure to JSON nodes. The big wins:
- No more "wkhtmltopdf 0.12 vs 0.13 renders this slightly differently" surprises.
- No more font-detection bugs after a Docker base-image upgrade.
- Memory under a few MB per render, instead of a Chromium process.
From Puppeteer / Playwright
These give you full programmatic control of a real browser. Two reasons people use them:
- Rendering charts/visualisations. No good direct mapping. If you produce SVG charts (Chart.js → SVG, ECharts → SVG, D3 → SVG), embed them as
imagenodes — see Images. - Pixel-exact rendering of a web page. Outside our scope. Keep your headless browser for that.
For the first case, the typical refactor:
// Before: Puppeteer renders chart on a hidden page
const browser = await puppeteer.launch()
const page = await browser.newPage()
await page.setContent(htmlWithChart)
const pdf = await page.pdf({ format: 'A4' })
// After: render the chart as SVG on the server, embed in gpdf-api
const svg = renderChart({ data, width: 600, height: 300 }) // your existing chart lib
const pdf = await fetch('https://api.gpdf.dev/v1/pdf', {
method: 'POST',
headers,
body: JSON.stringify({
template: {
page: { size: 'A4' },
body: [{ image: `data:image/svg+xml;base64,${btoa(svg)}`, width: '180mm' }]
}
})
}).then(r => r.arrayBuffer())
Net effect: usually a 10× speed-up because there's no browser at all.
What doesn't migrate
If your existing PDFs depend on any of these, gpdf-api is not (yet) a drop-in replacement:
- Free-form positioned text (
position: absolutemagazine layouts). - CSS animations baked into HTML (we render static documents).
- Forms with JavaScript validation (we flatten or render — not interactive).
- Vertical Japanese (
縦書き) — v2. - PDF/A-3 with embedded XML invoice (PDF/A-1 and PDF/A-2 are supported via
options.pdfa).
For the first three, the answer is "keep your existing service". For the others, we'd love to hear from you on GitHub.
Migration checklist
- Pick one template — pick the simplest, highest-traffic one. Quote, invoice, receipt.
- Write the JSON template — start by mirroring the structure you have. Don't optimise yet.
- Diff the output side-by-side — pixel-diff if you can. Most differences will be padding / line height; tweak
styleuntil you're happy. - A/B in production — render with both providers for 1% of traffic for a week. Watch error rates.
- Cut over — flip the percentage to 100. Turn off the old provider once you've verified bills, audit logs, and customer downloads still work.
Worth doing? (Yes if…)
- Your bill is non-trivial (PDFShift / DocRaptor get expensive quickly).
- You're seeing tail latency over 1 s.
- You have multiple Chromium-related bugs in your tracker.
- You generate large batches (>50 PDFs/request).
Not worth doing if your PDFs are HTML-heavy and your volume is < 100/day — the migration cost dominates.
Related
- Templates → — JSON template grammar.
- Performance → — what you're trading for.
- Quickstart → — the 3-minute version.
Something unclear or missing on this page?