DEV Community: Accreditly

Browsershot Alternatives: HTML to Image in Laravel Without Puppeteer

Accreditly — Sat, 11 Jul 2026 09:49:18 +0000

Cross-posted from the HTML to Image blog, where the original lives.

Browsershot is the package most Laravel developers reach for when they need to turn HTML into an image. It wraps Puppeteer, drives real Chrome and produces pixel-accurate output. On your machine it works first time. Then you deploy, and the first render throws Failed to launch the browser process!.

The problem is not Browsershot's code. The problem is what it demands from the machine it runs on.

What Browsershot actually asks of your server

Browsershot is a PHP package with a second runtime hiding inside it. To run it in production you need Node.js, the Puppeteer npm package, a Chrome or Chromium binary, the long tail of shared libraries Chrome links against (libnss3, libatk, libgbm and friends on a slim Debian image) and a font set wide enough to cover whatever your templates contain, emoji included.

That is manageable on a full VPS you control. It falls apart in the places Laravel apps increasingly run:

Laravel Vapor and serverless. The PHP Lambda runtime ships neither Node nor Chrome, and you cannot apt-get your way out of a Lambda. The Puppeteer on Lambda guide covers just how deep that particular hole goes.
Shared and managed hosting. No root, no system packages, no browser binary. Browsershot is simply off the table.
Slim Docker images. php:8.3-fpm-alpine carries none of Chrome's dependencies. Adding Chromium, its libraries and fonts costs a few hundred megabytes and a permanent maintenance line in your Dockerfile.
CI pipelines, where every job downloads a browser before your test suite can touch a render.

The dependency does not stay contained either. Even Spatie's newer packages inherit it: spatie/laravel-og-image renders through laravel-screenshot, which drives Browsershot underneath, so the Node and Chrome requirement follows the whole family wherever it goes.

The usual workarounds

The first workaround is the fat container: bake Chromium, the shared libraries and a font stack into your image, pass the sandbox flags and accept the size. It works, but now every render boots a Chrome process on the same box that serves your requests. Chrome is hungry, so your memory headroom and your render concurrency are suddenly the same budget, and a traffic spike that triggers a burst of OG images can take PHP-FPM down with it.

The second is the sidecar: wnx/sidecar-browsershot ships Browsershot to a dedicated Node Lambda so your Vapor app can call it. Genuinely clever, and it solves the serverless case. It also means you now own a second deployment with its own IAM roles, layers, cold starts and a Node function that has to stay version-locked to your PHP code.

Both are real answers. Both also amount to operating a browser fleet so your app can produce a PNG.

The third option is to stop hosting the browser.

Rendering over an API instead

The official Laravel package for HTML to Image moves the Chrome part behind an API and leaves your app with a single HTTP call. It lives on GitHub and Packagist, and setup is the install plus a key:

composer require html2img/html2img-laravel

HTML2IMG_API_KEY=your-api-key

Package discovery registers the service provider and the Html2img facade, and php artisan html2img:test renders a small test image to confirm the key is live. Renders still run in real Chrome, just on the API side, so flexbox, grid, custom properties, web fonts and inline JavaScript behave exactly as they did under Browsershot. The output does not change. Where Chrome lives does.

Here is the classic case, a dynamic Open Graph image rendered from a Blade view:

use Html2img\Laravel\Facades\Html2img;
use Html2img\Request\HtmlRequest;

$response = Html2img::html(new HtmlRequest(
    html: view('og.post', ['post' => $post])->render(),
    width: 1200,
    height: 630,
    dpi: 2, // retina
));

return $response->url; // https://i.html2img.com/abc123def456.png

No Node on the box, no binary paths to configure, nothing browser-shaped in the Dockerfile. The same call renders whatever your Blade views can produce, and the invoice to image guide walks a complete billing example. The package guide covers the config file, the custom Guzzle client binding and every render option.

Swapping the call site

Migration is mostly mechanical because the shapes line up. A typical Browsershot call:

use Spatie\Browsershot\Browsershot;

Browsershot::html(view('og.post', ['post' => $post])->render())
    ->windowSize(1200, 630)
    ->save(storage_path("app/og/{$post->id}.png"));

becomes:

use Html2img\Laravel\Facades\Html2img;
use Html2img\Request\HtmlRequest;

$response = Html2img::html(new HtmlRequest(
    html: view('og.post', ['post' => $post])->render(),
    width: 1200,
    height: 630,
));

$path = Html2img::store($response, "og/{$post->id}.png");

store() downloads the render and writes it to any Laravel filesystem disk, local or S3, and hands back the path. If the CDN URL the API returns is all you need, skip the download entirely and serve that.

Screenshots are covered too

Browsershot's other job is capturing live URLs, and the swap is the same shape. selector crops the capture to one element and css is injected before capture, which is the polite way to remove cookie banners and chat widgets from the shot:

use Html2img\Laravel\Facades\Html2img;
use Html2img\Request\ScreenshotRequest;

$response = Html2img::screenshot(new ScreenshotRequest(
    url: 'https://example.com',
    selector: '#hero',
    css: '.cookie-banner, .intercom-launcher { display: none !important; }',
    dpi: 2,
));

The selector parameter docs cover the crop behaviour, and there is a full walkthrough on screenshotting a single element from a URL.

Failure handling you can actually catch

Browsershot failures surface as process exceptions, which leaves you matching on stderr strings to work out whether Chrome crashed, timed out or never launched. The package throws typed exceptions instead, with the status code and decoded response attached:

use Html2img\Laravel\Facades\Html2img;
use Html2img\Request\HtmlRequest;
use Html2img\Exception\RateLimitException;
use Html2img\Exception\Html2imgException;

try {
    $response = Html2img::html(new HtmlRequest(html: $document));
} catch (RateLimitException $e) {
    // 429: back off and release the job for retry
} catch (Html2imgException $e) {
    report($e); // status code, error code and payload all attached
}

That distinction matters most in queued jobs, where a render is a natural fit anyway. Type-hint Html2img\Laravel\Html2img in handle() and the container injects the configured manager, no facade required.

When Browsershot is still the right call

An API is not the answer to everything, and pretending otherwise would be selling.

If your compliance rules forbid sending markup to an external service, you need to own the browser, full stop. If your pipeline produces PDFs rather than images, Browsershot covers ground the image API does not. And if you render at sustained, very high volume with an ops team happy to feed a Chrome fleet, amortised infrastructure can beat per-render pricing. The Puppeteer comparison lays that trade-off out honestly.

For everyone else, the browser on your server is a tax. You pay it in Dockerfile lines, in memory headroom, in the 2am page when a Chromium update breaks fonts, and in every environment where the binary cannot follow you. One composer package and an API key make it someone else's problem, and that someone runs Chrome for a living.

If the only thing keeping Chrome on your server is image rendering, browse the templates gallery or read the docs to get started.

Have you fought a server to get Browsershot running, on Vapor, shared hosting or a slim container? Share the war story in the comments below.

How to auto-generate Open Graph images for every WordPress post

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

First published on the Accreditly blog.

Share a WordPress post on LinkedIn, Slack or X and the preview is usually a letdown. It pulls your featured image at the wrong aspect ratio, falls back to your site logo or shows nothing at all. A featured image is not an Open Graph image. It is rarely 1200x630, its focal point gets cropped in the wrong place and plenty of posts have none set. The fix is to generate a proper share card for every post automatically, from the post's own title and details, and serve it as the og:image. This article wires that up in a small plugin or your theme's functions.php.

The plan

You need three things: a card design, a way to render it to an image when a post is saved, and the meta tags that point social platforms at it. We keep the design as HTML, render it through the Open Graph image endpoint at a real 1200x630, store the resulting URL in post meta, and output it in the document head. Nothing runs on the front end, so there is no performance cost to readers.

If you want the background on why featured images fall short and how the rendered-card approach holds up across platforms, our deeper write-up on dynamic Open Graph images in WordPress covers the edge cases. Here we will build the working version.

Step 1: Build the card from the post

Start with a function that turns a post into a branded 1200x630 card. Inline every style so the render does not depend on your theme stylesheet.

function ai_og_card_html( WP_Post $post ): string {
    $title = esc_html( get_the_title( $post ) );
    $site  = esc_html( get_bloginfo( 'name' ) );
    $cat   = esc_html( get_the_category( $post->ID )[0]->name ?? 'Article' );

    return <<<HTML
    <div style="width:1200px;height:630px;box-sizing:border-box;padding:80px;
                display:flex;flex-direction:column;justify-content:space-between;
                font-family:Arial,sans-serif;color:#fff;
                background:linear-gradient(135deg,#1e3a8a,#4f46e5);">
      <div style="font-size:24px;letter-spacing:.1em;text-transform:uppercase;opacity:.8;">{$cat}</div>
      <h1 style="font-size:64px;line-height:1.1;margin:0;">{$title}</h1>
      <div style="font-size:28px;font-weight:bold;">{$site}</div>
    </div>
    HTML;
}

Step 2: Render and store the image when a post is saved

Hook save_post. When a published post is saved, render the card and stash the returned URL in post meta. Guard against autosaves and revisions so you are not firing on every keystroke.

add_action( 'save_post', 'ai_generate_og_image', 20, 2 );

function ai_generate_og_image( int $post_id, WP_Post $post ): void {
    if ( wp_is_post_autosave( $post_id ) || wp_is_post_revision( $post_id ) ) {
        return;
    }
    if ( $post->post_status !== 'publish' || $post->post_type !== 'post' ) {
        return;
    }

    $response = wp_remote_post( 'https://app.html2img.com/api/html', [
        'headers' => [
            'X-API-Key'    => HTML2IMG_API_KEY,
            'Content-Type' => 'application/json',
        ],
        'timeout' => 20,
        'body'    => wp_json_encode( [
            'html'   => ai_og_card_html( $post ),
            'width'  => 1200,
            'height' => 630,
        ] ),
    ] );

    if ( is_wp_error( $response ) ) {
        return;
    }

    $url = json_decode( wp_remote_retrieve_body( $response ), true )['url'] ?? null;
    if ( $url ) {
        update_post_meta( $post_id, '_og_image', esc_url_raw( $url ) );
    }
}

Define HTML2IMG_API_KEY in wp-config.php rather than hard-coding it in the theme. Because the work happens on save, the reader never waits for it, and the URL is ready long before anyone shares the post.

Step 3: Output the Open Graph tags

Now print the stored image in the head, with the dimensions that let platforms render it without re-fetching. Fall back to the featured image only if no card has been generated yet.

add_action( 'wp_head', 'ai_output_og_tags' );

function ai_output_og_tags(): void {
    if ( ! is_singular( 'post' ) ) {
        return;
    }

    $post_id = get_queried_object_id();
    $image   = get_post_meta( $post_id, '_og_image', true )
        ?: get_the_post_thumbnail_url( $post_id, 'full' );

    if ( ! $image ) {
        return;
    }

    printf( '<meta property="og:image" content="%s" />' . "\n", esc_url( $image ) );
    printf( '<meta property="og:image:width" content="1200" />' . "\n" );
    printf( '<meta property="og:image:height" content="630" />' . "\n" );
    printf( '<meta name="twitter:card" content="summary_large_image" />' . "\n" );
}

If an SEO plugin such as Yoast already prints og:image, filter its output instead of adding a second tag. Yoast exposes wpseo_opengraph_image, so you can return your stored URL there and let the plugin handle the rest of the markup.

add_filter( 'wpseo_opengraph_image', function ( $image ) {
    $stored = get_post_meta( get_queried_object_id(), '_og_image', true );
    return $stored ?: $image;
} );

Backfilling existing posts

New posts are covered on save. For the archive, run a one-off WP-CLI command that loops your published posts and triggers the same generation, so the whole site gets cards in one pass.

WP_CLI::add_command( 'og:backfill', function () {
    foreach ( get_posts( [ 'numberposts' => -1, 'post_status' => 'publish' ] ) as $post ) {
        ai_generate_og_image( $post->ID, $post );
        WP_CLI::log( "Generated card for: {$post->post_title}" );
    }
} );

That is the full loop. Every post now gets a clean, on-brand 1200x630 card built from its own title and category, generated the moment it is saved and served as the og:image. Your shares stop pulling badly cropped featured images, and you never open a design tool to make a single one.

How to turn any URL into a screenshot from Node.js

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

First published on the Accreditly blog.

You need a screenshot of a web page from a Node script: a thumbnail for a link, a visual record of a competitor's pricing page, an automated grab of a dashboard for a report. The instinct is to reach for Puppeteer, which means bundling a copy of Chromium, keeping it patched, and finding somewhere with enough memory to run it. For most jobs that is far more than you need. A screenshot API does the browser part for you, and your Node code shrinks to a single fetch. This article shows how to turn any URL into a PNG from Node, including full-page captures and grabbing one specific element.

One request instead of a browser

The whole task comes down to sending a URL to an endpoint and getting an image back. No puppeteer.launch, no --no-sandbox flags, no Chromium layer in your deploy. We use the HTML to Image API from plain Node, with the global fetch that ships in Node 18 and later.

async function screenshot(url, opts = {}) {
  const res = 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, width: 1280, height: 800, ...opts }),
  });

  if (!res.ok) {
    throw new Error(`Screenshot failed: ${res.status} ${await res.text()}`);
  }

  const { url: imageUrl } = await res.json();
  return imageUrl;
}

