DEV Community: Accreditly

Why your Open Graph image doesn't show up when you share a link

Accreditly — Wed, 12 Aug 2026 17:26:06 +0000

You paste a link into Slack and the preview comes back as a bare grey rectangle. Or the title shows and the image does not. Or LinkedIn serves artwork from three deploys ago. You open devtools, the tags are right there, and the card is still wrong.

The reason is nearly always the same one. The thing reading your page is not a browser. A social crawler makes one anonymous request, parses the HTML that came back over the wire, fetches the image, and leaves. No session, no JavaScript engine, no patience. We have published the full version of this with the platform specifics on the HTML to Image blog, in Why your Open Graph image doesn't show up when you share a link, and this post walks through the eight causes and how to tell them apart.

What happens when someone shares your URL

Four steps, and each fails independently:

The platform requests your URL with a crawler user agent, following redirects.
It parses the served HTML for og: and twitter: tags.
It resolves og:image to an absolute URL and fetches it, often reading only enough of the file to get its dimensions.
It builds a card using its own rules about which tag wins, how to crop, and how much of the title to keep.

Working out which step broke is most of the job.

1. The tags are in devtools but not in the response

The most common cause by a distance. If your head is set client-side, a Vue app assigning meta on mount, a React app using a client-only helmet component, a CMS script patching the head after load, the crawler sees none of it. Devtools shows the DOM after your JavaScript has run. The crawler reads the document as served.

One command tells you:

curl -sL https://example.com/pricing | grep -i 'og:\|twitter:'

Empty output means the tags have to move into server-rendered HTML. In Next.js that is the metadata export or generateMetadata in a server component, not anything set in useEffect. In Nuxt it is useSeoMeta on a server-rendered route. In a static site generator it is the head partial at build time.

2. `og:image` is a relative path

<meta property="og:image" content="/images/og/pricing.png">

Valid HTML, useless to a crawler. The protocol asks for an absolute URL including the scheme, and several platforms drop the image rather than guess your host.

<meta property="og:image" content="https://example.com/images/og/pricing.png">

Same problem with protocol-relative // URLs, and with anything still pointing at localhost because the base URL comes from an environment variable nobody set in production.

3. The image is not reachable by an anonymous bot

The image fetch is as anonymous as the page fetch. Hotlink protection that wants a same-origin referer, Cloudflare Bot Fight Mode on the asset path, a robots.txt rule over the image directory, an expired signed CDN URL, or a private bucket object will all kill it.

curl -sI https://example.com/images/og/pricing.png | head -n 3

You want a 200 and an image content type. A 403 for curl is a 403 for Facebook.

4. No `og:image:width` and `og:image:height`

Seeing your URL for the first time, a platform has no idea how big the image is, so it downloads and measures it before laying out the card. Several will render the card without the image rather than wait, then get it right on the second or third share. Your launch post has already been seen by then.

<meta property="og:image" content="https://example.com/images/og/pricing.png">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:type" content="image/png">
<meta property="og:image:alt" content="Pricing plans for Northgate">

5. The image is the wrong size, ratio or format

1200 by 630 renders cleanly everywhere. Below 600 by 315, Facebook and LinkedIn downgrade to a small square thumbnail beside the text. Over 8MB, the image is dropped. SVG is not read as an og:image anywhere that matters, and WebP support is patchy enough that PNG or JPEG remains the safe answer.

Then the crop. Everything centre-crops toward roughly 1.91:1 and square unfurls keep only the middle band, so a logo or headline near an edge is a logo or headline you sometimes lose.

6. `twitter:card` is missing so X renders the small card

X falls back to og: tags for the title, description and image, which is why people skip the twitter: namespace. The one tag you cannot skip is the card type. Without it you get summary, a small square thumbnail beside the text, instead of the full-width image card.

<meta name="twitter:card" content="summary_large_image">

7. The URL you tested is not the URL people share

Tags are read from the final URL after redirects, and what ends up in the wild is rarely the clean URL you tested. Campaign parameters, a trailing slash difference, a locale prefix, an AMP variant or an http to https hop can each resolve to a document with different tags. Test the canonical URL, then test the exact string your campaign is about to use.

8. Facebook is still showing a card you fixed last week

Meta caches the first scrape hard and can hold it for days. Deploying a fix does not invalidate it, so run the URL through Meta's Sharing Debugger once and use Scrape Again. This one matters mostly because it makes the other seven harder to diagnose. If a live fetch shows correct tags and Facebook shows the old card, the cache is stale rather than your fix being wrong.

Checking the lot in one pass

The official debuggers have thinned out. Meta's needs a Facebook login and only covers Facebook. X removed the rendered preview from its Card Validator, so it now tells you a card is valid without showing you the card. Neither says anything about Slack, Discord or WhatsApp.

We built the Open Graph Checker to run the whole sequence in one request: fetch as a crawler without executing JavaScript, follow redirects and read tags from the final URL, resolve relative image URLs, then read the image's real dimensions, type and file size from the file rather than from what the tags claim. It renders the card as Facebook, X, LinkedIn, Slack, Discord and WhatsApp would each build it, scores the page, and prints a corrected tag block. No login, and it reads live rather than from a cache.

The failures it separates fastest are the ones that look identical from outside: tags missing because they are client-side, an image URL that resolves but returns a 403, an image that is present but 400 pixels wide, and a page that redirects somewhere with different tags.

The block you are aiming for

<meta property="og:type" content="article">
<meta property="og:url" content="https://example.com/pricing">
<meta property="og:site_name" content="Northgate">
<meta property="og:title" content="Pricing that scales with your traffic">
<meta property="og:description" content="Per-render pricing with no seat fees, and a free tier that covers a small site.">
<meta property="og:image" content="https://example.com/images/og/pricing.png">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:type" content="image/png">
<meta property="og:image:alt" content="Pricing plans for Northgate">

<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Pricing that scales with your traffic">
<meta name="twitter:description" content="Per-render pricing with no seat fees, and a free tier that covers a small site.">
<meta name="twitter:image" content="https://example.com/images/og/pricing.png">

Titles under about 60 characters and descriptions under about 155, or they truncate in most placements.

Stopping it happening again

Share metadata rots quietly. It breaks during framework migrations, CMS moves and route refactors, and nothing in your test suite notices because the page still returns a 200. A crude assertion over your important URLs catches most of it:

for url in \
  https://example.com/ \
  https://example.com/pricing \
  https://example.com/docs
do
  html=$(curl -sL "$url")
  echo "$html" | grep -q 'property="og:image"' \
    && echo "ok   $url" \
    || echo "FAIL $url"
done

Run it in CI after deploy, and put your top twenty URLs through a checker after any migration, while the traffic that would have hit those broken cards is still recoverable.

The longer version, including how to generate the card image itself when the answer turns out to be that you never had one, is on the HTML to Image blog.

Which of the eight has bitten you? Mine is client-side tags, twice on the same project.

Generate Open Graph images in GitHub Actions (no headless browser required)

Accreditly — Thu, 06 Aug 2026 13:21:26 +0000

You can render Open Graph images, pull request screenshots and release cards from a GitHub workflow without installing a single browser on the runner. No Puppeteer, no apt-get install block for Chrome's dependencies, no cache step for a 300 MB browser download. One workflow step does the rendering remotely and hands you back a file.

The step is html2img/action, the official GitHub Action for the HTML to Image API. We have published a full write-up of the workflow patterns in Generate Open Graph Images in GitHub Actions, and this tutorial walks you through getting from nothing to committed OG images and PR screenshots, step by step.

Why bother moving the render out of the runner at all? Because a GitHub-hosted runner is a fresh machine every run. Anything a headless browser needs gets installed every time or cached with actions/cache, and both routes add minutes and new ways to fail. An API call takes a couple of seconds whatever the page contains, and fonts, emoji and CSS support stop being your problem.

Prerequisites

A GitHub repository with Actions enabled.
A free HTML to Image account. The free tier comes with 50 credits and does not ask for a card. One credit is one render.
Your API key from the dashboard.

Step 1: Add your API key as a secret

In your repository, go to Settings, then Secrets and variables, then Actions, and create a repository secret named HTML2IMG_API_KEY with your key as the value. The action masks the key in logs, but it still belongs in a secret rather than in the workflow file.

Step 2: Render your first image

Create .github/workflows/render.yml:

name: Render

on: workflow_dispatch

jobs:
  render:
    runs-on: ubuntu-latest
    steps:
      - uses: html2img/action@v1
        id: render
        with:
          api-key: ${{ secrets.HTML2IMG_API_KEY }}
          html: '<div style="font: 700 72px system-ui; padding: 80px">Hello</div>'
          width: 1200
          height: 630
          output-path: hello.png

      - run: echo "Rendered ${{ steps.render.outputs.url }}"

Run it from the Actions tab. The step writes hello.png into the workspace and sets three outputs you can use in later steps: url (the hosted render), path (where the file landed) and skipped (more on that in a moment).

You give the action exactly one source per step: html for inline markup, html-file for a file in your repository, url to screenshot a live page, or template plus variables to render a named template.

Step 3: Generate OG images for your blog posts

Here is the real workflow: every time posts change on main, find the ones with no social card yet, render them, and commit the PNGs. The example paths are Astro's, but only the paths are. Point it at content/posts and it is a Hugo workflow.

name: OG images

on:
  push:
    branches: [main]
    paths: ['src/content/blog/**']

permissions:
  contents: write

