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:

  1. Rendering charts/visualisations. No good direct mapping. If you produce SVG charts (Chart.js → SVG, ECharts → SVG, D3 → SVG), embed them as image nodes — see Images.
  2. 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: absolute magazine 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

  1. Pick one template — pick the simplest, highest-traffic one. Quote, invoice, receipt.
  2. Write the JSON template — start by mirroring the structure you have. Don't optimise yet.
  3. Diff the output side-by-side — pixel-diff if you can. Most differences will be padding / line height; tweak style until you're happy.
  4. A/B in production — render with both providers for 1% of traffic for a week. Watch error rates.
  5. 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.

Something unclear or missing on this page?