Call it with any page and you get back a hosted PNG URL.

const image = await screenshot('https://example.com');
console.log(image); // https://i.html2img.com/...

Keep your key in an environment variable, never in the source. The width and height set the viewport the page is captured at, just like a browser window.

Saving the file to disk

A hosted URL is handy, but often you want the bytes locally to attach to an email or commit to a report folder. Fetch the image and write it out.

import { writeFile } from 'node:fs/promises';

async function saveScreenshot(url, path) {
  const imageUrl = await screenshot(url);
  const bytes = Buffer.from(await (await fetch(imageUrl)).arrayBuffer());
  await writeFile(path, bytes);
  return path;
}

await saveScreenshot('https://example.com', './example.png');

That is the entire round trip: request the screenshot, download the result, write the file.

Capturing the full page

By default you get the viewport. To capture the entire scrollable page, top to bottom, set full_page. This is the one you want for archiving a long article or a pricing page that runs well below the fold.

const longPage = await screenshot('https://example.com/pricing', {
  full_page: true,
});

The full_page flag and the rest of the capture options are listed in the parameters reference, so you can see exactly what each one does.

Grabbing one element instead of the whole page

Sometimes you do not want the page, you want a piece of it: a chart, a card, a single widget. Pass a selector and the API captures just that element, cropped to its bounds. It waits for the element to be present before shooting.

const chart = await screenshot('https://example.com/dashboard', {
  selector: '#revenue-chart',
});

This is far cleaner than capturing the whole page and cropping in code, because the crop tracks the element's real size rather than fixed pixel coordinates that break the moment the layout shifts.

Screenshotting a list of URLs

Reporting jobs usually mean several pages at once. Map over the list, but cap how many run at the same time so you are polite to the API and do not blow your rate limit. A small concurrency helper does the job without a dependency.

async function mapLimit(items, limit, fn) {
  const results = [];
  const queue = [...items.entries()];

  async function worker() {
    for (const [i, item] of queue.splice(0)) {
      results[i] = await fn(item);
    }
  }

  await Promise.all(Array.from({ length: limit }, worker));
  return results;
}

const pages = [
  'https://example.com',
  'https://example.com/about',
  'https://example.com/pricing',
];

const shots = await mapLimit(pages, 3, (url) => screenshot(url));

For a long-running batch, prefer a webhook over waiting on each response: the API can call you back when each image is ready, which keeps your script from blocking on slow renders. The webhook option is documented alongside the other parameters.

What you have now

A screenshot function that turns any URL into a PNG, options for full-page and single-element captures, a save-to-disk helper and a batch runner with sane concurrency. All of it is plain Node and one fetch, with no browser to install, patch or babysit. When the task is "give me an image of this page", that is usually all it needs to be.

Satori's CSS limits: what it can and can't render

Accreditly — Mon, 29 Jun 2026 08:48:39 +0000

A recent post on the HTML to Image blog looked at why @vercel/og drops emoji from your Open Graph images. That is not a one-off bug. It is a symptom of how the whole thing works. The engine underneath @vercel/og and next/og is Satori, and Satori is not a browser. It converts HTML and CSS into SVG using a flexbox layout engine, and it implements a deliberately small subset of CSS. Emoji is one thing that subset leaves out. This post covers the rest, so you know why a card that looks right in Chrome can break, or quietly render wrong, the moment Satori touches it.

Satori is not a browser

Satori uses the same flexbox layout engine as React Native, the Yoga engine, and it is clear in its own docs that this is not a complete CSS implementation. @vercel/og wraps it: Satori produces the SVG, then it is rasterised to PNG, the whole thing designed to run in an edge function. You can read the supported list in the Satori readme and Vercel's OG image docs.

The mental model that saves you time is this. You are not writing CSS for a browser. You are writing for Yoga plus a curated set of properties. Almost every surprise comes from assuming browser behaviour that Satori never promised.

Everything is flexbox

The headline limit is layout. In Satori, display is either flex or none. There is no block, no inline-block, no table and, the one that catches most people, no grid. Vercel's docs say it plainly: advanced layouts using display: grid will not work.

Because the default is flex and there is no block flow, any element with more than one child has to declare its display explicitly. Leave it out and you get the error every Satori user has seen:

import { ImageResponse } from '@vercel/og'

new ImageResponse(
  <div style={{ color: 'white' }}>
    <h1>Title</h1>
    <p>Subtitle</p>
  </div>
)

// Error: Expected <div> to have explicit "display: flex" or "display: none"
//        if it has more than one child node.

The fix is to say what you mean:

<div style={{ display: 'flex', flexDirection: 'column', color: 'white' }}>
  <h1>Title</h1>
  <p>Subtitle</p>
</div>

CSS Grid is the bigger adjustment. You rebuild every grid as nested flex containers. A two column layout is a row with two half-width children:

<div style={{ display: 'flex' }}>
  <div style={{ display: 'flex', width: '50%' }}>Left</div>
  <div style={{ display: 'flex', width: '50%' }}>Right</div>
</div>

A card grid is a wrapping flex row with fixed-width children:

<div style={{ display: 'flex', flexWrap: 'wrap', gap: 16 }}>
  <div style={{ display: 'flex', width: '33.33%' }}>Card</div>
  <div style={{ display: 'flex', width: '33.33%' }}>Card</div>
  <div style={{ display: 'flex', width: '33.33%' }}>Card</div>
</div>

Most grid patterns do translate, but you carry the translation in your head and your markup grows a layer of wrapper divs.

Positioning and units are limited too

position supports relative and absolute only. There is no fixed and no sticky, which makes sense because Satori renders to a fixed canvas, not a scrolling viewport. For the same reason, viewport units do not work: vw, vh, vmin and vmax are silently ignored. Size things in pixels and percentages instead.

There is also no z-index. SVG paints in document order, so an element that comes later in the markup sits on top. If you need one thing above another, order the markup that way rather than reaching for a stacking context. Two dimensional transforms work, but three dimensional ones do not.

No selectors, pseudo-elements or media queries

You style with inline styles. There are no stylesheets, no class selectors, no :hover or :focus, no media queries and no ::before or ::after. The pseudo-element one bites hardest in practice, because so many designs lean on ::before for a decorative bar, an overlay or a quotation mark. In Satori you draw those as real elements:

// A ::before accent bar becomes a real child element
<div style={{ display: 'flex', flexDirection: 'column' }}>
  <div style={{ display: 'flex', width: 64, height: 6, background: '#818cf8' }} />
  <h1 style={{ marginTop: 24 }}>Heading</h1>
</div>

@vercel/og lets you use Tailwind through a tw prop, which feels like a way out, but it compiles down to the same inline subset. A class that maps to an unsupported property is still unsupported. Tailwind changes the syntax, not the boundaries.

Fonts and text have their own rules

There are no system fonts. If any text renders, you have to pass the font data yourself as an ArrayBuffer or Buffer:

new ImageResponse(<div style={{ fontFamily: 'Inter' }}>Hello</div>, {
  width: 1200,
  height: 630,
  fonts: [
    { name: 'Inter', data: interArrayBuffer, weight: 600, style: 'normal' },
  ],
})

Satori reads TTF, OTF and WOFF. It does not read WOFF2, which trips people up constantly because Google Fonts serves WOFF2 by default, so a font that loads fine in a browser fails here. Advanced typography such as kerning, ligatures and other OpenType features is not supported, and right-to-left scripts are not handled. Emoji, as the emoji post covered, have to be loaded as graphics through loadAdditionalAsset, because there is no emoji font in the box.

All of this competes for space. @vercel/og runs in an edge function with a 500KB bundle limit, and that budget covers your JSX, CSS, fonts and images. Every extra font weight and emoji asset you load eats into it, so a card with two or three weights and a logo can run out of room faster than you would expect.

The failures are usually silent

The explicit display: flex error is loud. Almost nothing else is. An old-version gap, a vh, a backgroundSize, an em font size: these tend to do nothing at all rather than throw, so the only way to map the edges is trial and error against the OG playground. Satori does give you one debugging aid, a debug flag that draws the layout boxes:

new ImageResponse(element, { width: 1200, height: 630, debug: true })

It is worth saying that the subset has grown. Flexbox gap and background-size: cover work in current versions where they did not a couple of years ago, and CSS custom properties are supported now, including fallbacks and inheritance. The specific gaps move. The model does not. You are maintaining a template in a dialect of CSS whose boundaries you find by hitting them.

What Satori does well