jobs:
  find-posts:
    runs-on: ubuntu-latest
    outputs:
      slugs: ${{ steps.find.outputs.slugs }}
    steps:
      - uses: actions/checkout@v4

      - id: find
        run: |
          slugs=$(for file in src/content/blog/*.md; do
            slug=$(basename "$file" .md)
            if [ ! -f "public/og/$slug.png" ]; then printf '%s\n' "$slug"; fi
          done | jq -R . | jq -sc .)
          echo "slugs=$slugs" >> "$GITHUB_OUTPUT"

  render:
    needs: find-posts
    if: needs.find-posts.outputs.slugs != '[]'
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        slug: ${{ fromJSON(needs.find-posts.outputs.slugs) }}
    steps:
      - uses: actions/checkout@v4

      - name: Build the card markup
        run: |
          title=$(sed -n 's/^title: *//p' "src/content/blog/${{ matrix.slug }}.md" | head -1 | tr -d '"')
          mkdir -p build
          cat > build/card.html <<HTML
          <!doctype html>
          <meta charset="utf-8">
          <div style="display:flex;align-items:center;width:1200px;height:630px;
                      box-sizing:border-box;padding:80px;background:#0f172a;
                      color:#fff;font:700 68px/1.15 system-ui,sans-serif">
            $title
          </div>
          HTML

      - uses: html2img/action@v1
        with:
          api-key: ${{ secrets.HTML2IMG_API_KEY }}
          html-file: build/card.html
          width: 1200
          height: 630
          output-path: public/og/${{ matrix.slug }}.png

      - uses: actions/upload-artifact@v4
        with:
          name: og-${{ matrix.slug }}
          path: public/og/

  commit:
    needs: render
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/download-artifact@v4
        with:
          pattern: og-*
          merge-multiple: true
          path: public/og

      - run: |
          git config user.name 'github-actions[bot]'
          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
          git add public/og
          if git diff --cached --quiet; then
            echo 'No new cards.'
          else
            git commit -m 'Add Open Graph images'
            git push
          fi

Committing the images matters, and it is not just tidiness. On the free plan a hosted render is kept for 7 days. An OG image referenced from a meta tag has to exist for as long as the post does, so the PNG belongs in your repository or your deploy output, not hotlinked from a CDN you do not control.

The card markup above is deliberately minimal so the workflow stays readable. In a real project you would design something better, or skip HTML altogether and use a named template.

Step 4: Screenshot the pull request preview

If your host deploys a preview per pull request, you can screenshot it and post the image as a comment that updates on every push. Reviewers see the change without leaving the PR.

name: Preview screenshot

on:
  pull_request:

permissions:
  contents: read
  pull-requests: write

jobs:
  screenshot:
    if: github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    steps:
      - name: Wait for the preview to answer
        id: preview
        run: |
          url="https://deploy-preview-${{ github.event.pull_request.number }}--example.netlify.app"
          for _ in $(seq 1 30); do
            if curl -fsS -o /dev/null "$url"; then
              echo "url=$url" >> "$GITHUB_OUTPUT"
              exit 0
            fi
            sleep 10
          done
          exit 1

      - uses: html2img/action@v1
        id: shot
        with:
          api-key: ${{ secrets.HTML2IMG_API_KEY }}
          url: ${{ steps.preview.outputs.url }}
          width: 1280
          height: 800
          wait-for-selector: 'main'
          css: '.cookie-banner, .chat-widget { display: none !important }'

      - uses: peter-evans/create-or-update-comment@v4
        with:
          issue-number: ${{ github.event.pull_request.number }}
          body: |
            Preview of ${{ github.event.pull_request.head.sha }}:

            ![Preview screenshot](${{ steps.shot.outputs.url }})

Two inputs are doing the heavy lifting. wait-for-selector holds the capture until your content actually exists in the DOM, and returns the moment it does, which beats guessing a fixed delay. css injects styles over the page's own, and since the page's styles usually win on specificity, that !important is not optional. It is the cleanest way to hide a cookie banner before the shot.

Note the if: guard. GitHub does not expose secrets to workflows triggered by pull requests from forks, so this recipe is for branches on your own repository. That is a platform security decision, and a sensible one, but it is better to know before you wonder why fork PRs get no screenshot.

Two things that save your credits

First, caching. When output-path is set, the action hashes the resolved inputs and writes the digest next to the file as <output-path>.html2img-hash. If the file and a matching digest already exist, the API is never called and the skipped output is true. Commit both files, as the OG workflow does, and re-runs cost nothing. CI re-runs identical work all day long, so this default is what keeps 50 free credits meaning 50 images rather than 50 workflow runs.

Second, DPI. For HTML sources the API's dpi default is 2, so a 1200 by 630 card comes back as a 2400 by 1260 file. That is the right call for retina screens, but if anything downstream asserts exact pixel dimensions, set dpi: 1.

Going further

The same step renders named templates (template: open-graph-image with a variables JSON object), which is how you attach a social card to every release without maintaining any markup, and it takes format: pdf if the artefact you need is a document rather than an image. The full article covers the release workflow, the PDF options and the parameter combinations the action refuses to send, and the action's README has the complete inputs table.

In this tutorial you have set up an API key as a secret, rendered a first image from a workflow, wired up committed OG images for a blog and posted preview screenshots on pull requests, all without a browser anywhere near your CI.

Are you generating OG images at build time, in CI, or on demand at request time? Share your setup in the comments below.

Format Dates, Numbers and Relative Time in JavaScript Without a Library

Accreditly — Tue, 04 Aug 2026 14:00:00 +0000

A surprising number of production bundles still ship a date library to do one thing: print "3 days ago" under a comment. The browser has done that natively for years, in every locale your users speak, through the Intl API. It formats dates, currencies, compact numbers, units, relative time and even lists, and it weighs nothing because it is already there. Let's have a look at the parts you will actually use.

Dates, properly localised

Intl.DateTimeFormat covers almost every date display you will ever need with two options:

const format = new Intl.DateTimeFormat('en-GB', {
  dateStyle: 'long',
  timeStyle: 'short',
  timeZone: 'Europe/London',
});

format.format(new Date());
// "31 July 2026 at 14:00"

Swap 'en-GB' for 'fr', 'de' or 'ja' and the output translates itself, month names and all. The timeZone option means you can store UTC everywhere and render in the user's zone at the last moment, which is the arrangement you wanted anyway.

For a one-off you can skip constructing a formatter and call the shortcut on the date itself:

new Date().toLocaleDateString('en-GB', { dateStyle: 'medium' });
// "31 Jul 2026"

Numbers, currencies and units

Intl.NumberFormat handles the formatting jobs that usually attract hand-rolled regex:

new Intl.NumberFormat('en-GB', {
  style: 'currency',
  currency: 'GBP',
}).format(1499.99);
// "£1,499.99"

new Intl.NumberFormat('en', { notation: 'compact' }).format(1250000);
// "1.3M"

new Intl.NumberFormat('en-GB', {
  style: 'unit',
  unit: 'kilometer',
  unitDisplay: 'long',
}).format(26.2);
// "26.2 kilometres"

That compact notation is the follower-count style you see on every social platform, free of charge. And notice the unit identifier uses the American spelling kilometer while the en-GB output comes back as "kilometres". The identifiers are fixed; the output localises.

Relative time, the bit everyone installs a library for

Intl.RelativeTimeFormat produces the "yesterday" and "in 3 hours" strings:

const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });

rtf.format(-1, 'day');  // "yesterday"
rtf.format(3, 'hour');  // "in 3 hours"

The numeric: 'auto' option is what turns "1 day ago" into "yesterday". The API wants a value and a unit, so in practice you pair it with a small helper that picks the largest sensible unit:

const units = [
  ['year', 31536000],
  ['month', 2592000],
  ['week', 604800],
  ['day', 86400],
  ['hour', 3600],
  ['minute', 60],
  ['second', 1],
];

function timeAgo(date) {
  const delta = (date.getTime() - Date.now()) / 1000;

  for (const [unit, seconds] of units) {
    if (Math.abs(delta) >= seconds || unit === 'second') {
      return rtf.format(Math.round(delta / seconds), unit);
    }
  }
}

timeAgo(new Date(Date.now() - 86400000 * 3));
// "3 days ago"

Fifteen lines, and that is the entire reason many projects still carry a date dependency.

Lists that read like sentences

The least known member of the family might be the most charming. Intl.ListFormat joins arrays the way a human would write them:

const list = new Intl.ListFormat('en-GB', { type: 'conjunction' });

list.format(['PHP', 'JavaScript', 'CSS']);
// "PHP, JavaScript and CSS"

Run the same code under en-US and you get "PHP, JavaScript, and CSS". The API knows about the Oxford comma so you do not have to have the argument.

Create formatters once

One genuine footgun: constructing a formatter is the expensive part, while calling .format() is cheap. Creating a new Intl.DateTimeFormat inside a loop or a hot render path will show up in a profile. Hoist them to module scope, or memoise per locale if the locale varies:

const cache = new Map();

function currencyFormatter(locale, code) {
  const key = `${locale}:${code}`;

  if (!cache.has(key)) {
    cache.set(key, new Intl.NumberFormat(locale, {
      style: 'currency',
      currency: code,
    }));
  }

  return cache.get(key);
}

Where Intl stops

Intl formats. It does not parse "31/07/2026", add a month to a date or convert a timestamp between zones for arithmetic. That is the territory of the incoming Temporal standard, which has started landing in browsers. Until it is everywhere, a fair split is a small library like date-fns for the maths and Intl for everything the user sees.

Recap

In this tutorial you've seen Intl.DateTimeFormat for localised dates, Intl.NumberFormat for currencies, compact notation and units, Intl.RelativeTimeFormat for "3 days ago", Intl.ListFormat for sentence-style lists, and why formatters should be created once and reused. For display work, the platform has quietly made the date library optional.

Which library did Intl let you delete? Tell us in the comments below.

Your AI agent can't design images. It can write HTML.

Accreditly — Tue, 04 Aug 2026 08:52:46 +0000

Ask your AI assistant to "make an OG image for this post" and you get one of two failures. If it reaches for a diffusion model you get soft gradients, warped typography and a title that looks photographed through water. If it does not, it writes you a perfectly good block of HTML and CSS and then apologises, because it has nowhere to render it.

The second failure is the interesting one. The model already did the design work. Layout, spacing, type scale, brand colour, all expressed precisely in the one design language every LLM has read millions of examples of. It was not missing ability. It was missing a render step.

This post wires that step in over MCP, so your agent can design, render and refine real image assets inside the conversation. It is a condensed version of our full guide, How to generate images from an AI agent with MCP, which also covers VS Code, Windsurf and the other clients.

Why diffusion is the wrong tool

Diffusion models are remarkable for photographic concepts and a lottery for layout. They cannot reliably render text, cannot hit exact pixel dimensions, cannot reuse your brand tokens and cannot produce the same output twice. A pricing card, an invoice, a certificate or an OG image needs all four.

HTML and CSS are the opposite: deterministic, pixel-exact, versionable and the most documented visual format in the model's training data. An LLM that mangles the word "Launch" in a generated picture will happily set it in Inter 800 at 96px with correct kerning, because that is just text.

So let the model design in the language it is fluent in, and bolt a renderer onto the end.

Prerequisites

An MCP-capable client (Claude Code or Cursor below)
An HTML to Image API key on a paid plan

