HTML render engine

Second-generation Airpdf render path: instead of the JSON-tree react-pdf pipeline, your template is plain HTML + CSS rendered by Chromium headless (via Puppeteer) for pixel-perfect output. Trade-off: ~5-10× slower than react-pdf, ~10× more memory per render, N× higher quota cost (default 25×).

Use the HTML engine when you need:

• Existing HTML/CSS layouts you can’t or won’t translate to JSON-tree
• Complex typography, Flexbox/Grid, web fonts, CSS custom properties
• Brand-perfect rendering matching an existing print stylesheet
• Headers/footers via Chromium’s native PDF margin templates

Stick with the react-pdf engine (default) for high-volume, latency- sensitive workloads and standard document layouts.

Enablement

The HTML engine is opt-in per plan:

plan.html_engine_enabled            : boolean (default false)
plan.html_engine_render_multiplier  : integer (default 1, typical 25)
plan.html_rate_limit_per_minute     : integer (default 10)

Toggled by the platform super-admin on a per-plan basis (/platform/plans). Workspaces subscribed to a plan with html_engine_enabled = false get HTTP 402 Payment Required if they attempt an HTML render.

Template configuration

Each template carries an engine field (react_pdf | html). For HTML templates also set html_template — the full HTML body with optional Mustache placeholders.

Set via:

• Editor UI: open template editor → header toggle “JSON” / “HTML” (gated by plan flag)
• API: PATCH /api/v1/templates/:slug with { "engine": "html", "html_template": "<!doctype html>..." }
• IEx: Airpdf.Templates.update_template(template, %{engine: :html, html_template: "..."}, scope: scope)

Variable substitution

The HTML body supports {{ path.to.value }} Mustache-style placeholders hydrated server-side by Phoenix before shipping the body to Chromium. Chromium itself never sees raw tenant template logic; this neutralises a broad class of SSRF/code-execution attacks against the browser process.

Supported syntax:

Missing paths render as empty string. All non-string values are coerced to string (integer, float, boolean, nil → "").

XSS defense: double-stash {{x}} always escapes <>&"'. Use the triple-stash form {{{x}}} only when the value is known-safe HTML generated by your own server.

Example

Template:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <style>
      body {
        font-family: 'Inter', system-ui;
        padding: 40px;
      }
      h1 {
        color: #06231a;
        border-bottom: 2px solid #9bf0c8;
      }
      .total {
        font-size: 24px;
        font-weight: 700;
      }
    </style>
  </head>
  <body>
    <h1>Invoice {{ invoice.number }}</h1>
    <p>To: <strong>{{ customer.name }}</strong> (VAT {{ customer.vat }})</p>
    <p>Date: {{ invoice.date }}</p>

    <table>
      <thead>
        <tr>
          <th>Item</th>
          <th>Qty</th>
          <th>Amount</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td>{{ items.0.label }}</td>
          <td>{{ items.0.qty }}</td>
          <td>€ {{ items.0.amount }}</td>
        </tr>
        <tr>
          <td>{{ items.1.label }}</td>
          <td>{{ items.1.qty }}</td>
          <td>€ {{ items.1.amount }}</td>
        </tr>
      </tbody>
    </table>

    <p class="total">Total: {{ totals.amount }}</p>
  </body>
</html>

Render call:

curl -X POST https://api.airpdf.io/api/v1/render \
  -H "x-api-key: $AIRPDF_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "template": "invoice-html",
    "data": {
      "invoice": {"number":"2026-0042","date":"2026-05-10"},
      "customer": {"name":"Globex Srl","vat":"IT09876"},
      "items": [
        {"label":"Pro plan","qty":1,"amount":99},
        {"label":"Premium support","qty":1,"amount":29}
      ],

    }
  }' --output invoice.pdf

PDF options

Pass under the options field of the render call:

Example:

{
  "template": "invoice-html",
  "data": { ... },
  "options": {
    "format": "A4",
    "margin": { "top": "60px", "bottom": "80px" },
    "printBackground": true,
    "displayHeaderFooter": true,
    "headerTemplate": "<div style='font-size:10px;width:100%;text-align:center'>Confidential</div>",
    "footerTemplate": "<div style='font-size:10px;width:100%;text-align:center'>Page <span class=pageNumber></span> of <span class=totalPages></span></div>"
  }
}

Engine override per request

For testing or migration, force the engine independently of the template default by adding "engine": "html" or "engine": "react_pdf" to the request body:

{ "template": "invoice", "data": {...}, "engine": "html" }

The plan gate still applies — HTML requires html_engine_enabled = true.

Quota & rate limits

Quota multiplier

Each HTML render consumes plan.html_engine_render_multiplier units against the monthly render_limit_monthly, instead of 1. With multiplier 25, an HTML-heavy month of 100 renders eats 2,500 quota units, same as 2,500 react_pdf renders.

Rate limit

Separate bucket from the standard plug-level rate limit:

plan.rate_limit_per_minute       : applies to /api/v1/render (any engine)
plan.html_rate_limit_per_minute  : additional bucket, only for engine=:html

A request to render HTML increments both buckets. If either exceeds its threshold the request gets 429 too_many_requests with a retry-after header.

Limits and caveats

• Font loading: Chromium downloads @font-face URLs at render time. Slow networks → render timeout. Prefer data-URI inline or tenant-uploaded font assets cached in your CDN.
• JavaScript: Inline <script> runs in the browser context (no network restrictions). Avoid for security — use server-side data substitution via Mustache instead.
• External resources: Images and stylesheets referenced by URL are fetched by Chromium, no proxy. Don’t rely on localhost or internal URLs.
• Visual regression: Pin Chromium version (managed by us via the Docker image); snapshot-based regression tests recommended on your side before bumping render_version.
• Memory bomb defense: per-render budget enforced by MAX_HEAP_MB on the render service; render process gracefully exits and is recycled by Fly when budgets are exceeded.

Error codes