To be fair, the supported subset is enough for a great many cards. Flexbox layout, absolute and relative positioning, padding and margin and gap, borders and border radius, box shadow and opacity, linear and radial gradients, background images by url, two dimensional transforms, text-overflow: ellipsis with line clamping and CSS variables all work. Satori is fast, deterministic and runs at the edge, which is exactly why @vercel/og chose it. If your OG cards live inside that subset, it is a good tool and there is no reason to move.

The limits only bite when you bring a richer browser layout to it and expect the browser to show up.

When to render with a browser instead

If your design needs the parts Satori leaves out, CSS Grid, pseudo-elements, media-query variants, WOFF2 or system fonts, emoji without manual loading, real OpenType typography, then stop fighting the subset and render with a real browser engine. This is the same conclusion the emoji post reached. A browser runs the whole CSS platform, so the card you build in the browser is the card you get back.

The tradeoff is honest. You give up Satori's edge-function model and call a browser instead. The HTML to Image API does that as a hosted request. You POST the HTML and CSS and get a PNG, with grid, pseudo-elements, web fonts and emoji all working, because the render happens in real Chromium:

const res = 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: `<div style="display:grid; grid-template-columns:1fr 1fr; gap:24px;">
             <div>Grid works here</div>
             <div>So do ::before and web fonts</div>
           </div>`,
    width: 1200,
    height: 630,
  }),
})

const { url } = await res.json()

If you are weighing the two for a Next.js project, the walk-through on dynamic OG images in Next.js without @vercel/og sets the API approach next to the Satori one. The Open Graph image template is a ready starting point, and there is a no-code Open Graph image generator if you want to design a card without writing the markup first.

Outgrowing Satori's CSS subset and want OG cards rendered in a full browser engine? Browse the templates gallery or read the docs to get started.

How we generate code screenshots for socials

Accreditly — Wed, 17 Jun 2026 16:00:00 +0000

We post a lot of code to X and LinkedIn. For a long time we grabbed those screenshots by hand: snippet open in the editor, crop the window, drop the PNG into the post. It worked, but it never stayed consistent. The theme drifted between posts, the widths were all over the place, the output looked soft on retina screens, and roughly once a month someone shipped a screenshot with the file tree still showing.

So we stopped doing it by hand. These days we generate code screenshots two ways, and which one we reach for depends entirely on whether a human or a machine is making the image. For one-offs we use a browser tool, the Code Screenshot Generator, which turns a snippet into a PNG without going anywhere near the codebase. For anything that needs to happen at publish time, or the same way across fifty snippets, we call a code screenshot API instead. This post covers both, and why we settled on the split.

Why screenshotting the editor does not scale

Grabbing the editor window is fine for one image. The trouble starts when you do it repeatedly.

Every screenshot ends up slightly different. One uses your current editor theme, the next uses whatever you switched to last week. The line gutter is in one, absent from another. The padding is whatever the window happened to be. Crop them by hand and the widths never match, so a thread of three snippets reads as three different posts stitched together. And because you are capturing a real screen, the output is tied to your display, which means it looks crisp on your machine and soft on everyone else's phone.

Carbon and Ray.so solve the prettiness problem, and we used them happily for years. They are genuinely good in-browser tools. The catch is that both are in-browser only, with no API. The moment you want a screenshot generated automatically, at publish time or inside a build step, a hand tool is the wrong shape for the job. You cannot put a button-click in a deploy pipeline.

The quick route: a browser tool for one-offs

When it is a single snippet for a tweet or a slide, and you are away from the code anyway, the fastest path is the online code screenshot tool. Paste the snippet, pick the language, and you get a clean image back.

It highlights any language Prism or highlight.js recognises, which is roughly three hundred of them, so JavaScript, Python, Rust, SQL, Elixir and the long tail are all covered. You pick a theme (One Dark, Dracula, GitHub, Night Owl and a handful of others, each matching its VS Code counterpart closely), toggle the macOS-style window chrome on or off, set the padding, and choose a solid colour or a gradient behind the code. Then you download the PNG or copy the hosted URL straight into a post.

That covers the ad-hoc case. The interesting part is what happens when you want the same output without a person in the loop.

The repeatable route: a code screenshot API

When the image needs to be produced by a machine, at publish time, in CI, or off a CMS hook, we use the Code Screenshot API. It is a ready-made template on HTML to Image (html2img.com): you POST the code and a few styling options as JSON, and you get back a hosted PNG URL. It is the same renderer that sits behind the browser tool, so the screenshots match whichever route produced them. There is no headless Chrome for you to install, patch, or babysit.

You need two things to follow along: an account with an API key, and a snippet to render. Here is the smallest call that does something useful, with curl:

curl -X POST https://app.html2img.com/api/v1/templates/code-screenshot \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "export async function fetchUser(id: string) {\n  const res = await fetch(`/api/users/${id}`);\n\n  if (!res.ok) {\n    throw new Error(`Failed to load user ${id}`);\n  }\n\n  return res.json() as Promise<User>;\n}",
    "language": "typescript",
    "title": "src/lib/users.ts",
    "theme": "atom-one-dark",
    "background": "linear-gradient(135deg, #6366F1 0%, #8B5CF6 50%, #EC4899 100%)",
    "padding": 72,
    "show_window_chrome": "true",
    "show_line_numbers": "false"
  }'

The fields map onto what you would set in the browser tool. code is the snippet, with newlines escaped in the JSON string. language drives the highlighting. title is the filename shown in the window bar. theme, background, and padding are the styling, and the two show_ flags toggle the window chrome and line numbers. Only code is required; leave the rest off and the template falls back to sensible defaults. The full input list, with example values and validation rules, is in the Code Screenshot template reference.

By default the template renders a 1600 by 1000 PNG, which you can override with width and height. A successful call returns JSON:

{
  "success": true,
  "id": "abc123",
  "url": "https://i.html2img.com/abc123.png",
  "credits_remaining": 1234,
  "template": "code-screenshot"
}

The url is a CDN link to the rendered image. That URL is the whole point: you store it, embed it, or attach it to a post.

Wiring it into the publishing flow

In practice you do not run curl, you call this from the code that publishes the post. Here is the Node version wrapped in a small helper that hands back the image URL:

async function codeScreenshot(code, language, title) {
  const res = await fetch('https://app.html2img.com/api/v1/templates/code-screenshot', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.HTML2IMG_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      code,
      language,
      title,
      theme: 'atom-one-dark',
      background: 'linear-gradient(135deg, #6366F1 0%, #8B5CF6 50%, #EC4899 100%)',
      padding: 72,
      show_window_chrome: 'true',
      show_line_numbers: 'false',
    }),
  });

  if (!res.ok) {
    throw new Error(`code-screenshot render failed: ${res.status}`);
  }

  const { url } = await res.json();
  return url;
}

Call it once per snippet when a post is published, save the returned URL alongside the post, and attach that image to the tweet or LinkedIn share. The code is rendered once and served from the CDN forever after, so there is no per-view cost.

We mostly publish from Laravel, and the shape is identical there. The HTTP client does the work:

use Illuminate\Support\Facades\Http;

$url = Http::withHeaders(['X-API-Key' => config('services.html2img.key')])
    ->post('https://app.html2img.com/api/v1/templates/code-screenshot', [
        'code' => $snippet,
        'language' => 'php',
        'title' => 'app/Actions/RenderSnippet.php',
        'theme' => 'atom-one-dark',
        'show_window_chrome' => 'true',
    ])
    ->throw()
    ->json('url');

The other languages follow the same pattern, and the reference has worked examples for Python, Ruby, React and Vue if you want a closer fit to your stack.

Getting the screenshots to actually read on social

A clean render is only half the job. Social feeds re-compress your image and shrink it, so a few habits make the difference between a screenshot people can read and one they scroll past.

Trim the snippet first. Anything past roughly twenty lines shrinks below a readable point size once the renderer scales it to fit, so cut to the part that matters and split a longer example into a sequence of smaller images rather than one tall one nobody can read.

Pick a theme that survives compression. Low-contrast themes like Solarized Light lose detail when X or LinkedIn re-encode the image for the feed. Higher-contrast themes (One Dark, Dracula, GitHub) hold up far better through that round trip, so favour them for anything social.

Keep it sharp. The browser tool has a 2x DPI toggle for retina output. Through the API the default 1600 by 1000 render is already large enough to stay crisp after a feed re-compresses it, and you can push the dimensions higher if you need more headroom.

Cache the URL hard. A rendered snippet's CDN URL does not change unless the code changes, so set long cache headers and only re-render when the snippet itself moves. Re-rendering an unchanged screenshot on every publish is wasted work.

Which one we reach for

The split is simple. One-offs, and anything where you are already away from the editor, go through the code screenshot generator in the browser. Anything repeatable, or that has to happen at publish time, goes through the code screenshot template and its API. Because both run the same renderer, the two never drift apart, which was the original problem we set out to fix.

If you want to go deeper, the Code Screenshot API reference lists every input, including line numbers, diff highlighting by setting the language to diff, and custom themes via a Prism variables block.

How do you handle code screenshots for your posts at the moment, still grabbing them by hand, or have you wired it into publishing? Let me know in the comments.

[Boost]

Accreditly — Wed, 17 Jun 2026 15:38:11 +0000

Accreditly

Jun 10

Dynamic OG Images in Rails

#rails #ruby #webdev #tutorial

6 min read

Use Laravel to create your own MCP server

Accreditly — Tue, 16 Jun 2026 14:20:41 +0000

Claude can already work with your Laravel app. Not by you hand-building a REST API, writing a client, and describing every endpoint to it, but by exposing a few tools over the Model Context Protocol (MCP) and letting the model call them directly. The official laravel/mcp package turns that into an afternoon's work.

This is the hands-on version. We'll build a small MCP server for an online shop: tools the model can call, a resource it can read, input validation, auth, and a test to keep it honest. The full write-up of how the protocol fits together lives on our site, Use Laravel to create your own MCP server. Here we're going to write the code.

First, the short version of what we're building. An MCP server exposes three things to a connected AI client: tools (actions the model can call, like searching orders), resources (read-only data it can pull in for context), and prompts (reusable templates). The client and server talk JSON-RPC, and laravel/mcp handles that wire format so you only write PHP.

Prerequisites

A recent Laravel application (12.x works well).
PHP 8.2 or newer.
Composer.
An MCP client to connect with later. Claude Desktop or Claude Code both work, and the bundled MCP Inspector covers testing.

Step 1: Install the package

Pull it in with Composer:

composer require laravel/mcp

Then publish the routes file your servers are registered in:

php artisan vendor:publish --tag=ai-routes

That gives you routes/ai.php. Treat it like routes/web.php: every server you expose gets a line in there.

Step 2: Create a server

A server is the thing a client connects to. It groups your tools, resources and prompts under one name. Generate one:

php artisan make:mcp-server OrdersServer

You get app/Mcp/Servers/OrdersServer.php. The class carries its identity in attributes and lists what it exposes in three arrays:

<?php

namespace App\Mcp\Servers;

use App\Mcp\Tools\SearchOrdersTool;
use Laravel\Mcp\Server;
use Laravel\Mcp\Server\Attributes\Instructions;
use Laravel\Mcp\Server\Attributes\Name;
use Laravel\Mcp\Server\Attributes\Version;

#[Name('Orders Server')]
#[Version('1.0.0')]
#[Instructions('Search orders, add internal notes, and cancel orders for the shop.')]
class OrdersServer extends Server
{
    protected array $tools = [
        SearchOrdersTool::class,
    ];

    protected array $resources = [
        //
    ];

    protected array $prompts = [
        //
    ];
}

Don't skip the Instructions attribute. It is sent to the client as context for what the server is for, so the model knows what it is looking at before it calls anything.

Step 3: Register the server

The server does nothing until it is registered in routes/ai.php. There are two kinds. A web server is reachable over HTTP for remote clients, and a local server runs as an Artisan command for agents on the same machine, like Claude Code.

use App\Mcp\Servers\OrdersServer;
use Laravel\Mcp\Facades\Mcp;

Mcp::web('/mcp/orders', OrdersServer::class)
    ->middleware(['auth:sanctum', 'throttle:60,1']);

Mcp::local('orders', OrdersServer::class);

Web servers are ordinary routes, so the middleware you already use applies. We'll come back to the auth line in Step 8.

Step 4: Build a tool

This is the part that does real work. Generate a tool:

php artisan make:mcp-tool SearchOrdersTool

A tool has two methods. schema declares the arguments it accepts, and handle runs the work and returns a response. Here's a read-only search over orders:

<?php

namespace App\Mcp\Tools;

use App\Models\Order;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Tool;
use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;

#[IsReadOnly]
#[Description('Search recent orders, optionally filtered by status, and return their references and totals.')]
class SearchOrdersTool extends Tool
{
    public function handle(Request $request): Response
    {
        $validated = $request->validate([
            'status' => ['nullable', 'in:pending,shipped,delivered,cancelled'],
            'limit' => ['integer', 'between:1,50'],
        ]);

        $orders = Order::query()
            ->when($validated['status'] ?? null, fn ($query, $status) => $query->where('status', $status))
            ->latest()
            ->limit($validated['limit'] ?? 10)
            ->get();

        if ($orders->isEmpty()) {
            return Response::text('No orders matched that search.');
        }

        return Response::structured([
            'count' => $orders->count(),
            'orders' => $orders->map(fn ($order) => [
                'reference' => $order->reference,
                'status' => $order->status,
                'total' => $order->total,
                'placed_at' => $order->created_at->toIso8601String(),
            ])->all(),
        ]);
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'status' => $schema->string()
                ->enum(['pending', 'shipped', 'delivered', 'cancelled'])
                ->description('Only return orders with this status.'),

            'limit' => $schema->integer()
                ->description('Maximum number of orders to return.')
                ->default(10),
        ];
    }
}

It's already in the server's $tools from Step 2, so the client can call it now.

Two things are worth calling out. The schema is a typed contract for the model: status is one of four values, limit is an integer with a default. And the Description is how the model decides when to reach for the tool, so write it like you're briefing someone who has never seen your code. Response::structured() sends back parseable data while keeping a plain text version for clients that want one.

Step 5: Validate the input, and write errors the model will read

The schema sets the shape. Laravel's validator enforces the rules, exactly as in a controller:

$validated = $request->validate([
    'reference' => ['required', 'string', 'max:32'],
], [
    'reference.required' => 'Provide the order reference, for example "ORD-10423".',
]);

Here's the part people miss. The error message goes back to the model, and the model decides what to do next from what it says. "The reference field is required" tells it nothing. "Provide the order reference, for example ORD-10423" tells it how to retry. Write validation messages as instructions to a reader who is going to act on them.

Step 6: Tell the client how a tool behaves

Annotations describe a tool's behaviour without changing what it does. A client uses them to decide how to present a tool, for example asking the user to confirm before running anything that makes a change. They are attributes:

<?php

namespace App\Mcp\Tools;

use App\Models\Order;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Tool;
use Laravel\Mcp\Server\Tools\Annotations\IsDestructive;
use Laravel\Mcp\Server\Tools\Annotations\IsIdempotent;

#[IsDestructive]
#[IsIdempotent]
#[Description('Cancel an order. An order that is already cancelled is left unchanged.')]
class CancelOrderTool extends Tool
{
    public function handle(Request $request): Response
    {
        $validated = $request->validate([
            'reference' => ['required', 'string', 'max:32'],
        ]);

        $order = Order::where('reference', $validated['reference'])->firstOrFail();

        if ($order->status !== 'cancelled') {
            $order->update(['status' => 'cancelled']);
        }

        return Response::text("Order {$order->reference} is cancelled.");
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'reference' => $schema->string()
                ->description('The reference of the order to cancel.')
                ->required(),
        ];
    }
}

There are four: #[IsReadOnly] (changes nothing), #[IsDestructive] (can make destructive changes), #[IsIdempotent] (running it again with the same arguments changes nothing further), and #[IsOpenWorld] (it touches systems outside your app). Cancelling an order is destructive but idempotent: cancel it twice and it is still just cancelled. Add CancelOrderTool::class to the server's $tools so it can be called.

Step 7: Add a resource and a prompt

Tools are actions. The other two primitives fill in the picture.

A resource is read-only context the model can pull in. No arguments, just a handle that returns content, like a returns policy:

<?php

namespace App\Mcp\Resources;

use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Resource;

#[Description('The shop returns and refunds policy.')]
class RefundPolicyResource extends Resource
{
    public function handle(Request $request): Response
    {
        return Response::text(file_get_contents(resource_path('policies/refunds.md')));
    }
}

A prompt is a reusable template the client can offer the user. It declares its arguments and returns the messages:

<?php

namespace App\Mcp\Prompts;

use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Prompt;
use Laravel\Mcp\Server\Prompts\Argument;

#[Description('Draft a short status update to send to a customer about their order.')]
class OrderUpdatePrompt extends Prompt
{
    public function arguments(): array
    {
        return [
            new Argument(
                name: 'reference',
                description: 'The order the update is about.',
                required: true,
            ),
        ];
    }

    public function handle(Request $request): array
    {
        $reference = $request->string('reference');

        return [
            Response::text('You write friendly customer service messages.')->asAssistant(),
            Response::text("Draft a short update for the customer about order {$reference}."),
        ];
    }
}

Generate these with make:mcp-resource and make:mcp-prompt, then register them in the server's $resources and $prompts arrays.

Step 8: Secure the server

A web MCP server is a public endpoint that can read and change your data. Leaving it open is the same mistake as shipping an admin API with no auth. Because it is a normal route, you protect it with middleware.

The simple option is a token with Laravel Sanctum. The client sends it in the Authorization header:

Mcp::web('/mcp/orders', OrdersServer::class)
    ->middleware(['auth:sanctum', 'throttle:60,1']);

For third-party clients, OAuth 2.1 through Laravel Passport is the stronger choice. Register the discovery routes and apply Passport's guard:

Mcp::oauthRoutes();

Mcp::web('/mcp/orders', OrdersServer::class)
    ->middleware('auth:api');

Once a user is authenticated, the request carries them into your tools, so $request->user() works as normal. You can even hide a tool per user with a shouldRegister method:

public function shouldRegister(Request $request): bool
{
    return $request->user()?->can('manage-orders') ?? false;
}

A tool whose shouldRegister returns false never shows up in the client's list and cannot be called. One server, different tools for different users.

Step 9: Inspect and test it

Two things check the server before a real client touches it.

The MCP Inspector connects to a server and lists its tools, resources and prompts so you can call them by hand. Point it at a registered server by name:

php artisan mcp:inspector orders

It prints the client settings to copy into your MCP client. If the server is behind auth, you add the header there too.

For automated coverage, write a normal test and call the primitive on the server that registers it. The response has assertion helpers:

<?php

use App\Mcp\Servers\OrdersServer;
use App\Mcp\Tools\CancelOrderTool;
use App\Models\Order;

it('cancels an order', function () {
    $order = Order::factory()->create([
        'reference' => 'ORD-10423',
        'status' => 'shipped',
    ]);

    $response = OrdersServer::tool(CancelOrderTool::class, [
        'reference' => 'ORD-10423',
    ]);

    $response
        ->assertOk()
        ->assertSee('ORD-10423 is cancelled');

    expect($order->fresh()->status)->toBe('cancelled');
});

There are matching assertions for errors and notifications, and an actingAs helper for testing tools that depend on the authenticated user.

Wrapping up

You have gone from an empty Laravel app to an MCP server with a read tool, a write tool, a resource, a prompt, authentication, and a test. The model now works against your application through one standard interface, and you never wrote a line of protocol code. The pattern from here is small: add a tool, give it a clear description and honest annotations, validate its input with messages worth reading, and put it behind the right middleware.

For the longer explanation of how MCP fits together, the full article is on our site: Use Laravel to create your own MCP server.

Have you wired an MCP server into something useful yet? Tell me what you connected it to in the comments.

Dynamic OG Images in Rails

Accreditly — Wed, 10 Jun 2026 11:26:35 +0000

Every blog post, product page, and profile in a Rails app deserves its own Open Graph image, the picture that shows up when someone shares the link on Twitter, LinkedIn, or Slack. The catch is that Ruby's options for generating those images are worse than the equivalents in the JavaScript and PHP worlds. There's no Satori, no first-class templating-to-image story, and the tools that do exist either make you place pixels by hand or run a headless browser next to Puma.

This post walks through the three realistic ways to do it in Rails, then builds out the one that keeps your view layer and your servers clean: rendering an ERB template to a PNG over HTTP, with caching and a background job so it never sits on the request path.

This is a cross-post of an article first published on html2img.com.

The three approaches

Approach	What runs	Best for
Image libraries (MiniMagick, ruby-vips)	ImageMagick or libvips on your server	Fixed layouts with very little text
Headless Chrome (Grover)	Node and a Chromium binary alongside Puma	Full CSS control, if you can carry the ops cost
HTML to Image API	One HTTP call, nothing local	Apps that want CSS layouts without running a browser

Approach 1: image libraries, and why they hurt

The pure-Ruby route is MiniMagick or ruby-vips. You open a base image and composite text onto it.

require "mini_magick"

image = MiniMagick::Image.open(Rails.root.join("app/assets/images/og-base.png"))

image.combine_options do |c|
  c.gravity "NorthWest"
  c.pointsize "64"
  c.fill "#0F172A"
  c.font "Inter-Bold"
  c.annotate "+80+80", post.title
end

image.write(Rails.root.join("public/og/#{post.id}.png"))

This works until the text gets interesting. You're positioning every element by hand, with no line wrapping and no idea how wide a string will render until you measure it. You also have to install and reference font files on every machine. For one short line on a fixed background it's fine. The moment you want a title that wraps, an author line, and a logo, you're reimplementing CSS layout in ImageMagick options. Wrong job for the tool.