The server is remote, so there is nothing to install or host. It lives at https://app.html2img.com/mcp, speaks Streamable HTTP and takes the API key as a bearer token.

Step 1: connect the server

Claude Code is one line:

claude mcp add --transport http html2img https://app.html2img.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Cursor takes the same server in ~/.cursor/mcp.json, or .cursor/mcp.json for a single project:

{
  "mcpServers": {
    "html2img": {
      "url": "https://app.html2img.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

That exposes two tools. generate-image-from-html renders complete HTML to a PNG or PDF. screenshot-url captures a live page, with optional injected CSS and an element selector. Both cost one credit per image.

Step 2: ask for an image

With the server connected, image generation is just conversation:

Make me a 1200x630 launch card for "Relay 2.0". Dark background, big title, a one-line subtitle that says "Webhooks that retry themselves", and our accent green #10B981.

The agent writes something like this and calls the tool with it:

<!doctype html>
<html>
<head>
<style>
  @import url('https://fonts.googleapis.com/css2?family=Inter:wght@500;800&display=swap');
  body {
    width: 1200px; height: 630px; margin: 0;
    display: flex; flex-direction: column; justify-content: center;
    padding: 80px; box-sizing: border-box;
    background: #0B1220; font-family: 'Inter', sans-serif;
  }
  .pill {
    color: #10B981; font-weight: 500; font-size: 22px;
    letter-spacing: 0.14em; text-transform: uppercase;
  }
  h1 { color: #fff; font-size: 96px; font-weight: 800;
       letter-spacing: -0.02em; margin: 18px 0 24px; }
  p  { color: #94A3B8; font-size: 30px; margin: 0; }
</style>
</head>
<body>
  <span class="pill">Now shipping</span>
  <h1>Relay 2.0</h1>
  <p>Webhooks that retry themselves.</p>
</body>
</html>

Two seconds later the rendered card is in the chat with a permanent CDN URL. No Chromium install, no Puppeteer script, no switch to a design tool.

Step 3: let it look at its own work

Here is the part that makes this better than fire-and-forget generation. The tool returns two things to the model: the full-resolution URL, and a downscaled preview image. The preview means the model sees what it made.

So it reviews its render the way you would. It notices the subtitle crowding the title, or a long product name clipping the right edge, then edits the HTML and renders again. You can steer with plain language ("tighten the spacing, the title feels lost") or tell it to critique its own output before showing you. Either way you iterate at conversation speed.

Each pass costs a credit, so three refinements is three credits. For design work that is the right trade, because the alternative is your afternoon.

Step 4: put your brand in a rules file

The highest-value trick is the simplest. Every agent runtime has a standing-instructions file (CLAUDE.md, Cursor rules, Copilot instructions). Put your visual system in it once:

When generating images with the html2img MCP server:
- Canvas 1200x630 for OG images, 1080x1080 for Instagram
- Fonts: Inter for UI, weights 500 and 800 only
- Background #0B1220, text #FFFFFF, muted #94A3B8, accent #10B981
- Embed any image as a base64 data URI, never a remote URL
- Complete, self-contained HTML with styles in one <style> block

Every image the agent produces from then on is on-brand without restating anything. The data URI rule is technical as well as stylistic: the renderer skips remote <img> sources by design, so assets go inline. Google Fonts are the exception and load server-side, which is why the @import above just works.

When not to use MCP

MCP and the REST API are the same engine, so the question is only who calls it. A person or agent in the loop, designing assets or screenshotting pages mid-task: MCP. Your application rendering an OG image per post at build time or an invoice per order: the REST API, because pipelines want code paths, not conversations.

They compose well. Design the template in a chat, iterate until the render is right, then lift the final HTML into your codebase and call the API with real data. The MCP session is the design phase, the API call is production.

We eat this cooking ourselves: every cover image on the HTML to Image blog is produced by an agent that writes the HTML, renders it, inspects the preview and fixes its own mistakes before anything ships. The full guide covers the remaining clients, the complete tool parameters and the PDF output mode.

Have you wired image rendering into your agent setup, and what did you have it build first? Share it in the comments.

Generating 10,000 certificates from one HTML template

Accreditly — Mon, 03 Aug 2026 20:55:31 +0000

The day your first cohort completes a course is the day certificates stop being a design job and become an engineering problem. One certificate is a Canva export. Ten thousand is a rendering pipeline with a database table, a queue and a verification page.

This post walks through the three ways teams actually build that pipeline, with working Python for each, then covers the two parts most certificate tutorials skip: batching at volume and verification. It is a condensed version of our full guide, How to generate signed digital certificates at scale, which also covers storage, retention and revocation.

One scope note up front. Most platform certificates do not need cryptographic signing in the PKI sense. The trust model that 95% of platforms ship is simpler: a unique ID printed on the certificate resolves to a verification page on the issuer's domain. An employer types the ID, the page confirms it. That is the model this post builds. If you need true PKI signing for regulated credentials, the stack is different (Adobe Sign, DocuSign, in-house HSM workflows) and this post is not it.

What every certificate needs

Whichever approach you pick, the output is the same:

Component	Detail
Layout	Landscape A4, 2480x1754 at 200 DPI for print
Personal	Recipient name with full Unicode support
Course	Course title and completion date
Issuer	Issuer name plus a signature image
ID	Unique certificate ID (UUID or short slug)
Verify	A URL under the ID pointing to your `/verify` route

The signature image communicates authority but provides zero tamper resistance. The certificate ID plus the verification page is the practical trust layer. Keep both in mind as you read the code.

The three approaches at a glance

Approach	Setup	Render time	Maintenance
PDF library (ReportLab, PDFKit)	1 day	200 to 400 ms	Fonts, layout drift, library updates
HTML plus headless Chrome	2 hours	1 to 3 sec	Chromium, memory, queue workers
Template API	5 minutes	1 to 2 sec	None

Approach 1: a PDF library

Python with ReportLab is the canonical first attempt. The output is a real PDF, text-searchable and around 30 KB per certificate, and you have absolute control.

import io
from uuid import uuid4
from reportlab.lib.pagesizes import landscape, A4
from reportlab.lib.colors import HexColor
from reportlab.pdfgen import canvas
from reportlab.lib.utils import ImageReader

def generate(recipient, course, completion_date,
             issuer, signature_path, accent='#0F766E'):
    width, height = landscape(A4)
    cert_id = uuid4().hex[:12]

    buffer = io.BytesIO()
    c = canvas.Canvas(buffer, pagesize=landscape(A4))

    c.setFillColor(HexColor(accent))
    c.rect(0, height - 80, width, 80, fill=1, stroke=0)
    c.setFillColor(HexColor('#FFFFFF'))
    c.setFont('Helvetica-Bold', 28)
    c.drawCentredString(width / 2, height - 55, 'Certificate of Completion')

    c.setFillColor(HexColor('#1F2937'))
    c.setFont('Helvetica-Bold', 36)
    c.drawCentredString(width / 2, height - 240, recipient)
    c.setFont('Helvetica-Bold', 22)
    c.drawCentredString(width / 2, height - 340, course)
    c.setFont('Helvetica', 14)
    c.drawCentredString(width / 2, height - 380, f'on {completion_date}')

    sig = ImageReader(signature_path)
    c.drawImage(sig, width / 2 - 80, 120, width=160, height=60,
                preserveAspectRatio=True, mask='auto')
    c.setFont('Helvetica', 9)
    c.drawString(40, 30, f'Certificate ID: {cert_id}')
    c.drawRightString(width - 40, 30,
                      f'Verify at northwindstudio.com/verify/{cert_id}')

    c.save()
    return buffer.getvalue()

That runs. But once you add Unicode font registration (default Helvetica only covers Latin Extended, so "Müller" and "Çelik" need a registered font), signature scaling and line wrapping for long course titles, you are at roughly 250 lines. Layout drift creeps in with every design change, because every element is a coordinate calculation. The output also looks like a 2008 PDF unless you put real design effort in.

Pick this when you need low-level PDF control, your design barely changes and someone on the team is comfortable living in PDF coordinate space.

Approach 2: an HTML template plus headless Chrome

If your team thinks in HTML and CSS rather than PDF coordinates, this is the natural next step. The certificate becomes the same Jinja, Blade or EJS template you would use for any other branded output, and you iterate on it in a normal browser before pointing Playwright at it.

from playwright.sync_api import sync_playwright
from jinja2 import Environment, FileSystemLoader

env = Environment(loader=FileSystemLoader('templates'))
template = env.get_template('certificate.html')

def generate(recipient, course, completion_date, issuer,
             signature_url, cert_id, accent='#0F766E'):
    html = template.render(
        recipient=recipient, course=course,
        completion_date=completion_date, issuer=issuer,
        signature_url=signature_url, cert_id=cert_id, accent=accent,
    )

    with sync_playwright() as p:
        browser = p.chromium.launch()
        page = browser.new_page(viewport={'width': 2480, 'height': 1754})
        page.set_content(html, wait_until='networkidle')
        png = page.screenshot(full_page=False)
        browser.close()
    return png

The template stays under 60 lines of HTML and CSS. Real fonts via Google Fonts, Flexbox for positioning, a background colour for the accent band.

The honest cost is the same as any headless Chrome workflow: Chromium on every worker, 200 to 400 MB resident per instance, and cold starts of 3 to 5 seconds on serverless. Batching 8,000 certificates a month on a t3.small will OOM. Under 1,000 a month on infrastructure you already run, this is the right pick. Above that, the render infrastructure starts costing more attention than it saves.

Approach 3: a template API

The lowest-setup path is to send the data to a hosted template and get an image back. The certificate-of-completion template accepts the fields an LMS has to hand and returns a print-ready 2480x1754 PNG, or a PDF when you set format to pdf.

import os
import requests

def generate(recipient, course, completion_date, issuer,
             signature_url, cert_id, accent='#0F766E'):
    response = requests.post(
        'https://app.html2img.com/api/v1/templates/certificate-of-completion',
        headers={'X-API-Key': os.environ['HTML_TO_IMAGE_KEY']},
        json={
            'recipient_name': recipient,
            'course_name': course,
            'completion_date': completion_date,
            'issuer_name': issuer,
            'issuer_signature_url': signature_url,
            'certificate_id': cert_id,
            'accent_color': accent,
        },
        timeout=15,
    )
    response.raise_for_status()
    return response.json()['url']

No Chromium, no fonts, no workers. The trade is a credit per render, so run the maths against your real volume: a platform issuing 200 certificates a week (10,400 a year) sits comfortably inside a $60 a month plan, and a $25 plan covers 3,000 renders a month.

Batching 10,000

Here is where the title's number earns its place. A cohort completing together looks like this:

from uuid import uuid4
from datetime import datetime

def issue_cohort(cohort_id, course_name, completion_date, signature_url):
    students = db.query(Enrollment).filter_by(
        cohort_id=cohort_id, completed=True
    ).all()

    for student in students:
        cert_id = uuid4().hex[:12]
        url = generate(
            recipient=student.full_name,
            course=course_name,
            completion_date=completion_date,
            issuer='Northwind Studio',
            signature_url=signature_url,
            cert_id=cert_id,
        )
        db.session.add(Certificate(
            student_id=student.id,
            certificate_id=cert_id,
            image_url=url,
            issued_at=datetime.utcnow(),
        ))
    db.session.commit()

That loop is fine for a hundred students. At 1 to 2 seconds per render, 10,000 certificates issued serially take three to five hours, and your worker hangs on every request. The fix is to stop waiting. Pass a webhook URL instead and let the renders come back to you:

response = requests.post(
    'https://app.html2img.com/api/v1/templates/certificate-of-completion',
    headers={'X-API-Key': os.environ['HTML_TO_IMAGE_KEY']},
    json={
        'recipient_name': recipient,
        'course_name': course,
        'completion_date': completion_date,
        'issuer_name': issuer,
        'issuer_signature_url': signature_url,
        'certificate_id': cert_id,
        'webhook_url': f'https://northwindstudio.com/webhooks/cert/{cert_id}',
    },
)

The dispatch loop now takes minutes, and the webhook handler updates each Certificate row with the rendered URL as it lands. The same pattern applies to Approach 2 if you push renders onto a queue: fire the jobs, collect results asynchronously, never block issuance on rendering.

Two batching rules regardless of approach. Generate the certificate ID at dispatch time, not render time, so a retried render is idempotent and never mints a duplicate. And store the image URL in the database rather than the bytes, backing it up to your own S3 bucket if you have multi-year retention requirements.

The verification page

This is the part every certificate tutorial skips, and it is the part that makes the certificate worth anything. A printed ID without a resolver is just a number. The trust anchor is the page on your domain:

from flask import Flask, render_template, abort

app = Flask(__name__)

@app.route('/verify/<cert_id>')
def verify(cert_id):
    cert = db.query(Certificate).filter_by(
        certificate_id=cert_id
    ).first()
    if not cert:
        abort(404)

    return render_template(
        'verify.html',
        recipient=cert.student.full_name,
        course=cert.course_name,
        issued_at=cert.issued_at,
        image_url=cert.image_url,
    )

The page shows the recipient, the course, the issue date and the certificate image itself. The certificate links here via the printed URL, the page confirms the certificate. The loop closes.

Three design notes from running this in production:

Use UUIDs or 12-character hex for the ID, never auto-increment integers. Sequential IDs leak your issuance volume to anyone holding two certificates.
Serve a plain 404 for revoked certificates, not a "this was revoked" page. An employer hitting a 404 will contact you directly, which is exactly what you want in the rare revocation case.
Let the verify pages be indexed. They are your trust anchor and you want search engines to know they exist.

Picking one

Under 1,000 certificates a month on infrastructure you already maintain, headless Chrome is fine. If you need embedded PDF metadata and your design is frozen, ReportLab earns its 250 lines. In the 100 to 10,000 a month band, or if you would rather spend engineering time on the learning platform than on render infrastructure, the template API is the sensible default, and there is a free tier to test it on a small cohort first.

The full guide, including storage, retention, diacritics handling and adding a QR code to the verify flow, is over on HTML to Image.

How are you issuing certificates on your platform, and has the verification side ever come up with employers? Share your setup in the comments.

Practical Uses for CSS :has() Now That It Works Everywhere

Accreditly — Sun, 02 Aug 2026 14:00:00 +0000

For about twenty years the answer to "how do I style a parent based on its children?" was "you can't, use JavaScript". Then :has() arrived, and it has now been supported in every major browser for long enough that you can use it without a second thought. The interesting question is no longer whether you can use it, but what it is actually good for. Here are the patterns I keep reaching for.

Style the wrapper, not just the input

Form fields are usually an input wrapped in a container with a label, a hint and an error slot. Before :has(), styling that container based on the input's state meant toggling classes with JavaScript. Now it is one selector:

.field:has(input:focus-visible) {
  outline: 2px solid #2563eb;
  outline-offset: 2px;
}

.field:has(input:user-invalid) {
  border-color: #dc2626;
}

.field:has(input:user-invalid) .hint {
  color: #dc2626;
}

Note :user-invalid rather than :invalid. Plain :invalid matches a required field the moment the page loads, before anyone has typed anything, so your form opens in a wall of red. :user-invalid only matches after the user has interacted with the field, which is what you actually wanted all along.

Cards that adapt to their own content

A card grid where some cards have images and some do not usually ends up with a .card--has-image modifier class that someone has to remember to apply. The card can just check for itself:

.card {
  padding: 1.5rem;
}

.card:has(> img) {
  padding: 0;
}

.card:has(> img) .card-body {
  padding: 1.5rem;
}

The CMS or the component can stop caring. If an editor adds an image, the layout adjusts. If they remove it, the padding comes back.

Styling the previous sibling

CSS has always been able to style the next sibling with +, but never the previous one. :has() fixes that through a small trick: select the element whose next sibling is hovered.

li:hover {
  transform: scale(1.05);
}

li:has(+ li:hover) {
  transform: scale(1.02);
}

The hovered item grows, and the item before it grows slightly too. You get the smooth dock-style ripple effect that previously needed a JavaScript mouseover handler.

Page-level state without JavaScript

Because :has() can sit on body or html, a checkbox anywhere in the document can drive layout anywhere else:

body:has(#menu-toggle:checked) {
  overflow: hidden;
}

body:has(#menu-toggle:checked) .drawer {
  translate: 0;
}

A hamburger menu that locks page scroll and slides a drawer in, with the checkbox hack doing the state management and zero script. For anything more complex than a toggle you will still want JavaScript, but for a mobile nav this is genuinely all it takes.

Quantity queries

:has() can ask how many children an element contains, which is brilliant for layouts that should change shape as content grows:

ul:has(> li:nth-child(6)) {
  columns: 2;
}

Read it as: if this list contains a sixth item, split into two columns. The same idea handles galleries that switch grid density once they pass a threshold, or a tag list that shrinks its font when it gets crowded. No resize observers, no counting nodes in script.

The gotchas

Three things to know before you sprinkle this everywhere.

First, specificity. :has() takes the specificity of the most specific selector in its argument list, so .card:has(#featured) carries id-level weight and will win fights you did not expect it to.

Second, you cannot nest :has() inside :has(). The browser will drop the rule.

Third, unlike :is() and :where(), the selector list inside :has() is not forgiving. One invalid or unsupported selector in the list invalidates the whole rule, so keep experimental selectors out of shared argument lists.

Performance-wise, browsers have done serious optimisation work here. Sensible, qualified selectors are fine in production. Just avoid pathological things like div:has(*) on enormous documents.

Recap

:has() turns a pile of state-management JavaScript into declarative CSS: form field states, content-aware cards, previous-sibling effects, page-level toggles and quantity queries. Combined with :user-invalid it also quietly fixes how form validation feels.

What have you replaced JavaScript with since :has() landed? Share your favourite pattern in the comments below.

How to Find and Fix N+1 Queries in Laravel

Accreditly — Fri, 31 Jul 2026 14:00:00 +0000

An N+1 problem rarely shows itself in development. Your local database has five rows, the page renders instantly and the query log looks harmless. Production has five thousand rows, and the same page now runs five thousand and one queries. Laravel makes this bug easy to write, but it also gives you everything you need to catch it early and fix it for good.

What an N+1 actually looks like

Here is the classic version:

$posts = Post::all();

foreach ($posts as $post) {
    echo $post->author->name;
}

One query fetches the posts. Then every pass through the loop triggers another query, because author is a lazy-loaded relationship and nothing has loaded it yet. Ten posts means eleven queries. A thousand posts means a thousand and one.

The nasty part is that nothing is visibly broken. The page renders, the data is correct and the only symptom is response time creeping up as the table grows. That is why these bugs ship: they pass code review and they pass QA.

Make Laravel shout about it

Laravel can throw an exception the moment a lazy load happens, and you should turn that on today:

// app/Providers/AppServiceProvider.php

use Illuminate\Database\Eloquent\Model;

public function boot(): void
{
    Model::preventLazyLoading(! $this->app->isProduction());
}

With this enabled, the loop above throws a LazyLoadingViolationException naming the model and the relationship, instead of quietly running an extra query. The ! $this->app->isProduction() guard means local and staging environments fail loudly while production carries on serving pages.

If you want production visibility without production exceptions, log the violations instead:

Model::handleLazyLoadingViolationUsing(function ($model, $relation) {
    logger()->warning("Lazy load of {$relation} on " . get_class($model));
});

There is also Model::shouldBeStrict(), which enables this check plus protection against silently discarded attributes and access to missing attributes. Worth a look once lazy loading is under control.

Fix it with eager loading

The fix is almost always with():

$posts = Post::with('author')->get();

Two queries total, regardless of row count: one for the posts, one whereIn for all the authors. The loop from earlier now touches memory, not the database.

Relationships nest with dot syntax, and you can load several at once:

$posts = Post::with(['author.profile', 'comments'])->get();

You can also trim the columns you pull back, as long as you include the keys the relationship needs to match on:

$posts = Post::with('author:id,name')->get();

Leave out id there and the relationship silently returns null, which is a fun afternoon of debugging you can skip.

Counts without loading anything

A common false fix is eager loading an entire relationship just to count it. If the page only shows "42 comments", use withCount():

$posts = Post::withCount('comments')->get();

foreach ($posts as $post) {
    echo $post->comments_count;
}

One extra subquery, no comment models hydrated, and your memory usage stays flat.

When the models are already loaded

Sometimes the collection arrives from code you do not control and the queries have already run. Lazy eager loading covers that:

$posts->load('author');

Same two-query outcome, just performed after the fact. Handy inside a controller that receives models from a package or a route binding.

Pin the query count in a test

Fixing an N+1 once is good. Stopping it coming back is better. Laravel's test suite can assert exactly how many queries an endpoint runs:

public function test_post_index_runs_a_fixed_number_of_queries(): void
{
    Post::factory()
        ->count(50)
        ->for(User::factory(), 'author')
        ->create();

    $this->expectsDatabaseQueryCount(3);

    $this->get('/posts')->assertOk();
}

Run it once to find the real number for your endpoint, then pin it. The exact figure does not matter much. What matters is that it stays constant whether the factory creates 50 rows or 500, and that the test fails the moment someone reintroduces a lazy load inside a loop.

Recap

In this tutorial you've seen how N+1 queries happen, how Model::preventLazyLoading() turns them into loud failures during development, and how with(), withCount() and load() fix them properly. The combination of strict mode locally and a pinned query count in your test suite means the next N+1 gets caught before it ever reaches a customer.

Do you run lazy loading prevention in production too, or only in development? Share your setup in the comments below.

How to Control Page Breaks in HTML to PDF Output

Accreditly — Sat, 25 Jul 2026 14:54:41 +0000

You render an invoice that looks right in the browser, open the PDF and find line item 14 cut in half by a page boundary. The description sits at the foot of page one and the amount sits at the top of page two. Or a certificate splits down the middle. Or a section heading is stranded alone at the bottom of a page while its content starts overleaf.

Chrome is doing exactly what it was asked to do: fill a page, start another, repeat. It has no opinion about which parts of your document belong together. You supply that opinion in CSS, and it takes about six lines. This post originally appeared on the HTML to Image blog as How to control page breaks in HTML to PDF output.

Everything here applies to any Chrome based pipeline: Puppeteer's page.pdf(), Playwright, or a rendering API. The properties are standard CSS, not vendor extensions.

The three properties that do the work

There is no avoid_splitting_rows flag on any HTML to PDF tool worth using, because the renderer is a browser and browsers already have a standard for this. CSS Fragmentation gives you three properties:

Property	What it does	Values you will actually use
`break-inside`	Controls splitting within an element	`avoid`, `auto`
`break-before`	Forces or prevents a break before an element	`page`, `avoid`, `auto`
`break-after`	Forces or prevents a break after an element	`page`, `avoid`, `auto`

The older page-break-inside, page-break-before and page-break-after still work. The spec defines them as legacy aliases and Chrome maps them onto the modern equivalents, so an existing stylesheet does not need rewriting. New code should use the short forms.

These properties do nothing on screen. Continuous media has no page boundaries to avoid, so the browser computes them and moves on. They only mean something once the content is being cut into pages.

Put them in your normal stylesheet, not in @media print

This is the bit that catches people out.

A rule hidden inside @media print only fires if the renderer is actually emulating print media. Puppeteer's page.pdf() does emulate print, so @media print blocks apply there. Plenty of rendering APIs do not, including the one I use, which renders PDFs with your screen CSS so the PDF matches the PNG of the same input.

The fragmentation properties do not care either way. They are ordinary declarations that sit in the cascade like any other, get ignored on continuous media, and take effect when the document paginates. So write them unconditionally:

/* Applied when the document paginates. Inert in the browser. */
.invoice-row,
.line-items tr,
.card,
figure {
  break-inside: avoid;
}

Nothing about the page changes in a browser tab. Here is what it buys you in the PDF: six 300px cards with no rules at all fill each page to the edge and split whichever card straddles the boundary. Add break-inside: avoid to .card and the renderer fits three per page, leaves the leftover space at the foot of the page and starts card four cleanly on the next one.

Keeping an invoice together

Line items are the classic failure. A row that splits is not just ugly, it is a document where a quantity and its price appear on different pages, which is the sort of thing an accounts department notices before it notices your typography.

.line-items tr {
  break-inside: avoid;
}

/* Never leave a heading alone at the foot of a page */
h2,
h3 {
  break-after: avoid;
}

/* Totals, payment terms and the signature block stay as one unit */
.totals,
.payment-terms,
.signature {
  break-inside: avoid;
}

break-after: avoid on headings is the quiet win. It tells the renderer that a heading may not be the last thing on a page, so if the following block will not fit, the heading travels with it. Two declarations remove an entire class of report that looks like it was assembled by accident.

Forcing a break where you want one

break-before: page starts a new page unconditionally. It is how you get one certificate per attendee, one statement per customer or one section per page out of a single render:

<style>
  .sheet { break-before: page; }
  .sheet:first-child { break-before: auto; }
</style>

<div class="sheet">…certificate for Priya…</div>
<div class="sheet">…certificate for Tom…</div>
<div class="sheet">…certificate for Andreas…</div>

The :first-child reset matters. Without it the first sheet forces a break before itself and you ship a PDF with a blank first page. I have seen that one survive into production more than once.

It also turns a batch job into a single render. One request that returns a 40 page document beats 40 requests, and every page is still real vector text rather than a picture of a certificate.

Do not assume table headers repeat

Chrome is supposed to redraw <thead> at the top of every page a table spans. Test that assumption against your own pipeline before you rely on it. When I measured this on the renderer I use, the header appeared once at the start and every page after that carried bare rows.

The fix is to chunk in your template rather than hope in your CSS. Split the rows into page sized groups and give each group its own table:

const PER_PAGE = 24;

const chunks = [];
for (let i = 0; i < rows.length; i += PER_PAGE) {
  chunks.push(rows.slice(i, i + PER_PAGE));
}

const html = chunks.map((chunk, index) => `
  <table class="ledger${index > 0 ? ' continued' : ''}">
    <thead>
      <tr><th>Date</th><th>Reference</th><th>Description</th><th>Amount</th></tr>
    </thead>
    <tbody>
      ${chunk.map(r => `
        <tr>
          <td>${r.date}</td><td>${r.ref}</td><td>${r.description}</td><td>${r.amount}</td>
        </tr>`).join('')}
    </tbody>
  </table>
`).join('');

.ledger.continued {
  break-before: page;
}

.ledger tr {
  break-inside: avoid;
}

You now control exactly where the table breaks, every page carries its own header, and you can label the continued ones. Pick PER_PAGE by rendering once and counting, then leave it alone.

Running footers with fixed positioning

Chrome repeats fixed position elements on every page of a printed document, which gives you a running footer without the @page margin box machinery that browsers never implemented:

.doc-footer {
  position: fixed;
  bottom: 0;
  left: 0;
  right: 0;
  padding: 12px 24px;
  border-top: 1px solid #e2e8f0;
  font-size: 12px;
  color: #64748b;
}

/* Reserve the space so content never slides under it */
body {
  padding-bottom: 64px;
}

That covers a company registration number, a document reference or a confidentiality line on every page.

What you cannot get this way is a page number. Page counters live in @page margin boxes, which Chrome has never supported, so content: counter(page) renders nothing. Number the sheets yourself in the template where you already know how many there are, or reach for a print focused engine like Paged.js or a dedicated PDF service.

Flex and grid children fragment fine now

There is an old reflex that says flexbox and grid children ignore break-inside, so people rewrite a working card layout in floats or tables before generating a PDF. That reflex is out of date. Modern Chrome fragments both properly, and a column of flex children or grid items with break-inside: avoid paginates the same way block elements do: the item that will not fit moves to the next page whole.

I tested this rather than trusting my memory of it, and so should you, because the answer changed somewhere around the LayoutNG work and most of the advice online predates that.

The starter stylesheet

Drop this into any document you intend to render as a PDF and most pagination complaints disappear before anyone files them:

tr,
figure,
blockquote,
.card,
.totals,
.signature {
  break-inside: avoid;
}

h1, h2, h3, h4 {
  break-after: avoid;
}

.sheet {
  break-before: page;
}

.sheet:first-child {
  break-before: auto;
}

Then render the real document, not a sample of three rows, and look at every page boundary. Pagination bugs only appear at length, which is why they tend to ship.

The full version of this post, including the notes on page size and what happens to content wider than the page, is on the HTML to Image blog: How to control page breaks in HTML to PDF output.

What is your worst PDF pagination bug? Mine is still the blank first page that nobody noticed for two months. Share yours in the comments.

Add "Export as image" to any dashboard

Accreditly — Thu, 23 Jul 2026 14:00:00 +0000

First published on the Accreditly blog.

"Export as image" is one of those features users expect and developers keep putting off. Someone wants to drop a chart into a slide deck or paste a KPI panel into Slack, and right now they screenshot it themselves and crop it badly. Adding a proper export button is less work than it looks, as long as you do not try to rasterise the DOM in the browser. The reliable approach is to render the panel server-side through an image API and hand back a clean PNG. This article adds an export button to a dashboard and wires up the backend that produces the image.

Why not just screenshot the DOM in the browser

Client-side approaches like html2canvas re-implement a browser's rendering inside the browser, and they break on the things dashboards are made of: web fonts, cross-origin images, SVG charts, CSS you did not write yourself. The output rarely matches what is on screen. Rendering server-side in a real browser engine sidesteps all of it. You send the markup or a URL, a genuine Chromium renders it, and you get a pixel-accurate PNG. Here we use the HTML to Image API from a small Node backend.

There are two ways in. If the panel can be rebuilt from data, render a standalone HTML version of it on the server. If the dashboard page is reachable by the API, point it at the URL and capture just the panel with a CSS selector. We will do the first, then show the second.

Step 1: The export button

On the front end, an export button calls your backend, receives the image bytes, and triggers a download. No canvas, no rendering library.

async function exportPanel(panelId) {
  const res = await fetch(`/api/export/${panelId}`, { method: 'POST' });
  if (!res.ok) {
    alert('Export failed');
    return;
  }

  const blob = await res.blob();
  const link = document.createElement('a');
  link.href = URL.createObjectURL(blob);
  link.download = `${panelId}.png`;
  link.click();
  URL.revokeObjectURL(link.href);
}

document.querySelectorAll('[data-export]').forEach((button) => {
  button.addEventListener('click', () => exportPanel(button.dataset.export));
});

Any element with data-export="revenue" becomes an export trigger. The browser's only job is to ask for the file and save it.

Step 2: Render the panel on the server

The backend rebuilds the panel as a self-contained HTML document from the same data the dashboard uses, posts it to the render endpoint, and streams the PNG back. Inlining the styles keeps the render independent of your app's CSS bundle.

import express from 'express';
const app = express();

function panelHtml(panel) {
  return `
    <div style="width:1000px;padding:48px;font-family:Arial,sans-serif;background:#fff;">
      <h2 style="margin:0 0 8px;font-size:28px;">${panel.title}</h2>
      <p style="margin:0 0 24px;color:#6b7280;">${panel.subtitle}</p>
      <div style="font-size:72px;font-weight:bold;color:#4f46e5;">${panel.value}</div>
    </div>`;
}

app.post('/api/export/:id', async (req, res) => {
  const panel = await loadPanel(req.params.id); // your data layer

  const render = await fetch('https://app.html2img.com/api/html', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.HTML2IMG_API_KEY,
    },
    body: JSON.stringify({ html: panelHtml(panel), width: 1000, height: 600 }),
  });

  const { url } = await render.json();
  const image = Buffer.from(await (await fetch(url)).arrayBuffer());

  res.set('Content-Type', 'image/png');
  res.send(image);
});

Because the server holds the data, the export is deterministic. The same panel produces the same image whether the user is on a phone or a 4K monitor, which is not true of a browser screenshot.

Step 3: Capturing a live panel by selector

If your dashboard is reachable by the API, for example a public status board or a page behind a signed URL, you can skip rebuilding the HTML and capture the real element instead. Point the screenshot endpoint at the page and pass a CSS selector for the panel you want. The API waits for that element, then crops the image to its bounds.

app.post('/api/export-live/:id', async (req, res) => {
  const render = await fetch('https://app.html2img.com/api/screenshot', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.HTML2IMG_API_KEY,
    },
    body: JSON.stringify({
      url: `https://dashboard.example.com/board?token=${process.env.BOARD_TOKEN}`,
      selector: `#panel-${req.params.id}`,
    }),
  });

  const { url } = await render.json();
  const image = Buffer.from(await (await fetch(url)).arrayBuffer());
  res.set('Content-Type', 'image/png').send(image);
});

The selector approach is the quickest when the rendered panel already looks right and you just need it as a file. The rebuild approach gives you more control, since the export can differ from the on-screen version, add a title block, or strip interactive chrome that makes no sense in a static image.

Polishing it

A couple of touches make this feel finished. Show a brief loading state on the button while the request is in flight, because a render takes a second or two. And cache the generated image keyed by the panel and its last-updated time, so exporting the same unchanged panel twice does not render twice.

That is a complete export feature: a button on the front end, a backend route that renders the panel in a real browser, and a clean PNG that matches what the user sees. Your users stop cropping screenshots, and "export this" becomes a one-click answer instead of a backlog item.

How to Generate Verifiable PDF Certificates in Laravel

Accreditly — Tue, 21 Jul 2026 18:20:19 +0000

When a learner finishes a course they want a certificate that behaves like a document: something they can print at full quality, attach to a job application and that an employer can check is genuine. In this tutorial you'll build exactly that in Laravel: a Blade-designed certificate rendered as a vector PDF, with a QR code that resolves to a verification page and an email that delivers it automatically. This post originally appeared on Accreditly as How to generate verifiable PDF certificates in Laravel.

Keep the design in Blade

The certificate is an ordinary Blade view. Everything lives in one file, styles inline, so the markup you preview in the browser is exactly what gets rendered. If you want a designed starting point rather than a blank page, the certificate of completion template is a good base to adapt.

{{-- resources/views/certificates/template.blade.php --}}
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<style>
  body { font-family: Georgia, serif; color: #1a2233; margin: 0; }
  .certificate { padding: 60px; border: 6px double #b28a2f; margin: 24px; text-align: center; }
  .heading { font-size: 15px; letter-spacing: 4px; text-transform: uppercase; color: #b28a2f; }
  h1 { font-size: 44px; margin: 24px 0 8px; }
  .course { font-size: 22px; margin: 4px 0 28px; }
  .issued { font-size: 15px; color: #5a6478; }
  .qr { margin-top: 36px; }
  .verify-url { font-size: 12px; color: #5a6478; }
</style>
</head>
<body>
  <div class="certificate">
    <p class="heading">Certificate of Completion</p>
    <h1>{{ $certificate->user->name }}</h1>
    <p class="course">has completed {{ $certificate->course }}</p>
    <p class="issued">Issued {{ $certificate->issued_at->format('j F Y') }}</p>

    <div class="qr">
      {!! QrCode::size(110)->generate(route('certificates.verify', $certificate)) !!}
    </div>
    <p class="verify-url">{{ route('certificates.verify', $certificate) }}</p>
  </div>
</body>
</html>

Two things are doing quiet work here. The design flows like a document rather than being pinned to fixed pixel dimensions, because the PDF renders onto A4 portrait pages. And the QR code is generated as inline SVG, so the renderer has nothing external to fetch.

Give every certificate a verifiable identity

Verification only needs a stable public identifier and a page that resolves it. A UUID on the certificate row is enough.

Schema::create('certificates', function (Blueprint $table) {
    $table->id();
    $table->uuid('uuid')->unique();
    $table->foreignId('user_id')->constrained();
    $table->string('course');
    $table->timestamp('issued_at');
    $table->timestamps();
});

The verification route binds on the UUID, so guessing sequential ids gets nobody anywhere:

Route::get('/verify/{certificate:uuid}', function (Certificate $certificate) {
    return view('certificates.verify', ['certificate' => $certificate]);
})->name('certificates.verify');

The verify view shows the learner's name, the course and the issue date. Anyone scanning the QR code on a printed certificate lands on your domain and sees the record, which is the whole trust story: the paper claims it, your database confirms it.

For the QR code itself, pull in the standard package. The default renderer outputs SVG, which is what you want:

composer require simplesoftwareio/simple-qrcode

Render it as a vector PDF

You have three ways to turn that Blade view into a PDF. DomPDF is pure PHP but supports a narrow slice of CSS, and a certificate is exactly the kind of designed layout it mangles. Browsershot renders correctly because it drives real Chrome, but now you are installing and babysitting Chrome on your server. The third route is an HTML to PDF API: you POST the rendered HTML with format: "pdf" and get back a URL to a finished document, rendered by a browser engine you never have to operate.

The service is short:

namespace App\Services;

use App\Models\Certificate;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Storage;

class CertificateService
{
    public function issue(Certificate $certificate): string
    {
        $html = view('certificates.template', [
            'certificate' => $certificate,
        ])->render();

        $response = Http::withHeaders([
            'X-API-Key' => config('services.html2img.key'),
        ])->post('https://app.html2img.com/api/html', [
            'html' => $html,
            'format' => 'pdf',
        ])->throw()->json();

        $path = "certificates/{$certificate->uuid}.pdf";
        Storage::put($path, Http::get($response['url'])->body());

        return $path;
    }
}

Add the key to config/services.php so it stays out of the codebase:

'html2img' => [
    'key' => env('HTML2IMG_API_KEY'),
],

The returned file is a real vector PDF. Text stays selectable and searchable, fonts are embedded and it prints sharp at any size, which is precisely what a certificate needs and what a PNG cannot give you. The page renders with your normal screen CSS, so there is no separate print stylesheet to maintain.

Email it to the learner

Store the PDF once, then attach it from storage in a mailable:

namespace App\Mail;

use App\Models\Certificate;
use Illuminate\Mail\Mailable;
use Illuminate\Mail\Mailables\Attachment;
use Illuminate\Mail\Mailables\Content;
use Illuminate\Mail\Mailables\Envelope;

class CertificateIssued extends Mailable
{
    public function __construct(public Certificate $certificate)
    {
    }

    public function envelope(): Envelope
    {
        return new Envelope(
            subject: 'Your certificate for '.$this->certificate->course,
        );
    }

    public function content(): Content
    {
        return new Content(markdown: 'emails.certificate-issued');
    }

    public function attachments(): array
    {
        return [
            Attachment::fromStorage("certificates/{$this->certificate->uuid}.pdf")
                ->as('certificate.pdf')
                ->withMime('application/pdf'),
        ];
    }
}

Wire it to course completion

Issue and deliver in the listener for whatever event marks a course as finished:

public function handle(CourseCompleted $event): void
{
    $certificate = Certificate::create([
        'uuid' => (string) Str::uuid(),
        'user_id' => $event->user->id,
        'course' => $event->course->title,
        'issued_at' => now(),
    ]);

    app(CertificateService::class)->issue($certificate);

    Mail::to($event->user)->send(new CertificateIssued($certificate));
}

Push the listener onto a queue and the learner has a verifiable document in their inbox seconds after finishing, with no one on your team touching anything.

Batches and tamper evidence

Two upgrades when volume grows. For bulk issuing, historic cohorts or end-of-term runs, pass a webhook_url with each request and collect the PDFs as they finish instead of holding connections open for the whole batch. And if verification needs to survive scrutiny beyond a database lookup, content hashes and signed identifiers make the document itself tamper-evident; the approach is covered in how to generate signed digital certificates at scale.

In this tutorial you've designed a certificate in Blade, rendered it as a vector PDF, given it a QR verification link and delivered it by email on course completion. The full version, including the fixed-width scaling notes and the Open Badges pairing, lives on Accreditly.

How are you issuing certificates in your Laravel apps at the moment? Share your approach in the comments below.

WeasyPrint Alternative: HTML to PDF in Python (When You Need JavaScript)

Accreditly — Tue, 21 Jul 2026 17:53:30 +0000

You build a report template in HTML. It looks right in the browser: the layout holds, the webfont loads, the Chart.js graph draws. Then you run it through WeasyPrint and the PDF comes back with a blank space where the chart should be. No exception, no warning, just a hole in the page.

That is not a bug you can fix. WeasyPrint does not execute JavaScript, so anything drawn or injected client-side simply does not exist as far as its renderer is concerned. This post walks through where the Python PDF stack falls short and the API route around it; it originally appeared on the HTML to Image blog as WeasyPrint Alternative: HTML to PDF in Python.

Where WeasyPrint stops

WeasyPrint has earned its popularity. It is pure Python, it takes CSS paged media seriously and for static, document-shaped HTML it produces clean output. If your templates are plain markup with print styles, it does the job.

The problems start when your HTML behaves like the modern web:

No JavaScript at all. Chart.js, Alpine, anything rendered client-side, even a small <script> that swaps a date into the footer: none of it runs.
A layout engine that trails the browser. WeasyPrint implements its own CSS engine, so features like flexbox and grid arrived years behind Chrome and still carry edge cases. You end up maintaining a second, simpler stylesheet just for PDFs.
Native dependencies. WeasyPrint leans on Pango and HarfBuzz. On a full Ubuntu image that is an apt-get away. On Alpine, distroless or AWS Lambda it means custom layers, missing shared libraries and builds that break when the base image changes.

None of that is WeasyPrint doing anything wrong. It is the cost of reimplementing a rendering engine outside a browser.

The other Python options have the same shape

pdfkit wraps wkhtmltopdf, and wkhtmltopdf is archived and unmaintained, frozen on a Qt WebKit build that predates most of modern CSS. Flexbox is unreliable and grid does not exist. New projects should not adopt it in 2026.

xhtml2pdf builds on ReportLab and supports a small CSS subset. Fine for simple tables, out of its depth the moment a designer touches the template.

Running headless Chrome yourself, through Playwright or pyppeteer, renders correctly because it is a real browser. Now you operate a browser: hundreds of megabytes of Chromium in every image, cold starts measured in seconds, memory spikes, font packages and a patching schedule.

So the choice looks like this: correct rendering with heavy infrastructure, or light infrastructure with a rendering engine stuck years behind the browser.

Render the PDF with a browser engine you don't have to run

The HTML to PDF API gives you the first option without the operations. You POST your HTML with format: "pdf" and get back a URL to a finished document, rendered by a real browser engine:

import os

import requests

API_KEY = os.getenv('HTML2IMG_API_KEY')


def html_to_pdf(html: str, css: str = '') -> str:
    """Render HTML to a PDF and return the hosted URL."""
    response = requests.post(
        'https://app.html2img.com/api/html',
        json={'html': html, 'css': css, 'format': 'pdf'},
        headers={'X-API-Key': API_KEY},
        timeout=60,
    )
    response.raise_for_status()
    result = response.json()
    if not result.get('success'):
        raise RuntimeError(result.get('message', 'Render failed'))
    return result['url']

The response is small enough to read in full:

{
    "success": true,
    "id": "9d5f9b52-6b32-4a1c-a9c5-1f0b2a9e4c11",
    "credits_remaining": 499,
    "url": "https://i.html2img.com/image-1784019129398-416501.pdf"
}

The url points at a real vector PDF served as application/pdf. Text stays selectable and searchable, fonts are embedded (webfonts included) and background colours and gradients come through. Content lays out on A4 portrait pages and paginates automatically, so a three page report is no more work than a one page invoice.

One detail that saves you a refactor: the PDF renders with your normal screen CSS. You do not need @media print rules or a parallel print stylesheet. The markup that looks right in the browser is the markup that ships.

A worked example: an invoice from a Jinja2 template

Invoices are the classic job. Here is the whole flow, template to hosted PDF:

from jinja2 import Template

INVOICE = Template("""
<div class="invoice">
  <h1>Invoice #{{ number }}</h1>
  <p class="meta">Northgate Coffee Ltd &middot; Due {{ due }}</p>
  <table>
    <tr><th>Item</th><th>Qty</th><th>Price</th></tr>
    {% for line in lines %}
    <tr><td>{{ line.item }}</td><td>{{ line.qty }}</td><td>&pound;{{ line.price }}</td></tr>
    {% endfor %}
  </table>
  <p class="total">Total due: &pound;{{ total }}</p>
</div>
""")

CSS = """
body { font-family: Helvetica, Arial, sans-serif; color: #0e1521; }
.invoice { padding: 24px; }
table { width: 100%; border-collapse: collapse; margin-top: 16px; }
th, td { text-align: left; padding: 8px 4px; border-bottom: 1px solid #e2e6ec; }
.total { font-weight: 700; margin-top: 16px; }
"""

html = INVOICE.render(
    number=1042,
    due='20 August 2026',
    lines=[
        {'item': 'Espresso machine service', 'qty': 1, 'price': '180.00'},
        {'item': 'Filter papers (case)', 'qty': 4, 'price': '12.50'},
    ],
    total='230.00',
)

print(html_to_pdf(html, CSS))

In Flask you would build html with render_template, in Django with render_to_string. The API does not care which framework produced the markup.

Your charts render, because JavaScript runs

Back to that blank hole from the opening. JavaScript executes in the renderer, so Chart.js draws exactly as it does in the browser. Disable the entry animation so the canvas paints immediately, and give the page a short ms_delay so the script settles before capture:

chart_html = """
<canvas id="sales" width="640" height="280"></canvas>
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<script>
new Chart(document.getElementById('sales'), {
  type: 'bar',
  data: {
    labels: ['Mar', 'Apr', 'May', 'Jun'],
    datasets: [{ label: 'Orders', data: [412, 468, 530, 597] }]
  },
  options: { animation: false }
});
</script>
"""

response = requests.post(
    'https://app.html2img.com/api/html',
    json={'html': chart_html, 'format': 'pdf', 'ms_delay': 500},
    headers={'X-API-Key': API_KEY},
)

Turning a chart you already render in the browser into a document is one parameter.

What changes in your deployment

Your PDF dependency list becomes requests. No Pango, no HarfBuzz, no Chromium layer, no font packages. The same code runs identically on Alpine, in a distroless container and on Lambda, because the rendering happens on the API's browsers rather than your box. For async stacks there is an httpx version in the Python guide that fits FastAPI, and for big batch runs you can pass a webhook_url and collect the PDFs as they finish instead of holding connections open.

Two behaviours to know before you ship. Pages are A4 portrait and content reflows to the page width, so width, height, dpi, fullpage and selector are ignored in PDF mode; write markup that flows like a document, or pass scale_to_fit to scale a fixed-width design onto the page. And a PDF costs the same single credit as an image, so the pricing maths does not change.

When WeasyPrint is still the right call

If you need fine control over CSS paged media (running headers, counter(page) footers), if your PDFs must render fully offline, or if policy rules out external services, WeasyPrint remains the best pure Python option. For everything else the trade is simple: one HTTP call buys you a browser engine's rendering, working JavaScript and a deployment that no longer knows what Pango is.

In this post you've seen where WeasyPrint, pdfkit and xhtml2pdf stop, and how to get browser-accurate PDFs from Python with nothing installed beyond requests. The full guide, including the format parameter reference, lives on the HTML to Image blog.

What are you using for PDF generation in Python at the moment? Share your setup in the comments below.

Why HTML to PDF with Puppeteer Keeps Breaking on Serverless (and the Fix)

Accreditly — Fri, 17 Jul 2026 12:06:01 +0000

You wrote an HTML template for your invoices, wired up page.pdf(), ran it locally and got a clean A4 document in under a second. Then you deployed it to Lambda and got a 502. Or a blank first page. Or a PDF where every character is a hollow rectangle. Or it ran fine for three weeks until Chrome shipped a new major version and it stopped.

This is the standard trajectory for HTML to PDF on serverless, and it is not because you did anything wrong. PDF generation is the heaviest thing you can ask headless Chrome to do, and a serverless function is the most hostile place to run headless Chrome. This post originally appeared on the HTML to Image blog as Why HTML to PDF with Puppeteer keeps breaking on serverless, and it walks through the six ways the setup breaks, the fix for each, and the point at which the fixes stop being worth your time.

Why `page.pdf()` is heavier than a screenshot

A screenshot is a raster of whatever Chrome already painted. A PDF is a different rendering path entirely.

When you call page.pdf(), Chrome switches the page to print media, recomputes layout against a physical page size rather than your viewport, splits the content into pages, resolves every font it needs and embeds them into the document, then serialises text, borders, gradients and shapes as vectors. Only genuine raster content, your img tags and canvases, goes in as pixels.

That work costs more memory, more CPU and more wall-clock time than a screenshot of the same markup. A long report that screenshots in two seconds can take eight or ten to paginate into a document. Every constraint a serverless platform imposes, size, memory, execution time, gets hit harder by PDF work than by anything else you might run through Puppeteer.

Keep that in mind as we go through the failure modes. Each one exists for screenshots too. Each one bites sooner for PDFs.

Failure 1: the browser does not fit in the function

Lambda gives you 250MB of unzipped deployment package, layers included. A Chromium build alone eats most of that, which is why nobody ships stock Puppeteer to Lambda. The ecosystem answer used to be chrome-aws-lambda, which famously stopped receiving updates. Its successor is @sparticuz/chromium, which ships a compressed browser and decompresses a couple of hundred megabytes of it into /tmp on first launch.

The working setup looks like this:

import chromium from '@sparticuz/chromium';
import puppeteer from 'puppeteer-core';

export const handler = async (event) => {
  const browser = await puppeteer.launch({
    args: chromium.args,
    defaultViewport: chromium.defaultViewport,
    executablePath: await chromium.executablePath(),
    headless: 'shell',
  });

  const page = await browser.newPage();
  await page.setContent(event.html, { waitUntil: 'networkidle0' });

  const pdf = await page.pdf({
    format: 'A4',
    printBackground: true,
  });

  await browser.close();
  return { statusCode: 200, body: pdf.toString('base64'), isBase64Encoded: true };
};

It works, until it doesn't, because puppeteer-core and @sparticuz/chromium have to agree on a Chromium version. Chrome ships a new major roughly every four weeks, the package versions move in lockstep and a mismatch produces the fun class of bug where pages render differently, or the browser refuses to launch with an error that mentions none of this. Pin both versions, upgrade both together, and accept that this is now a recurring calendar event.

The escape hatch is a container image, which lifts the limit to 10GB. It also makes your cold starts worse, which brings us to failure 3. First, fonts.

Failure 2: the fonts are not there

The Amazon Linux image underneath Lambda ships with almost no fonts. Locally your PDF renders in whatever your OS provides. On Lambda, any glyph Chrome cannot resolve becomes tofu, the hollow rectangle. Emoji and CJK text are the classic casualties, but plenty of teams discover this through a customer's name.

Screenshots have this problem too. PDFs have it worse, for a nasty reason: the broken font gets embedded into the document. A screenshot with tofu is a bad image you regenerate. A PDF with tofu is a permanent artefact, and if your pipeline emails invoices automatically, it is a permanent artefact sitting in your customer's inbox.

The fix is to load every font you need explicitly. @sparticuz/chromium has a helper that fetches a font file into the environment before launch:

import chromium from '@sparticuz/chromium';

await chromium.font('https://cdn.your-app.com/fonts/Inter-Regular.ttf');
await chromium.font('https://cdn.your-app.com/fonts/NotoColorEmoji.ttf');

Or you declare @font-face in your CSS with absolute URLs and wait for the network to settle before printing. Either way, you now own a font manifest. Miss one, and you find out from a rendered document, not from a stack trace.

Failure 3: cold starts meet the 29 second ceiling

Booting headless Chrome inside a function takes two to four seconds on a good day. On a cold start the compressed binary has to be decompressed into /tmp first, so add a few more. Then the actual work starts, and PDF work is the slow kind: a multi-page report with webfonts can take another five to ten seconds to lay out and paginate.

Now stack the platform limits on top. API Gateway's default integration timeout is 29 seconds. A cold start plus a font fetch plus a long document does not always fit, and when it doesn't, the client gets a 504, retries and lands on another cold container. Under a burst of traffic, invoice runs at month end are the textbook case, the retries amplify the load and the whole endpoint browns out.

You can keep functions warm with scheduled pings or provisioned concurrency. Both work. Both are also a standing charge for a browser you are keeping alive to avoid paying its startup cost, which quietly deletes the economic argument for putting this on serverless in the first place.

Failure 4: memory spikes and zombie Chrome

Chrome's print pipeline holds the whole paginated document in memory while it serialises. Pages that render happily in a 1024MB function will occasionally spike far past it on a long table or a chart-heavy report, and Lambda's response to that is a kill, not a warning. You will see it as a function that "randomly" dies on roughly one render in fifty.

The subtler version is the zombie. Serverless containers are reused between invocations, and if your code throws after launch but before browser.close(), the Chrome process survives into the next invocation. Each leaked browser holds memory and file handles, /tmp still contains the decompressed binary and any scratch files, and after a few leaks the container is poisoned: launches fail with Protocol error: Target closed until the platform recycles it.

The defence is boring and mandatory:

let browser = null;
try {
  browser = await puppeteer.launch({ /* ... */ });
  const page = await browser.newPage();
  await page.setContent(html, { waitUntil: 'networkidle0' });
  return await page.pdf({ format: 'A4', printBackground: true });
} finally {
  if (browser) {
    await browser.close();
  }
}

Every code path, every error, every timeout has to end in browser.close(). One await you forgot to wrap is one poisoned container.

Failure 5: the print CSS you did not know you were writing

Even when everything launches and nothing leaks, the output surprises people, because page.pdf() does not render what you saw in your browser tab. It renders your page under print media, against defaults you probably have not read.

The ones that catch nearly everyone:

Backgrounds vanish. printBackground defaults to false, so your branded header ships as white space until you switch it on.
The paper is American. The default page size is Letter, not A4. If you are anywhere outside North America, every margin is subtly wrong until you pass format: 'A4' or set preferCSSPageSize: true and control it from CSS.
Your media query fires. Any @media print rules in your stylesheet, including a framework's, now apply. If you want the on-screen look, you need page.emulateMediaType('screen') and to know why you needed it.
Pagination cuts where it likes. Table rows split across page boundaries, headings get orphaned at the bottom of a page, and nothing tells you. You end up sprinkling break-inside: avoid through the stylesheet and writing @page rules you have never needed before:

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

.invoice-row,
.line-items tr {
  break-inside: avoid;
}

Lazy content is missing. Images below the fold that lazy-load on scroll never load, because nobody scrolled. Charts drawn on a timer render as empty boxes. You start adding waits and forced-load hacks per template.

None of these is hard on its own. Together they mean your PDF templates are a separate discipline from your web templates, tested against a rendering mode you cannot see in normal development, on a pinned browser version that differs from the Chrome on your laptop. "Works locally, wrong in production" stops being a bug and becomes the workflow.

Failure 6: some platforms cannot run Chrome at all

Everything above assumes you are on a platform where running a native binary is possible. Not all of them are.

Cloudflare Workers cannot execute a Chrome binary full stop. Cloudflare's answer is a managed Browser Rendering API with its own concurrency limits and pricing, which concedes the underlying point: the browser has to live somewhere else. Vercel and Netlify functions sit on the same class of infrastructure as Lambda and inherit the same size and execution ceilings under different labels.

So teams converge on the same design: a dedicated rendering service, sized for Chrome, that the rest of the system calls over HTTP. Which is a sensible architecture, and also an admission. You adopted serverless to stop running servers, and the PDF requirement quietly made you stand one up, with Chrome on it, that you now patch, monitor and scale.

The treadmill is the real cost

Add it up. A version matrix you re-pin every few weeks. A font manifest you maintain by hand. Cold-start budgets, memory headroom you cannot predict, cleanup code you cannot get wrong and a print stylesheet dialect your team learns one production surprise at a time.

None of it is your product. All of it recurs. This is the same conclusion the ecosystem keeps reaching from different directions: wkhtmltopdf froze on a 2012 rendering engine and was eventually archived, and its users are migrating off it years later. Laravel developers reach for DomPDF to avoid running a browser, then hit the wall of its CSS support the first time a template uses flexbox. The browser is the only engine that renders modern CSS correctly, and owning a browser in production is a part-time job.

The fix: move rendering off the function

The alternative is one HTTP request. You send the HTML, real Chrome runs somewhere that is built for it, and you get back a URL to a finished PDF:

curl -X POST https://app.html2img.com/api/html \
  -H 'X-API-Key: your-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "html": "<h1>Invoice #1042</h1><p>Due within 30 days.</p>",
    "css": "h1 { color: #4f46e5; }",
    "format": "pdf"
  }'

That format parameter is the whole migration. The HTML to PDF API is the same API HTML to Image uses for images, with "format": "pdf" switching the output, so the same request shape produces a PNG for your confirmation screen and a document for the email attachment. The format docs cover the details.

From a Lambda function, the entire rendering path becomes:

export const handler = async (event) => {
  const res = await fetch('https://app.html2img.com/api/html', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.HTML2IMG_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      html: event.html,
      format: 'pdf',
    }),
  });

  const { url } = await res.json();
  return { statusCode: 200, body: JSON.stringify({ pdf: url }) };
};

No layer, no binary, no version matrix, no /tmp, no browser.close(). The function is back to being a function: milliseconds of compute and a few kilobytes of payload. The response url points at a .pdf served from a CDN, so you store the link against the order rather than shuttling base64 through API Gateway.

What you get out the other end is a real document, not a screenshot glued into a PDF shell. Text is selectable and searchable, webfonts load server-side and are embedded properly, output is vector where it should be, backgrounds print by default and long content paginates onto A4 automatically. The pagination and font problems from failures 2 and 5 are handled where they belong, inside the rendering service, not in your deploy pipeline.

Two more pieces round it off. For slow third-party pages, pass a webhook_url and collect the result asynchronously instead of holding a connection open near a timeout. And if the input is a live page rather than your own markup, the Screenshot endpoint takes a url with the same format parameter, which the URL to PDF page covers in full. The first 25 renders a month are free without a card, so you can test it against your worst template before deciding anything.

When you should still run Puppeteer yourself

An API is not the answer to everything, and pretending otherwise would undersell the cases where DIY is right.

Keep running your own Puppeteer if you need full browser automation rather than rendering: logging in, clicking through flows, scraping behind interaction. Keep it if compliance genuinely prevents document content leaving your infrastructure, though check whether that constraint is real or assumed before you staff it. And at very large sustained volume with a platform team who own a rendering fleet as their job, the economics can favour self-hosting.

If what you need is HTML in, correct PDF out, none of those apply. The test is simple: if the words executablePath, chromium.font or break-inside have appeared in your incident channel this quarter, you are paying an infrastructure tax for a rendering problem. Send the request instead of shipping the browser.

Have you fought Puppeteer PDFs on Lambda, or found a setup that actually stays working? Share your war stories in the comments below.

DEV Community: Accreditly

Why your Open Graph image doesn't show up when you share a link

What happens when someone shares your URL

1. The tags are in devtools but not in the response

2. og:image is a relative path

3. The image is not reachable by an anonymous bot

4. No og:image:width and og:image:height

5. The image is the wrong size, ratio or format

6. twitter:card is missing so X renders the small card

7. The URL you tested is not the URL people share

8. Facebook is still showing a card you fixed last week

Checking the lot in one pass

The block you are aiming for

Stopping it happening again

Generate Open Graph images in GitHub Actions (no headless browser required)

Prerequisites

Step 1: Add your API key as a secret

Step 2: Render your first image

Step 3: Generate OG images for your blog posts

Step 4: Screenshot the pull request preview

Two things that save your credits

Going further

Format Dates, Numbers and Relative Time in JavaScript Without a Library

Dates, properly localised

Numbers, currencies and units

Relative time, the bit everyone installs a library for

Lists that read like sentences

Create formatters once

Where Intl stops

Recap

Your AI agent can't design images. It can write HTML.

Why diffusion is the wrong tool

Prerequisites

Step 1: connect the server

Step 2: ask for an image

Step 3: let it look at its own work

Step 4: put your brand in a rules file

When not to use MCP

Generating 10,000 certificates from one HTML template

What every certificate needs

The three approaches at a glance

Approach 1: a PDF library

Approach 2: an HTML template plus headless Chrome

Approach 3: a template API

Batching 10,000

The verification page

Picking one

Practical Uses for CSS :has() Now That It Works Everywhere

Style the wrapper, not just the input

Cards that adapt to their own content

Styling the previous sibling

Page-level state without JavaScript

Quantity queries

The gotchas

Recap

How to Find and Fix N+1 Queries in Laravel

What an N+1 actually looks like

Make Laravel shout about it

Fix it with eager loading

Counts without loading anything

When the models are already loaded

Pin the query count in a test

Recap

How to Control Page Breaks in HTML to PDF Output

The three properties that do the work

Put them in your normal stylesheet, not in @media print

Keeping an invoice together

Forcing a break where you want one

Do not assume table headers repeat

Running footers with fixed positioning

Flex and grid children fragment fine now

The starter stylesheet

Add "Export as image" to any dashboard

Why not just screenshot the DOM in the browser

Step 1: The export button

Step 2: Render the panel on the server

Step 3: Capturing a live panel by selector

Polishing it

How to Generate Verifiable PDF Certificates in Laravel

Keep the design in Blade

2. `og:image` is a relative path

4. No `og:image:width` and `og:image:height`

6. `twitter:card` is missing so X renders the small card

Why `page.pdf()` is heavier than a screenshot