Approach 2: headless Chrome with Grover

If you want real CSS, the obvious move is to render HTML in a real browser. Grover wraps Puppeteer and turns HTML into a PNG.

# Gemfile
gem "grover"

html = ApplicationController.render(
  template: "og/post",
  layout: false,
  assigns: { post: post }
)

png = Grover.new(html, width: 1200, height: 630).to_png
File.binwrite(Rails.root.join("public/og/#{post.id}.png"), png)

The output is excellent, because it's a browser. The cost is operational. Grover drives Puppeteer, so every machine that renders an image needs Node and a Chromium binary installed next to your Ruby app. On a container that means a much larger image, a few hundred megabytes of Chrome resident whenever it runs, and cold-start latency when the process spins up. You're operating a browser to make a picture.

Approach 3: render an ERB template through an API

The third option keeps the browser-quality rendering but moves it off your infrastructure. You write the OG card as a normal ERB template, render it to an HTML string, and POST that string to an image API. One HTTP call, nothing extra to install.

Start with the key. Add it to your encrypted credentials with rails credentials:edit:

html2img:
  api_key: your-key-here

The key goes out as an X-API-Key header on every request. Now build the template. It's a plain view, styled with inline CSS, sized to exactly the dimensions you'll request.

<%# app/views/og/post.html.erb %>
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <style>
      @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;600;800&display=swap');
      * { margin: 0; box-sizing: border-box; }
      body {
        width: 1200px; height: 630px; padding: 80px;
        display: flex; flex-direction: column; justify-content: space-between;
        background: #0F172A; color: #F8FAFC; font-family: 'Inter', sans-serif;
      }
      .title { font-size: 64px; font-weight: 800; line-height: 1.1; max-width: 1000px; }
      .meta  { font-size: 26px; color: #94A3B8; }
    </style>
  </head>
  <body>
    <div class="title"><%= @post.title %></div>
    <div class="meta"><%= @post.author.name %> &middot; <%= @post.published_at.strftime("%-d %B %Y") %></div>
  </body>
</html>

Set the width and height on the body to match what you send the API, otherwise the content can shift. Because this renders in a real browser, emoji, web fonts, and full CSS behave exactly as they do in your own tab.

Wrap the call in a plain service object. ApplicationController.render turns the template into a string outside the request cycle, and Faraday posts it.

# app/services/og_image_generator.rb
class OgImageGenerator
  ENDPOINT = "https://app.html2img.com/api/html".freeze

  class GenerationError < StandardError; end

  def initialize(post)
    @post = post
  end

  def call
    html = ApplicationController.render(
      template: "og/post",
      layout: false,
      assigns: { post: @post }
    )

    res = connection.post("") do |req|
      req.body = { html: html, width: 1200, height: 630 }.to_json
    end

    raise GenerationError, res.body unless res.success?

    JSON.parse(res.body).fetch("url")
  end

  private

  def connection
    @connection ||= Faraday.new(url: ENDPOINT) do |f|
      f.headers["Content-Type"] = "application/json"
      f.headers["X-API-Key"]    = Rails.application.credentials.dig(:html2img, :api_key)
      f.options.timeout         = 15
    end
  end
end

The response is JSON with a url pointing at the hosted PNG. Store that on the record rather than proxying the image through your own app.

Generating off the request path

You never want to make an external HTTP call while a user waits for a page, so move generation into a background job.

# app/jobs/generate_og_image_job.rb
class GenerateOgImageJob < ApplicationJob
  queue_as :default

  def perform(post)
    url = OgImageGenerator.new(post).call
    post.update_columns(og_image_url: url, og_signature: post.current_og_signature)
  end
end

update_columns writes straight to the database without firing callbacks, which matters in a second.

Caching so you don't regenerate on every save

Regenerating the image every time a record is touched wastes calls. The fix is a signature: a hash of only the fields that appear in the image. If the signature hasn't changed, the existing image is still correct.

class AddOgFieldsToPosts < ActiveRecord::Migration[7.1]
  def change
    add_column :posts, :og_image_url, :string
    add_column :posts, :og_signature, :string
  end
end

# app/models/post.rb
class Post < ApplicationRecord
  belongs_to :author

  after_save_commit :enqueue_og_image, if: :og_image_outdated?

  def current_og_signature
    Digest::SHA1.hexdigest([title, author.name, published_at.to_i].join("|"))
  end

  private

  def og_image_outdated?
    og_image_url.blank? || og_signature != current_og_signature
  end

  def enqueue_og_image
    GenerateOgImageJob.perform_later(self)
  end
end

Editing a post's body, which isn't part of the card, leaves the signature untouched, so no new image is generated. Change the title and the next save regenerates exactly once. Because the job uses update_columns, storing the new URL and signature doesn't trigger after_save_commit again, so there's no loop.

Wiring up the meta tags

With the URL on the record, the view layer is the easy part. Yield a head block in the layout, then fill it in from the post page with Rails' tag helpers.

<%# app/views/posts/show.html.erb %>
<% content_for :head do %>
  <%= tag.meta property: "og:image",  content: @post.og_image_url %>
  <%= tag.meta name: "twitter:card",  content: "summary_large_image" %>
  <%= tag.meta name: "twitter:image", content: @post.og_image_url %>
<% end %>

Set twitter:card to summary_large_image so the image renders full width rather than as a thumbnail.

Testing without hitting the API

Stub the HTTP call so tests never make a real request, then assert the job stores what the API returned.

# test/jobs/generate_og_image_job_test.rb
require "test_helper"

class GenerateOgImageJobTest < ActiveJob::TestCase
  test "stores the returned image url on the post" do
    post = posts(:hello_world)

    stub_request(:post, "https://app.html2img.com/api/html")
      .to_return(
        status:  200,
        body:    { url: "https://i.html2img.com/abc123.png" }.to_json,
        headers: { "Content-Type" => "application/json" }
      )

    GenerateOgImageJob.perform_now(post)

    assert_equal "https://i.html2img.com/abc123.png", post.reload.og_image_url
  end
end

That uses WebMock, which most Rails test setups already pull in. The same pattern works in RSpec.

Which to reach for

Use MiniMagick only when the layout is fixed and almost text-free. Reach for Grover when you genuinely need a browser on your own infrastructure for other reasons and the OG image is a side benefit. For everything else, rendering an ERB template through an API keeps your servers free of Chrome, gives you real CSS, and costs a single HTTP call per image. Pair it with the signature cache and a background job and OG images become something you set up once and stop thinking about.

The full version, with a couple of extra notes, is on html2img.com. How are you generating OG images in your Rails apps at the moment? Let me know in the comments.

Replacing five Figma files with one HTML renderer for our content brand

Accreditly — Mon, 08 Jun 2026 14:18:00 +0000

The trigger was a brand refresh. The marketing director walked into a Tuesday standup with a new colour palette, a new display font, and a kind smile. The work to roll that out across our content brand was three weeks: I counted the Figma files (blog hero, quote card, podcast cover, episode card, newsletter banner), multiplied by the designer's day rate, and added a fortnight of "could you regenerate the hero image for these 300 archive posts" that I would have to do by hand.

What we shipped instead took a Saturday afternoon and one paid invoice. Every editorial image format moved into HTML templates. The brand variables landed in a single CSS file. A brand refresh became a five-minute edit, a cache bump, and a deploy. The back catalogue regenerated on next request.

This article is the pattern, with working code in Laravel, the bits I got wrong, and when this is the wrong approach.

What was in the stack

Five image formats. Each one had a Figma file. Each one was opened by a different person across the year and slowly drifted into a slightly different interpretation of the same brand.

Blog hero at 1600 by 900. Sits at the top of the article.
Quote card at 1200 by 1200. Pull-quotes for social.
Podcast cover at 1500 by 1500. Apple Podcasts and Spotify directories.
Episode card at 1200 by 630. Per-episode share image.
Email header at 1200 by 300. Newsletter banner. Three different aspect ratios, four different content data shapes, one brand language meant to feel like one thing across all of them. It did not. By the time the refresh landed, the back catalogue looked like a small museum of how the brand had been interpreted over 18 months.

The pattern

One Blade view per format. One CSS partial that defines the brand. One renderer service that handles all five.

namespace App\Services;

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Storage;

class EditorialImageRenderer
{
    private const FORMATS = [
        'blog-hero'     => ['w' => 1600, 'h' => 900,  'view' => 'editorial.blog-hero'],
        'quote-card'    => ['w' => 1200, 'h' => 1200, 'view' => 'editorial.quote-card'],
        'podcast-cover' => ['w' => 1500, 'h' => 1500, 'view' => 'editorial.podcast-cover'],
        'episode-card'  => ['w' => 1200, 'h' => 630,  'view' => 'editorial.episode-card'],
        'email-header'  => ['w' => 1200, 'h' => 300,  'view' => 'editorial.email-header'],
    ];

    public function render(string $format, array $data): string
    {
        $config = self::FORMATS[$format];
        $key = $this->cacheKey($format, $data);

        if (Storage::disk('s3')->exists($key)) {
            return Storage::disk('s3')->url($key);
        }

        $html = view($config['view'], $data)->render();

        $res = Http::withHeaders(['X-API-Key' => config('services.html2img.key')])
            ->post('https://app.html2img.com/api/html', [
                'html' => $html,
                'width' => $config['w'],
                'height' => $config['h'],
                'wait_for_selector' => '.ready',
            ])->throw()->json();

        $bytes = Http::get($res['url'])->throw()->body();
        Storage::disk('s3')->put($key, $bytes, 'public');

        return Storage::disk('s3')->url($key);
    }

    private function cacheKey(string $format, array $data): string
    {
        ksort($data);
        $hash = md5(json_encode([...$data, '_format' => $format, '_v' => '1']));
        return "editorial/{$format}/{$hash}.png";
    }
}

The _v field in the cache key is the brand-refresh switch. Bumping it from '1' to '2' invalidates every cached image. The next request for each one regenerates against the current Blade view, which in turn pulls from the current brand partial.

The brand partial

This is the bit that earns the system its keep. Every per-format Blade view starts with @include('editorial._brand'). The partial defines the colour palette, fonts, and shared element styles. Nothing else in the system hard-codes a brand value.

{{-- resources/views/editorial/_brand.blade.php --}}
<style>
  @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;700;900&family=Fraunces:wght@600;800;900&display=swap');
  * { margin: 0; padding: 0; box-sizing: border-box; }
  :root {
    --brand-bg: #FFFCF5;
    --brand-fg: #1A1A1A;
    --brand-accent: #C2410C;
    --brand-muted: #6B7280;
    --font-display: 'Fraunces', Georgia, serif;
    --font-body: 'Inter', sans-serif;
  }
  body {
    background: var(--brand-bg);
    color: var(--brand-fg);
    font-family: var(--font-body);
  }
  .brand-mark {
    font-family: var(--font-display);
    font-weight: 900;
    letter-spacing: -0.02em;
  }
  .ready { visibility: hidden; height: 0; }
</style>

When the brand refreshed, the changes that landed were: --brand-bg from cream to slate, --font-display from Fraunces to Newsreader, --brand-accent from orange to teal. Three lines. One commit. The PR description was longer than the code change.

One format in full: the blog hero

Most-shared. Doubles as the Open Graph image. Worth showing in full.

{{-- resources/views/editorial/blog-hero.blade.php --}}
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
@include('editorial._brand')
<style>
  body { width: 1600px; height: 900px; padding: 100px; display: grid; grid-template-rows: auto 1fr auto; }
  .category {
    font-size: 18px; font-weight: 700; letter-spacing: 4px;
    text-transform: uppercase; color: var(--brand-accent);
  }
  h1 {
    font-family: var(--font-display);
    font-size: 110px; font-weight: 900;
    line-height: 1.02; letter-spacing: -2px;
    align-self: end; max-width: 1300px;
  }
  footer {
    font-size: 24px; color: var(--brand-muted);
    display: flex; justify-content: space-between; align-items: end;
  }
  footer .author { font-weight: 700; color: var(--brand-fg); }
  .divider { width: 80px; height: 4px; background: var(--brand-fg); margin: 16px 0 32px; }
</style>
</head>
<body>
  <div>
    <div class="category">{{ $category }}</div>
    <div class="divider"></div>
  </div>
  <h1>{{ $title }}</h1>
  <footer>
    <span><span class="author">{{ $author }}</span> · {{ $published_at }}</span>
    <span class="brand-mark">{{ config('app.brand') }}</span>
  </footer>
  <div class="ready"></div>
</body>
</html>

The display font carries most of the visual weight. A 110px title in Fraunces feels editorial in a way 110px in Inter does not. The grid layout anchors the category at the top, the title vertically centred, and the byline at the bottom: three rows that adapt to title length without manual tuning.

Triggering the render from the article model:

public function heroImageUrl(): string
{
    return app(EditorialImageRenderer::class)->render('blog-hero', [
        'title' => $this->title,
        'category' => $this->category->name,
        'author' => $this->author->name,
        'published_at' => $this->published_at->format('jS F Y'),
    ]);
}

The article template embeds the result as a plain <img> tag. Same URL goes into the OG meta tag in the page head.

The other four formats

Each one follows the same shape. A Blade view sized to the viewport, including the brand partial, ending with a .ready element so the renderer knows when to capture.

The data shapes for the ones I haven't shown in full:

Quote card: quote, attribution, optional avatar_url. Big serif italic, an oversized quotation-mark glyph as an accent, the attribution underneath.
Podcast cover: show_name, host, tagline. Square. Generated rarely.
Episode card: episode_number, title, guest, optional topic. Generated automatically when each episode publishes.
Email header: issue_number, volume, date. Wide banner across the top of the newsletter template. If you would rather not build the Blade views, html2img has pre-built blog hero, quote card, podcast cover, podcast episode card and email header templates that accept the same data shape and return a sized PNG. The trade-off is the layout is opinionated. We use the HTML endpoint for the blog hero and quote card (most brand-defining) and the pre-built templates for the rest.

Gotchas

The list that bit me first.

Quote lengths are unpredictable. A 9-word pull-quote at 96px looks balanced. A 32-word quote at the same size overflows the card. Either drop the font size dynamically based on character count, or hard-cap the input length in the editor.

Brand partial cascade. I learned the hard way that putting the brand partial after the per-format <style> block lets the format override the brand. That's the opposite of what you want. The partial goes first, the format styles go after, format-specific rules override brand defaults where needed but the brand variables stay as the source of truth.

Webfonts and wait_for_selector. The convention of ending every template with a <div class="ready"> means the screenshot fires after the meaningful DOM is in place. Without it, the screenshot occasionally captures the page before the webfont has loaded and you ship a fallback render. Solved problem, but only if you remember the convention.

External images. Avatars hosted on third-party CDNs, hero photographs pulled from Cloudinary, brand marks loaded from another domain. Any of them can delay the render or fail outright. Inline your brand assets as SVG or base64. Pre-upload editorial photos to your own fast CDN, or accept that the render will occasionally miss them.

Cache key construction. ksort the data array before hashing. Without stable ordering, the same logical data hashed twice gives two different keys, which doubles your API calls. Took me a confused afternoon to spot.

Don't store the upstream URL. The API returns a CDN URL. Tempting to use it directly. We did, then ran into an outage where every link 404'd. Fetch the bytes once at render time, persist to your own storage, serve from your own CDN.

When this is the wrong approach

Two cases.

If your content output is one piece a fortnight and you have a designer who enjoys the work, the engineering cost is not worth it. The Figma stack has a real cost only at higher cadences.

If your editorial team wants pixel-level art direction on every image (full-bleed photography, custom illustrations per piece), HTML templates can't replace that. They can complement: hero images that need photography handled in Figma, everything else templated. Most content brands sit at the latter mix.

For everything else, the HTML renderer earned its keep in the brand refresh that triggered it. The thing it actually unlocks is content-team velocity: they can ship a quote card without waiting for the designer, because the template enforces the brand for them. That benefit shows up every week, not just at brand refresh time.

The first version took an afternoon. The maintenance cost is roughly zero, because there is no Chromium and no Figma file to keep in sync. If you're staring at a Figma folder with five subfolders right now, this is the half-day refactor worth doing.

Why we replaced PDF invoice attachments with inline PNG receipts

Accreditly — Mon, 01 Jun 2026 14:04:00 +0000

We used to attach a PDF to every order confirmation email. The PDF was the invoice, generated server-side from a Blade template via a PDF library, and it worked. It also tanked our email open rates on mobile, where the attachment showed up as a generic clip icon nobody tapped, and it pushed up our spam score because PDF attachments at scale carry weight.

A year ago we replaced the PDF with an inline PNG image embedded in the email body. Same content. No attachment. The image renders the moment the email opens. Customers see the invoice without tapping anything. Open rates went up. The spam score dropped enough to feel it.

This article is about the pattern that replaced the PDF, and how the same plumbing handles receipts, vouchers, and product cards. Working code in Laravel, the bits we got wrong, and when this is the wrong approach.

Why the PDF attachment is not great

A PDF as an order confirmation feels professional. There are three real problems.

PDFs are heavy. A styled invoice from a library like dompdf weighs roughly 150 KB. The equivalent PNG is 40 KB. When you send a million transactional emails a year, the difference adds up. More importantly, your email service provider grades you on average message size, and that grade feeds back into deliverability.

Mobile email clients hide attachments. Gmail on Android shows a generic "1 attachment" pill that needs a tap. iOS Mail shows the attachment as an icon at the bottom of the message. Neither client renders the PDF inline by default. The customer has to want to see the invoice. Most do not bother.

Spam scoring penalises attachments at scale. Marketing emails with PDF attachments are flagged disproportionately, because most legitimate transactional senders moved off PDF attachments years ago. Hitting Inbox or Promotions is partly determined by the absence of attachments. Replacing the PDF with an inline image moves you back into Inbox.

The fix that I tried first: generate the PDF, render its first page to a PNG with imagick, embed the PNG. This works. It also means you're now running both a PDF generator and a rasteriser in your image pipeline, with one feeding the other. The plumbing was twice as much code for half the design control.

The fix that stuck: skip the PDF, render the invoice template directly to a PNG.

The pattern

One Blade template per document type. One renderer service that handles all of them. One cache layer on S3 that serves repeat requests without a re-render.

namespace App\Services;

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Storage;

class TransactionalImageRenderer
{
    private const VIEWPORTS = [
        'invoice'      => ['w' => 1240, 'h' => 1754, 'view' => 'images.invoice'],
        'receipt'      => ['w' => 600,  'h' => 900,  'view' => 'images.receipt'],
        'voucher'      => ['w' => 1200, 'h' => 600,  'view' => 'images.voucher'],
        'product-card' => ['w' => 1200, 'h' => 630,  'view' => 'images.product'],
    ];

    public function render(string $type, array $data): string
    {
        $config = self::VIEWPORTS[$type];
        $key = $this->cacheKey($type, $data);

        if (Storage::disk('s3')->exists($key)) {
            return Storage::disk('s3')->url($key);
        }

        $html = view($config['view'], $data)->render();

        $res = Http::withHeaders(['X-API-Key' => config('services.html2img.key')])
            ->post('https://app.html2img.com/api/html', [
                'html' => $html,
                'width' => $config['w'],
                'height' => $config['h'],
                'wait_for_selector' => '.ready',
            ])->throw()->json();

        $bytes = Http::get($res['url'])->throw()->body();
        Storage::disk('s3')->put($key, $bytes, 'public');

        return Storage::disk('s3')->url($key);
    }

    private function cacheKey(string $type, array $data): string
    {
        ksort($data);
        $hash = md5(json_encode([...$data, '_type' => $type, '_v' => '1']));
        return "tx-images/{$type}/{$hash}.png";
    }
}

A few things worth highlighting. The cache hits S3 first. If the image exists for this exact payload, it returns the URL immediately. No API call, no credit spent. The vast majority of calls become hits once the system has warmed up, because the same invoice gets re-rendered every time the customer or our support team opens the original email.

The wait_for_selector: '.ready' is a convention I picked up after a few rendered images shipped with the font in the fallback state. Add a <div class="ready"> to the bottom of every template, after the last meaningful element. The screenshot fires once that div is in the DOM, which guarantees everything above it has rendered. Cleaner than picking a content-specific selector per template.

The Mailable side is straightforward:

class OrderInvoiceMail extends Mailable
{
    public function __construct(public Order $order) {}

    public function build()
    {
        $invoiceUrl = app(TransactionalImageRenderer::class)->render('invoice', [
            'reference' => $this->order->reference,
            'issued_on' => $this->order->created_at->format('jS F Y'),
            'lines'     => $this->order->lines->toArray(),
            'total'     => $this->order->total,
            // ...
        ]);

        return $this->view('emails.order-invoice', ['invoice_url' => $invoiceUrl])
            ->subject("Your invoice from Coastline Coffee Co");
    }
}

In the email view, the invoice is a plain <img> tag pointing at the URL on our CDN. No attachment, no withAttachment, no PDF library.

What changed in the numbers

Mobile open-to-action rate (customers who tapped to view the invoice on mobile) went from 14% to 89%. The latter is essentially everyone who opened the email, because they didn't need to do anything to see the invoice.

Email size dropped from an average 198 KB to 67 KB. Send time per batch dropped proportionally.

Spam score (we use Postmark, which scores 0 to 10) dropped from a stable 1.2 to 0.4. Deliverability into the Inbox tab on Gmail, measured via the seed-list panel, went from 81% to 94%.

These numbers are specific to our setup and our send volume (high transactional, very low marketing). Your mileage will differ. The direction has been consistent across the three companies I have seen do this migration.

The four document types

The same renderer covers four template shapes. Each has a viewport, a Blade view, and a cache key. The data shape is different per type but the plumbing is identical.

Invoice at 1240 by 1754. A4 portrait. Full line items, totals, party details. Heaviest template. If you'd rather not maintain the HTML, there's a pre-built invoice template at the same dimensions.

Receipt at 600 by 900. A compact summary, just enough for an order confirmation. Pre-built version: receipt template.

Voucher at 1200 by 600. The code, expiry, terms, brand colour. Goes into marketing emails. Pre-built: coupon voucher.

Product card at 1200 by 630. Product photo, name, price, optional sale price. Used in abandoned-cart emails. Pre-built: product card.

If you go the pre-built route, the renderer becomes even shorter because you skip the Blade view and the wait selector. You POST JSON to the template endpoint, the response is your PNG URL. The trade-off is the layout is opinionated.

Gotchas

The list of things I wish I'd known.

Mobile email clients clip wide images. Most clients render the image at the email's content width (usually 600px on mobile). A 1200-wide voucher scales down cleanly. A 1240-wide invoice scales down too small to read. Use the preview-plus-link pattern for anything wider than 1000px: a smaller preview image inline, a "view full invoice" link to the full-size image on your CDN.

Tabular numerals. Without font-variant-numeric: tabular-nums on your money columns, numbers shift left and right row to row. Looks wrong in a way you can't quite name until you fix it. One CSS line, immediate improvement.

Currency formatting. number_format($amount, 2) is fine for GBP and USD. If you support more than one currency, use NumberFormatter from the Intl extension. The bug is when you display "£1,234.56" for everyone including the customer paying in EUR.

Compliance. If your invoices need a stable PDF for accounting or audit reasons, the PNG-in-email pattern complements the PDF, it doesn't fully replace it. Generate both: the PNG goes in the email body, the PDF lives in the customer's account or in your finance system. Most tax authorities still expect the PDF; tax authorities are not who reads the email.

The S3 cache is the system of record. The upstream API gives you a URL on its CDN. Tempting to just use that URL in the email. We did, then ran into a 90-minute outage where every old invoice link suddenly 404'd. The fix is to fetch the bytes once at render time and persist to your own storage. Treat the upstream URL as a one-shot handle, not a permanent address.

When this is the wrong approach

Two cases where the PDF attachment is still right.

Markets where customers print every invoice. PDFs at print-quality DPI are a better fit than PNGs, which are fixed-resolution. For B2B sales in regulated industries, the PDF attachment is still the norm and customers expect it.

Strict data residency. If your invoice contains PII that can't leave your infrastructure, an API renderer is a third-party processor. The render request and the resulting bytes flow through a third party. The API doesn't persist your HTML, but if your compliance team has a "no third-party processors for PII" rule, you generate the PDF locally and live with the attachment.

Outside of those two, the pattern has been the lowest-friction win for transactional email work I've made in years. The first version took an afternoon. The maintenance cost is roughly zero, because there is no Chromium and no PDF library to keep happy. Replacing a working PDF pipeline with this is a half-day refactor for the average application.

Worth the half-day.

One API, every social image - dynamic OG, Twitter, LinkedIn, Pinterest, YouTube

Accreditly — Tue, 26 May 2026 13:23:00 +0000

We were shipping one OG image per post. It was 1200 by 630. It was rendered server-side from a Blade template via Puppeteer. We were quite pleased with it.

Then someone in growth pointed out that the same image looked terrible on LinkedIn (cropped weirdly), unremarkable on Twitter (where 1200 by 675 actually shows in full), and tiny on Pinterest (where the feed is a vertical aspect ratio). The fix on paper was simple: make per-platform variants. The fix in practice was a fortnight of getting Puppeteer to behave at eight different viewport sizes.

This article is about the version that came after that. One HTML template, eight platform variants, the API runs the browser. No Chromium to maintain. Worth posting because the fan-out pattern is reusable and quite a lot smaller than what I was carrying before.

Why one shared image is not enough

The reflex is to ship a single 1200 by 630 and let each platform crop. That gets you 70% of the way there and looks fine. The reason teams that care about share traffic go further is that each platform has its own pathology:

OG / Facebook: 1200 by 630. Title in the centre, brand in a corner. Standard landscape.
Twitter / X: 1200 by 675 for summary_large_image. Slightly taller than OG. A 1200 by 630 image works but leaves a thin grey bar.
LinkedIn: 1200 by 627. Functionally identical to OG, but the comment overlay covers the bottom 80px on mobile. Anything at the bottom is invisible.
Pinterest: 1000 by 1500. Vertical. Completely different design problem. You have room for the title, key points, and a call to action.
Instagram square: 1080 by 1080. Title can be larger because the safe area is huge.
Instagram story: 1080 by 1920. Vertical. The top 200px is hidden by the username overlay, the bottom 250px by the reply bar. Real estate is the middle slab.
YouTube thumbnail: 1280 by 720. Bold, high contrast, big title. Different conventions to a blog OG. A blog post that gets shared into all of those wants eight images, sized correctly, generated from the same content. Building eight Puppeteer templates is a lot of work. Building one HTML template and rendering it at eight viewports is not.

The fan-out pattern

The principle: one HTML template, made flexible enough to render at three orientation modes (landscape, square, portrait), called by an API that handles the viewport per platform.

Here is the shape of a job that does this for a blog post. Laravel version:

public const PLATFORMS = [
    'og'        => ['w' => 1200, 'h' => 630],
    'twitter'   => ['w' => 1200, 'h' => 675],
    'linkedin'  => ['w' => 1200, 'h' => 627],
    'facebook'  => ['w' => 1200, 'h' => 630],
    'pinterest' => ['w' => 1000, 'h' => 1500],
    'square'    => ['w' => 1080, 'h' => 1080],
    'story'     => ['w' => 1080, 'h' => 1920],
    'youtube'   => ['w' => 1280, 'h' => 720],
];

public function handle(): void
{
    foreach (self::PLATFORMS as $name => $size) {
        $html = view('social.post', [
            'post' => $this->post,
            'orientation' => $this->orientationFor($size),
        ])->render();

        $response = Http::withHeaders(['X-API-Key' => config('services.html2img.key')])
            ->post('https://app.html2img.com/api/html', [
                'html' => $html,
                'width' => $size['w'],
                'height' => $size['h'],
                'wait_for_selector' => '.title',
            ])
            ->throw()
            ->json();

        $this->post->socialImages()->updateOrCreate(
            ['platform' => $name],
            ['url' => $response['url']],
        );
    }
}

Node version, same shape:

const PLATFORMS = {
  og:        { w: 1200, h: 630 },
  twitter:   { w: 1200, h: 675 },
  linkedin:  { w: 1200, h: 627 },
  facebook:  { w: 1200, h: 630 },
  pinterest: { w: 1000, h: 1500 },
  square:    { w: 1080, h: 1080 },
  story:     { w: 1080, h: 1920 },
  youtube:   { w: 1280, h: 720 },
};

async function generateAll(post) {
  const results = {};
  for (const [name, size] of Object.entries(PLATFORMS)) {
    const html = renderTemplate(post, orientationFor(size));
    const res = await fetch('https://app.html2img.com/api/html', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': process.env.HTML2IMG_KEY,
      },
      body: JSON.stringify({
        html,
        width: size.w,
        height: size.h,
        wait_for_selector: '.title',
      }),
    });
    if (!res.ok) throw new Error(`render failed for ${name}: ${res.status}`);
    const { url } = await res.json();
    results[name] = url;
  }
  return results;
}

Eight platforms, sequentially, in roughly 15 seconds total. If you want it faster, fire the requests in parallel with a concurrency limit of 3 to 5 (any higher and you start rate-limiting).

The template that handles three orientations

This is the bit that took the longest to get right. The same HTML has to read cleanly at 1200 by 630, 1080 by 1080, and 1080 by 1920. The trick is 100vw/100vh on the body, plus orientation-aware font sizing.

<!doctype html>
<html>
<head>
<meta charset="utf-8">
<style>
  @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;700;900&display=swap');
  * { margin: 0; padding: 0; box-sizing: border-box; }
  body {
    width: 100vw; height: 100vh;
    background: linear-gradient(135deg, #0B1220 0%, #1E293B 100%);
    color: #fff;
    font-family: Inter, sans-serif;
    padding: 80px;
    display: grid;
    grid-template-rows: auto 1fr auto;
  }
  .kicker {
    font-size: 20px;
    color: #F59E0B;
    font-weight: 700;
    text-transform: uppercase;
    letter-spacing: 2px;
  }
  .title {
    font-size: 60px;
    font-weight: 900;
    line-height: 1.05;
    align-self: center;
    max-width: 920px;
  }
  body[data-orientation="square"] .title { font-size: 64px; }
  body[data-orientation="portrait"] .title { font-size: 72px; }
  body[data-orientation="portrait"] .kicker { font-size: 24px; }
  .footer {
    font-size: 22px;
    color: #94A3B8;
    display: flex;
    justify-content: space-between;
    align-items: end;
  }
  .footer strong { color: #fff; font-weight: 700; }
</style>
</head>
<body data-orientation="{{orientation}}">
  <div class="kicker">{{category}}</div>
  <div class="title">{{title}}</div>
  <div class="footer">
    <span><strong>{{author}}</strong> · {{published_at}}</span>
    <span>yourdomain.example</span>
  </div>
</body>
</html>

The data-orientation attribute is the only thing that changes between calls. Three CSS selectors handle the three modes. The grid layout keeps the kicker at the top, the title vertically centred, and the footer at the bottom, no matter the viewport.

There is also a per-platform template approach where you don't write the HTML at all. The html2img per-platform templates cover every social size individually (OG, Twitter, LinkedIn, Pinterest, Instagram square, Instagram story, YouTube, Facebook). Same JSON payload shape, different endpoint per platform. Useful if your branding is settled and you don't want to maintain layout code.

Gotchas

The list that made me wish I'd known earlier.

wait_for_selector matters more than you'd think. Without it, the screenshot occasionally fires before the webfont has loaded and you get a fallback render. The selector should match an element that only renders once the font is in. Setting it to .title works because the title element gets its visible width from the loaded font.

Inline your brand assets. External image references slow the render and occasionally fail. Logos as inline SVG, avatars as base64 data URIs, hero images either inlined or pre-uploaded to your own fast CDN.

Cache by content hash. The naive cache key is the post ID, but if the title changes the existing image is stale. Hash the inputs:

$cacheKey = md5(json_encode([
    'title' => $post->title,
    'author' => $post->author,
    'platform' => $platform,
    'v' => '2',
]));

Bumping the v field is your manual cache bust when the template design changes.

Persist the bytes, not the upstream URL. The API returns a hosted CDN URL. Convenient. But for compliance and the case where the upstream has an outage, fetch the bytes once and serve from your own storage. Treat the upstream URL as a one-shot handle, not the system of record.

LinkedIn overlays the bottom 80px on mobile. Don't put critical content there. The .footer in the template above is fine because it's brand metadata, not the message itself.

Don't try to use the same image for the Instagram story. A landscape card stretched portrait reads badly. The orientation switch in the template gives you a portrait layout with title at the top and brand at the bottom, which is the only way a 1080 by 1920 looks intentional.

Closing the loop in your meta tags

The render side is half the work. The other half is your HTML head, which has to point each platform at the right variant.

<head>
  <meta property="og:image" content="https://yourcdn.example/social/{{slug}}/og.png">
  <meta property="og:image:width" content="1200">
  <meta property="og:image:height" content="630">

  <meta name="twitter:card" content="summary_large_image">
  <meta name="twitter:image" content="https://yourcdn.example/social/{{slug}}/twitter.png">

  <!-- LinkedIn reads og:image -->

  <!-- Pinterest reads og:image but you can also expose the pin variant
       as a direct URL for the Pin button -->
  <link rel="alternate" type="image/png"
        href="https://yourcdn.example/social/{{slug}}/pinterest.png"
        title="Pin this">
</head>

Instagram, YouTube and the in-feed Twitter/X variants are not driven by meta tags. You upload them directly to those platforms (or hand them to the marketing team to upload).

The honest verdict

If your team publishes daily and shares to more than one platform, the fan-out approach earns its keep within a couple of weeks. Building it took roughly half a day from "I should do this" to "all eight variants ship per post". Maintaining it has been free. Owning Chromium for the same job was a fortnightly small-fire situation.

If you're publishing once a week, this is over-engineering. Stay with one 1200 by 630 and a Figma file.

The same pattern works for product cards on an e-commerce site, share images for user-generated content (think Strava-style activity cards), and the per-episode covers for a podcast network. The viewport list changes, the rest of the code stays the same.

Chart.js Server-Side Rendering as Images (Python Guide)

Accreditly — Thu, 07 May 2026 10:47:00 +0000

I needed weekly performance reports emailed to clients. Each report had four charts: revenue trend, conversion rate, top products, traffic sources. The app was Python. The charts on the live dashboard were Chart.js because that's what the frontend team had standardised on, and they looked good.

First attempt was matplotlib. It produced charts. They looked like matplotlib charts, which is to say fine for a scientific paper and terrible for a client email that's supposed to match the product's visual language. The brand colours were approximate. The fonts were wrong. The legend looked like it was from 2008. Clients politely asked why the emailed reports didn't match the dashboard.

Second attempt was chartjs-node-canvas. This works by running Chart.js against a Node canvas polyfill. Close to the real thing, but not identical. Gradients rendered differently. Some plugins didn't work at all. And now I was running a Node service from Python for one specific job, which felt wrong.

What actually solved it was Chart.js server-side rendering, where "server-side" means a real browser on someone else's server. I generate the HTML for the chart, including the Chart.js script tag and the config, post it to a rendering API, and get back a PNG that matches what the dashboard shows exactly, because it's the same Chart.js code running in the same browser engine. This article is how I set that up from Python, and the small details that make the difference between a chart that looks right and one that doesn't.

Why the obvious Python chart options fall short

Matplotlib and Plotly both generate images natively from Python. They're fine tools. The problem is that if your product uses Chart.js (or D3, or Recharts, or ApexCharts) on the frontend, and you want emailed or PDF-embedded charts to match, you're re-implementing the same visual twice in two different libraries. Colours drift. Fonts drift. Tooltip styling is irrelevant for a static image but the overall look and feel stops matching.

Plotly can export as a PNG via its kaleido backend, which is better, but you're still maintaining two chart implementations. Any change to the dashboard's chart styling means a matching change to the Python-side Plotly code, and keeping those in sync is a perennial source of bugs.

chartjs-node-canvas gets you one library, but at the cost of running Node from Python and accepting that canvas-polyfill rendering isn't pixel-perfect against real browser canvas. Gradients, shadows, and certain plugin behaviours differ. For anything that'll sit next to the "real" chart in a client's inbox, close-but-not-quite is worse than obviously-different.

The approach that actually gives you matching output is to render the chart in a real Chromium instance. Chart.js draws to a canvas, you screenshot the canvas, done. Running that browser yourself brings all the Puppeteer-on-a-server problems: binary size, version drift, memory. Pointing at an API that does it for you removes the problem entirely.

The setup

Here's a working Python function that takes a chart config and returns PNG bytes. The chart config is a plain dict that matches Chart.js's config shape, which means you can either write it by hand in Python or fetch it from wherever your frontend gets its config from and reuse it directly.

import os
import json
import requests

HTML2IMG_URL = "https://api.html2img.com/v1/render"
API_KEY = os.environ["HTML2IMG_API_KEY"]

def render_chart(config: dict, width: int = 800, height: int = 450) -> bytes:
    """Render a Chart.js config as PNG bytes."""
    html = f"""
    <!DOCTYPE html>
    <html>
    <head>
      <meta charset="utf-8">
      <style>
        html, body {{ margin: 0; padding: 0; background: white; }}
        body {{
          width: {width}px;
          height: {height}px;
          font-family: -apple-system, "Segoe UI", system-ui, sans-serif;
          padding: 24px;
        }}
        #chart {{ width: 100%; height: 100%; }}
      </style>
      <script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.0/dist/chart.umd.min.js"></script>
    </head>
    <body>
      <canvas id="chart"></canvas>
      <script>
        const ctx = document.getElementById('chart').getContext('2d');
        const config = {json.dumps(config)};
        config.options = config.options || {{}};
        config.options.animation = false;
        config.options.responsive = false;
        config.options.maintainAspectRatio = false;
        const chart = new Chart(ctx, config);
        window.__chartReady = true;
      </script>
    </body>
    </html>
    """

    response = requests.post(
        HTML2IMG_URL,
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "html": html,
            "viewport_width": width + 48,
            "viewport_height": height + 48,
            "device_scale_factor": 2,
            "wait_for_selector": "#chart",
            "ms_delay": 400,
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.content

Three things in that HTML are worth calling out because they're the difference between a chart that renders and one that doesn't.

animation = false disables Chart.js's entrance animation. The screenshot fires as soon as the chart is ready, and you don't want to capture it mid-fade-in. responsive = false and maintainAspectRatio = false force the chart to use the exact canvas size you set, rather than trying to resize relative to its container. ms_delay: 400 gives Chart.js a moment to finish drawing after the canvas appears in the DOM. You could be more precise by having the page set a sentinel element when the chart is drawn and waiting for that selector, but a small delay is usually sufficient.

Now using it for a revenue trend chart:

revenue_config = {
    "type": "line",
    "data": {
        "labels": ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug"],
        "datasets": [{
            "label": "Revenue",
            "data": [42000, 48500, 51200, 55800, 61300, 68900, 72400, 79200],
            "borderColor": "#6366f1",
            "backgroundColor": "rgba(99, 102, 241, 0.12)",
            "fill": True,
            "tension": 0.35,
            "pointBackgroundColor": "#6366f1",
            "pointRadius": 4,
            "borderWidth": 3,
        }],
    },
    "options": {
        "plugins": {
            "legend": {"display": False},
            "title": {
                "display": True,
                "text": "Monthly Revenue",
                "font": {"size": 18, "weight": "700"},
                "color": "#0f172a",
                "align": "start",
                "padding": {"bottom": 20},
            },
        },
        "scales": {
            "y": {
                "beginAtZero": False,
                "grid": {"color": "#f1f5f9"},
                "ticks": {
                    "color": "#64748b",
                    "callback": "function(v) { return '£' + (v/1000) + 'k'; }",
                },
            },
            "x": {
                "grid": {"display": False},
                "ticks": {"color": "#64748b"},
            },
        },
    },
}

png_bytes = render_chart(revenue_config, width=800, height=450)

with open("revenue.png", "wb") as f:
    f.write(png_bytes)

One wrinkle: the callback function for the y-axis ticks is expressed as a string. JSON can't hold JavaScript functions, so if you need them, you serialise the config, then have a post-processing step that replaces string function placeholders with real function literals. Here's a tiny helper that does that:

import re

def build_html_config(config: dict) -> str:
    """Serialise a config dict, unwrapping string-encoded JS functions."""
    json_str = json.dumps(config)
    # Match "function(...) { ... }" inside JSON strings and unquote them
    return re.sub(
        r'"(function\s*\([^)]*\)\s*\{[^}]*\})"',
        lambda m: m.group(1).replace('\\"', '"'),
        json_str,
    )

Then in the HTML template, replace JSON.stringify(config) with the output of build_html_config(config). For simple charts that don't need formatter callbacks, you can skip this and pass config straight through.

Below is what we're rendering:

Gotchas worth knowing

Chart.js versions matter. The config shape changed significantly between v2 and v3, and again in a smaller way for v4. Pin the CDN URL to a specific version so your server-side renders don't suddenly break when the chart library publishes a release. The example above pins to 4.4.0.

Canvas text rendering is affected by fonts being available at the time of draw. If your chart uses a custom font via font.family, that font needs to either be a system font, be loaded before Chart.js runs, or you accept a fallback. The cleanest pattern is to include @font-face in the <style> block and reference the same font both in CSS and in the Chart.js config. Then bump ms_delay to 500-700ms to be safe.

Plugins that need DOM interaction, like the chartjs-plugin-datalabels click handlers or zoom plugins, are irrelevant for a static image and should be omitted from the server-side config even if your frontend uses them. Anything that only affects hover or click state is wasted computation.

For reports with multiple charts, render them in parallel. The API calls are independent, so concurrent.futures.ThreadPoolExecutor with a handful of workers cuts report generation time substantially:

from concurrent.futures import ThreadPoolExecutor

configs = [revenue_config, conversion_config, products_config, traffic_config]

with ThreadPoolExecutor(max_workers=4) as pool:
    images = list(pool.map(render_chart, configs))

For truly bulk runs (hundreds of charts per report, or reports generated on a schedule for thousands of accounts), switch to the webhook pattern. You post each render with a webhook_url, the API calls your endpoint with the finished PNG, and you don't hold threads open waiting. For a weekly-report system, that's usually the right shape.

One last thing: don't inline base64 PNGs into emails if you can avoid it. Host the PNG somewhere (S3, a signed CDN URL, your own storage) and reference it in the email HTML. Email clients handle external images more reliably than inline attachments, and the email itself stays small.

The Python usage guide covers the requests setup and async alternatives. For more chart examples beyond Chart.js, including rendering D3 and custom canvas visualisations, the chart screenshot example has a few variants. And if you're building this into a larger reporting pipeline, the webhook documentation walks through the async flow.

The trick is just to let the real library do the drawing. Your dashboard's Chart.js code is already the canonical source of truth for what a chart looks like in your product. Reusing it server-side means you stop maintaining a second chart implementation, and your emails finally match your app.