DEV Community: Accreditly

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.

HTML Invoice to Image in Laravel

Accreditly — Tue, 05 May 2026 09:11:00 +0000

I've written invoice PDFs with DomPDF. I've written them with wkhtmltopdf via Snappy. Both work. Neither produces output I'd want a customer to see if I cared about how the thing looked. DomPDF's CSS support is stuck somewhere around 2012, and Snappy hands you a wkhtmltopdf binary that renders fonts like it's still running on Windows XP.

The specific thing that pushed me off both of them was a client who wanted their invoices to match their brand guide. Inter font, a specific hex for the accent colour, rounded corners on the total row, a subtle shadow under the line items, and a small logo top-left. DomPDF rendered the Inter font as Times New Roman. Snappy got the font right but broke the border-radius. Neither supported CSS grid, so the two-column header with billing and shipping addresses side-by-side needed a float hack that I didn't want to write in 2026.

What I actually wanted was to render a Laravel Blade template the way Chrome renders it, and get a PNG I could email, embed in a dashboard, or drop into a PDF later. This article is how I got there without putting a headless browser on my own server.

Why the usual Laravel invoice libraries fall short

The state of PHP PDF libraries is, to put it politely, historical. DomPDF is actively maintained but its rendering engine is a subset of CSS 2.1 with partial CSS 3 support, which means no flexbox, no grid, unreliable webfonts, and shadow/filter properties that either ignore you or crash the renderer. It works for "here is a table of numbers" output. It doesn't work when your design team has opinions.

Snappy (via wkhtmltopdf) rendered more faithfully for a while, but wkhtmltopdf itself was archived in 2023. It still runs. It's not getting updates. And even at its peak, its font rendering was noticeably different from Chrome, which matters because your designer previewed the template in Chrome.

The modern-feeling option is to run Puppeteer or Playwright from PHP via an exec call, or a service like Browsershot. This works, but now you're maintaining a Node.js install alongside your Laravel app, a Chromium binary, and you're exec'ing into it from PHP which is a category of bug I don't love debugging. Browsershot in particular is great software, but it's infrastructure you have to install, update, and keep working on every environment including your CI and your production containers.

The approach that got me out of this was to stop trying to render the invoice on my own infrastructure. Let the Blade template render to HTML the way it normally would. Post that HTML to an API. Get a PNG back. The invoice design lives entirely in Blade and CSS, same as any other Laravel view, and nothing about my server has to change.

The setup

I'll walk through a working implementation for a billing system that generates a PNG invoice when an order is marked as paid. The invoice has a header with company details, a line item table, a totals block, and a footer with payment terms. Everything you'd expect.

Start with the Blade template at resources/views/invoices/image.blade.php:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <style>
        @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;800&display=swap');
        * { box-sizing: border-box; margin: 0; padding: 0; }
        body {
            width: 800px;
            font-family: 'Inter', system-ui, sans-serif;
            padding: 64px;
            color: #0f172a;
            background: white;
        }
        header {
            display: grid;
            grid-template-columns: 1fr 1fr;
            gap: 32px;
            padding-bottom: 32px;
            border-bottom: 2px solid #0f172a;
        }
        .brand h1 { font-size: 28px; font-weight: 800; margin-bottom: 4px; }
        .brand .addr { font-size: 13px; color: #64748b; line-height: 1.6; }
        .meta { text-align: right; }
        .meta .label { font-size: 12px; text-transform: uppercase; letter-spacing: 2px; color: #94a3b8; }
        .meta .invoice-no { font-size: 32px; font-weight: 800; margin: 6px 0 16px; }
        .meta .dates { font-size: 13px; color: #475569; line-height: 1.8; }
        .bill-to { margin: 40px 0 24px; }
        .bill-to .label { font-size: 12px; text-transform: uppercase; letter-spacing: 2px; color: #94a3b8; margin-bottom: 8px; }
        .bill-to .name { font-size: 16px; font-weight: 600; }
        .bill-to .addr { font-size: 13px; color: #475569; line-height: 1.6; margin-top: 4px; }
        table { width: 100%; border-collapse: collapse; margin-top: 16px; }
        th { text-align: left; font-size: 12px; text-transform: uppercase; letter-spacing: 1.5px; color: #94a3b8; padding: 12px 0; border-bottom: 1px solid #e2e8f0; }
        th.right { text-align: right; }
        td { padding: 16px 0; border-bottom: 1px solid #f1f5f9; font-size: 14px; }
        td.right { text-align: right; }
        .totals { margin-top: 24px; display: flex; justify-content: flex-end; }
        .totals-inner { width: 300px; }
        .totals-row { display: flex; justify-content: space-between; padding: 8px 0; font-size: 14px; color: #475569; }
        .totals-row.total {
            margin-top: 12px; padding: 16px 20px;
            background: #0f172a; color: white;
            border-radius: 10px;
            font-size: 18px; font-weight: 800;
        }
        footer { margin-top: 48px; padding-top: 24px; border-top: 1px solid #e2e8f0; font-size: 12px; color: #64748b; line-height: 1.6; }
    </style>
</head>
<body>
    <header>
        <div class="brand">
            <h1>{{ $business['name'] }}</h1>
            <div class="addr">
                {{ $business['address'] }}<br>
                {{ $business['email'] }} - {{ $business['phone'] }}
            </div>
        </div>
        <div class="meta">
            <div class="label">Invoice</div>
            <div class="invoice-no">#{{ $invoice['number'] }}</div>
            <div class="dates">
                Issued {{ $invoice['issued_at'] }}<br>
                Due {{ $invoice['due_at'] }}
            </div>
        </div>
    </header>

    <div class="bill-to">
        <div class="label">Bill to</div>
        <div class="name">{{ $customer['name'] }}</div>
        <div class="addr">{{ $customer['address'] }}</div>
    </div>

    <table>
        <thead>
            <tr>
                <th>Description</th>
                <th class="right">Qty</th>
                <th class="right">Unit</th>
                <th class="right">Amount</th>
            </tr>
        </thead>
        <tbody>
            @foreach ($items as $item)
                <tr>
                    <td>{{ $item['description'] }}</td>
                    <td class="right">{{ $item['qty'] }}</td>
                    <td class="right">£{{ number_format($item['unit'], 2) }}</td>
                    <td class="right">£{{ number_format($item['qty'] * $item['unit'], 2) }}</td>
                </tr>
            @endforeach
        </tbody>
    </table>

    <div class="totals">
        <div class="totals-inner">
            <div class="totals-row"><span>Subtotal</span><span>£{{ number_format($totals['subtotal'], 2) }}</span></div>
            <div class="totals-row"><span>VAT ({{ $totals['vat_rate'] }}%)</span><span>£{{ number_format($totals['vat'], 2) }}</span></div>
            <div class="totals-row total"><span>Total</span><span>£{{ number_format($totals['total'], 2) }}</span></div>
        </div>
    </div>

    <footer>
        Payment due within 14 days. Bank transfer details on request.<br>
        {{ $business['name'] }} - Company no. {{ $business['company_no'] }}
    </footer>
</body>
</html>

Now a service class that takes a domain Invoice, renders the Blade template, posts it to the API, and returns the PNG bytes:

<?php

namespace App\Services;

use App\Models\Invoice;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\View;
use RuntimeException;

class InvoiceImageRenderer
{
    public function __construct(
        private readonly string $apiKey,
    ) {}

    public function render(Invoice $invoice): string
    {
        $html = View::make('invoices.image', [
            'business' => config('invoicing.business'),
            'customer' => [
                'name' => $invoice->customer->name,
                'address' => $invoice->customer->formatted_address,
            ],
            'invoice' => [
                'number' => $invoice->number,
                'issued_at' => $invoice->issued_at->format('j F Y'),
                'due_at' => $invoice->due_at->format('j F Y'),
            ],
            'items' => $invoice->items->map(fn ($i) => [
                'description' => $i->description,
                'qty' => $i->quantity,
                'unit' => $i->unit_price,
            ])->all(),
            'totals' => [
                'subtotal' => $invoice->subtotal,
                'vat_rate' => $invoice->vat_rate,
                'vat' => $invoice->vat_amount,
                'total' => $invoice->total,
            ],
        ])->render();

        $response = Http::withToken($this->apiKey)
            ->timeout(30)
            ->post('https://api.html2img.com/v1/render', [
                'html' => $html,
                'viewport_width' => 800,
                'viewport_height' => 1100,
                'device_scale_factor' => 2,
                'wait_for_selector' => '.totals-row.total',
                'full_page' => true,
            ]);

        if ($response->failed()) {
            throw new RuntimeException(
                "Invoice render failed: {$response->status()} {$response->body()}"
            );
        }

        return $response->body();
    }
}

Bind it in a service provider or resolve it directly:

$renderer = new InvoiceImageRenderer(config('services.html2img.key'));
$png = $renderer->render($invoice);

Storage::disk('s3')->put("invoices/{$invoice->number}.png", $png);

A few details in that render call worth pointing out. full_page: true is what makes this work for invoices specifically, because an invoice's height depends on how many line items it has, and you don't want to clip or stretch. The viewport width stays fixed at 800 (a comfortable reading width for a document), and the height becomes whatever the content needs. wait_for_selector: '.totals-row.total' ensures the render happens after the full content tree has mounted, which matters if the Google Font hasn't finished loading yet. device_scale_factor: 2 gives you a 1600-pixel-wide PNG that looks crisp when viewed on retina screens or printed.

Blade does the HTML escaping for you when you use {{ $var }}, so user-supplied data like customer names and addresses can't break the layout or inject markup. If you're pulling item descriptions from a rich-text source, use {!! $var !!} deliberately and only after you've sanitised it server-side.

Gotchas worth knowing

Fonts are the biggest source of surprise on first run. The @import inside the <style> block works, but adds a network round-trip inside the render. For a production pipeline that's generating thousands of invoices, either host the font file yourself and reference it via @font-face with a publicly reachable URL, or base64-encode the woff2 and inline it. The wait_for_selector option helps, but if your selector is visible before the font has swapped in, you still get a fallback for a brief moment. Adding a small ms_delay of 300-500ms on top of the selector wait is a reasonable belt-and-braces.

Numbers need locale-aware formatting. number_format() defaults to US conventions. For UK invoices I use number_format($amount, 2, '.', ','). For European invoices where the comma is the decimal separator, switch the arguments. Getting this wrong in production is embarrassing.

Don't render invoices synchronously inside a web request if you can avoid it. Queue it. Laravel's job system handles this naturally, and the API supports webhooks if you want the render itself to be asynchronous and get notified when it's done. For batch runs, the webhook flow is substantially faster because you're not blocking on each render.

One operational note: version your invoice template. When you change the design, old invoices that get re-rendered will look different from their original version, which can cause accounting confusion. Either snapshot the rendered PNG to S3 at generation time and serve that, or include a template_version column on the invoice and pick the right Blade view based on it. I do the former.

The Laravel usage guide covers the framework integration in more depth, including the HTTP client setup and how to test the renderer without hitting the API. For longer documents or batch work, the webhook parameter docs walk through the async pattern. And if you want more examples of document-style templates beyond invoices, the invoice and receipt example has a few variants.

Render the view, post the HTML, save the PNG. Your Blade template is the source of truth for what the invoice looks like, the same way it's the source of truth for the rest of your app.

Replacing Puppeteer on AWS Lambda for Screenshots

Accreditly — Thu, 30 Apr 2026 08:44:00 +0000

My chrome-aws-lambda function had been running fine for about eight months. Then Chrome shipped a new major version, the pinned Chromium binary in my layer went stale, pages started rendering with missing fonts, and the Lambda cold starts crept from two seconds up to nearly nine. I spent a weekend rebuilding the layer, swapping to @sparticuz/chromium, and arguing with webpack about why puppeteer-core kept bundling things it shouldn't.

That was the third time in two years I'd done some version of that weekend. At that point I started seriously looking at Puppeteer Lambda alternatives, because the pattern was clear: running headless Chrome inside a 250MB function limit is a thing you can make work, but it's not a thing that stays working without active maintenance.

This article is about what I moved to instead. It's specifically for people who have a working Puppeteer-on-Lambda setup that's getting expensive to maintain, or who are about to build one and want to know if there's a less painful option. The short version: yes, and the trade-off is usually worth it.

Why Puppeteer on Lambda gets expensive to own

The problems compound. Individually none of them are deal-breakers, but together they chew through engineering time.

Lambda has a 250MB unzipped deployment size limit. A full Chromium binary is around 170MB compressed, more unzipped, so you're immediately using a Lambda layer or container image. Every project that needs screenshots now has infrastructure decisions to make before it renders a single pixel.

Chrome ships a new major version roughly every four weeks. chrome-aws-lambda famously stopped receiving updates, and its successor @sparticuz/chromium needs a matching puppeteer-core version. Mismatch them and pages render oddly, or not at all. I've had a deployment where screenshots of the same URL produced different results locally (using a Chrome 120 binary) versus on Lambda (pinned to 114), and spent half a day figuring out why a flexbox layout was collapsing only in production.

Cold starts are the user-facing tax. Booting a headless Chrome instance inside a Lambda container takes two to four seconds even on warm infrastructure, more if the binary has to be extracted from the layer first. You can keep functions warm, but that undoes some of the cost argument for serverless in the first place.

Memory is the quiet killer. Chrome's per-page memory footprint is unpredictable. A page with a complex JavaScript-rendered chart can briefly spike to 700MB. Your function runs fine on a 1024MB allocation ninety-five percent of the time, and then a specific URL causes an OOM and the whole invocation fails. You discover this in production.

None of these are bugs. They're the shape of the problem. Running a browser engine inside a serverless function is just an awkward fit, and the fit doesn't improve over time.

The alternative: treat the browser as an API

The pattern I settled on is to treat rendering as a third-party service rather than infrastructure I own. My Lambda function does what Lambdas are good at, which is receiving an event, doing some business logic, and making HTTP calls. When it needs an image, it posts to a rendering API and gets back a PNG. The browser lives somewhere else, maintained by someone whose entire job is keeping it running.

There are a few services that do this. I landed on html2img.com because its API accepts raw HTML directly, which matters when the thing I'm trying to screenshot is something I've generated server-side (invoices, social cards, receipts) rather than a public URL. For URL-based screenshots it also works fine, but the HTML-first path is what got me off Puppeteer.

The migration is mostly subtractive. You delete the Chromium layer, remove puppeteer-core from your dependencies, swap the browser-launching block for a fetch call, and your Lambda package size drops by about 80%.

Here's what we're going to be making:

What the replacement looks like in practice

Here's a before-and-after for a Lambda function that generates a receipt image when an order is placed. The before version uses @sparticuz/chromium and puppeteer-core. The after version uses fetch.

The Puppeteer version, trimmed for readability:

const chromium = require('@sparticuz/chromium');
const puppeteer = require('puppeteer-core');

exports.handler = async (event) => {
  const { order } = JSON.parse(event.body);
  const html = buildReceiptHtml(order);

  const browser = await puppeteer.launch({
    args: chromium.args,
    executablePath: await chromium.executablePath(),
    headless: chromium.headless,
  });

  try {
    const page = await browser.newPage();
    await page.setViewport({ width: 600, height: 800, deviceScaleFactor: 2 });
    await page.setContent(html, { waitUntil: 'networkidle0' });
    const png = await page.screenshot({ type: 'png' });

    return {
      statusCode: 200,
      headers: { 'Content-Type': 'image/png' },
      body: png.toString('base64'),
      isBase64Encoded: true,
    };
  } finally {
    await browser.close();
  }
};

This works. It's also 180MB of dependencies, takes three seconds to cold start, and will break the next time Chrome updates and you forget to bump the Chromium package.

The replacement:

exports.handler = async (event) => {
  const { order } = JSON.parse(event.body);
  const html = buildReceiptHtml(order);

  const response = await fetch('https://api.html2img.com/v1/render', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${process.env.HTML2IMG_API_KEY}`,
    },
    body: JSON.stringify({
      html,
      viewport_width: 600,
      viewport_height: 800,
      device_scale_factor: 2,
      wait_for_selector: '.total',
    }),
  });

  if (!response.ok) {
    const err = await response.text();
    throw new Error(`Render failed: ${response.status} ${err}`);
  }

  const png = Buffer.from(await response.arrayBuffer());

  return {
    statusCode: 200,
    headers: { 'Content-Type': 'image/png' },
    body: png.toString('base64'),
    isBase64Encoded: true,
  };
};

function buildReceiptHtml(order) {
  const rows = order.items.map(item => `
    <tr>
      <td>${escape(item.name)}</td>
      <td class="qty">${item.quantity}</td>
      <td class="price">£${item.price.toFixed(2)}</td>
    </tr>
  `).join('');

  return `
    <!DOCTYPE html>
    <html>
      <head>
        <style>
          body {
            width: 600px;
            font-family: -apple-system, system-ui, sans-serif;
            padding: 48px;
            color: #111;
          }
          h1 { font-size: 28px; margin-bottom: 8px; }
          .meta { color: #666; font-size: 14px; margin-bottom: 32px; }
          table { width: 100%; border-collapse: collapse; }
          td { padding: 12px 0; border-bottom: 1px solid #eee; font-size: 16px; }
          .qty, .price { text-align: right; }
          .total {
            margin-top: 24px;
            padding-top: 24px;
            border-top: 2px solid #111;
            font-size: 22px;
            font-weight: 700;
            display: flex;
            justify-content: space-between;
          }
          footer { margin-top: 48px; color: #888; font-size: 13px; }
        </style>
      </head>
      <body>
        <h1>${escape(order.businessName)}</h1>
        <div class="meta">Order #${order.id} - ${order.date}</div>
        <table><tbody>${rows}</tbody></table>
        <div class="total"><span>Total</span><span>£${order.total.toFixed(2)}</span></div>
        <footer>Thanks for your order.</footer>
      </body>
    </html>
  `;
}

function escape(str) {
  return String(str)
    .replace(/&/g, '&amp;')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;');
}

Same input, same output. No browser to boot, no layer to maintain, no Chromium version to track. The Lambda deployment is now just your handler code and whatever you were doing before the Puppeteer block, which in my case was about 40KB zipped.

A couple of things worth pointing out in the replacement. The wait_for_selector parameter tells the renderer to wait until .total exists in the DOM before capturing, which matters if your HTML has any client-side rendering or webfonts. device_scale_factor: 2 gives you a retina-quality PNG rendered into the specified viewport, which is typically what you want for anything that'll be displayed or printed. And escape is doing the job that page.setContent was implicitly doing for you before, which is preventing user-supplied data from breaking your HTML.

Gotchas worth knowing

The big behavioural difference is latency. An API call adds a round-trip that your in-Lambda Puppeteer didn't have. In practice this has been faster overall for me, because the cold start I was paying on Lambda was longer than the API round-trip, but it's worth measuring for your own workload. If you're doing thousands of renders synchronously inside a single request handler, you'll want to parallelise the API calls or use the webhook flow so the render happens asynchronously.

For anything bulk or latency-sensitive, the webhook pattern is worth knowing about. You post the HTML with a webhook_url parameter, get back a job ID immediately, and html2img posts the finished PNG to your webhook when it's done. Your Lambda returns in milliseconds, and a separate function handles the completed image. This is how I run anything that generates more than one image per invocation.

Error handling needs more thought than with Puppeteer, because you now have a network dependency. Wrap the fetch in a retry with backoff for 5xx responses. Log the response body on failure, not just the status code, because the API's error messages usually tell you exactly what's wrong (a missing selector, an HTML syntax error, a timeout). And make sure your function timeout is higher than the API's maximum render time plus a margin.

Finally, don't commit your API key. It reads as obvious advice but I've seen people check a key into a repo because their Lambda needs it at runtime and "it's just for a test." Use Parameter Store, Secrets Manager, or at minimum an environment variable set through the console, never a hardcoded literal.

The Node.js usage guide covers the full parameter surface, and the webhook documentation walks through the async flow if you're doing bulk work. If you're specifically migrating existing Puppeteer screenshot code, the parameters reference maps the Puppeteer options you're used to (viewport, wait conditions, full-page capture) to the equivalent API parameters.

Less infrastructure, fewer weekends lost to Chrome version drift, same PNGs out the other end. For any Lambda that currently boots a browser, that's a good trade.

Dynamic OG Images in Next.js Without @vercel/og (1,200 630)

Accreditly — Mon, 27 Apr 2026 08:42:29 +0000

I had a perfectly reasonable OG image template. Flexbox layout, custom font, a gradient background, a small CSS grid for a two-column footer with the author name and publish date. Worked in the browser. Looked great in Figma. Then I moved it into next/og and half of it disappeared.

No errors. No warnings. Satori, the renderer behind ImageResponse, just silently ignored the parts it doesn't support. CSS grid, gone. The calc() I was using for spacing, ignored. A CSS variable for the brand colour, treated as an unknown value. The fallback rendered, which was worse than if it had thrown, because I didn't notice until someone shared the link on Slack and the preview was visibly broken.

If you've been building dynamic OG images in Next.js and hit the same wall, this article is about the other way to do it: rendering your template in an actual browser via an API, and serving the resulting PNG from your opengraph-image route. Same developer ergonomics, no CSS subset to memorise, and your template is literally just HTML and CSS that renders the way you'd expect.

Why @vercel/og falls short once your template gets real

Satori is clever. It parses JSX, approximates a subset of CSS, and produces an SVG which then gets rasterised to PNG. For simple cards, a title over a solid background with one font, it's lovely. The problems show up when your designer hands you something that looks like an actual marketing asset.

Flexbox is supported. Grid is not. display: flex has to be set explicitly on every container, even <span>, because Satori's defaults aren't the browser's. Custom fonts have to be fetched inside the request handler and passed into ImageResponse, not loaded at module scope. The entire bundle, including fonts and any inlined imagery, has to stay under 500KB on Edge. CSS variables don't resolve. calc() doesn't compute. Box shadows work, mostly, until they don't.

You can work around all of this. I did, for a while. The problem is that every design tweak becomes a translation exercise. You're not writing CSS any more, you're writing the subset of CSS that Satori understands, and the feedback loop is slow because rendering happens at request time on Edge.

The alternative that I keep coming back to is rendering the template in a real Chromium instance. You write normal HTML and CSS, including grid, variables, custom fonts loaded with @font-face, animations you can freeze on a specific frame if you want, anything. Then you screenshot it at 1200×630 and serve the PNG. The only question is where that Chromium lives.

Running Puppeteer yourself on Vercel or AWS Lambda is possible but tedious. The chromium binary is too large for the default Lambda size limit, so you end up on @sparticuz/chromium or a layer, watching memory usage, dealing with cold starts, pinning versions when Chrome updates break things. For an OG image pipeline that has to work reliably every time someone shares a link, I'd rather not own that problem. An API that takes HTML and gives you back a PNG cuts out the whole category of infrastructure work.

The approach

The pattern is straightforward. In your route folder, you add an opengraph-image.tsx file (Next.js picks this up automatically and wires it to the right meta tag). Inside it, you build the HTML and CSS for the card using whatever data the route has access to, post it to the html2img API, and return the resulting PNG as the response.

Because Next.js caches OG image routes aggressively by default, you don't pay the API cost on every share. The image gets generated once per unique URL and then served from the framework's cache. If your content changes, you bust the cache the same way you'd bust any route cache.

Building the thing in Next.js

Here's a working implementation for a blog where each post has its own OG image with the title, author, publish date, and category.

Here's what we're going to be making:

Looks great, right?

I'm using the App Router. If you're on Pages Router, the same idea works inside an API route, you just return the bytes yourself.

Inside the post route folder, app/posts/[slug]/opengraph-image.tsx:

import { getPostBySlug } from '@/lib/posts';

export const size = { width: 1200, height: 630 };
export const contentType = 'image/png';

export default async function OpengraphImage({
  params,
}: {
  params: { slug: string };
}) {
  const post = await getPostBySlug(params.slug);

  const html = `
    <!DOCTYPE html>
    <html>
      <head>
        <style>
          @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;700;900&display=swap');
          :root {
            --brand: #0b1220;
            --accent: #f59e0b;
            --muted: #94a3b8;
          }
          * { box-sizing: border-box; margin: 0; padding: 0; }
          body {
            width: 1200px;
            height: 630px;
            background: linear-gradient(135deg, var(--brand) 0%, #1e293b 100%);
            font-family: 'Inter', system-ui, sans-serif;
            color: white;
            padding: 80px;
            display: grid;
            grid-template-rows: auto 1fr auto;
          }
          .category {
            font-size: 20px;
            font-weight: 700;
            color: var(--accent);
            text-transform: uppercase;
            letter-spacing: 2px;
          }
          h1 {
            font-size: 68px;
            font-weight: 900;
            line-height: 1.1;
            align-self: center;
            max-width: 900px;
          }
          footer {
            display: grid;
            grid-template-columns: 1fr auto;
            align-items: end;
            color: var(--muted);
            font-size: 22px;
          }
          .author { color: white; font-weight: 700; }
        </style>
      </head>
      <body>
        <div class="category">${escapeHtml(post.category)}</div>
        <h1>${escapeHtml(post.title)}</h1>
        <footer>
          <div><span class="author">${escapeHtml(post.author)}</span> - ${post.publishedAt}</div>
          <div>yourdomain.com</div>
        </footer>
      </body>
    </html>
  `;

  const response = await fetch('https://api.html2img.com/v1/render', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${process.env.HTML2IMG_API_KEY}`,
    },
    body: JSON.stringify({
      html,
      viewport_width: 1200,
      viewport_height: 630,
      device_scale_factor: 2,
      wait_for_selector: 'h1',
    }),
  });

  if (!response.ok) {
    throw new Error(`html2img returned ${response.status}`);
  }

  const png = await response.arrayBuffer();

  return new Response(png, {
    headers: {
      'Content-Type': 'image/png',
      'Cache-Control': 'public, max-age=31536000, immutable',
    },
  });
}

function escapeHtml(str: string) {
  return str
    .replace(/&/g, '&amp;')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;')
    .replace(/"/g, '&quot;');
}

A few things worth pointing out. device_scale_factor: 2 gives you a retina-quality 2400×1260 PNG, which is what Twitter actually wants these days, rendered into the 1200×630 viewport. wait_for_selector: 'h1' makes sure the page has rendered the heading before the screenshot runs, which matters if you're pulling a font from Google Fonts. Without that wait, you can occasionally get an image where the font hasn't loaded yet and the fallback renders instead.

The escapeHtml helper is not optional. If someone's post title contains a quote character or an ampersand and you interpolate it into an HTML string without escaping, you get either a broken image or, depending on what you're rendering, a small HTML injection vector on your own server. Always escape.

Set your API key as an environment variable and you're done. Next.js will call this function when Twitter or LinkedIn or Slack hits /posts/my-post/opengraph-image.png, cache the result, and serve it from CDN on subsequent requests.

Gotchas I've hit

Fonts are the most common source of surprise. Google Fonts via @import works but adds a network round-trip inside the render. If latency matters to you, either use a system font stack, inline a @font-face with a base64-encoded woff2, or host the font on your own CDN. The wait_for_selector parameter helps, but if the selector appears before the font loads, you still get a fallback. For guaranteed results, add a small ms_delay on top.

Image assets inside the HTML need to be publicly accessible URLs. If your logo is behind auth, inline it as a base64 data URL instead. Same for any background images.

Caching is worth thinking about carefully. The Cache-Control: immutable header on the route is safe because Next.js gives each OG image route a unique URL per slug, but if your post content changes and you want the OG image to reflect that, you need to either include a content hash in the route or manually revalidate. I lean towards including a short hash of the title in the URL for content that might be edited.

Finally, error handling. If the API call fails, you don't want your share previews to break. Wrap the fetch in a try/catch and return a static fallback image on failure. A broken OG image is much worse than a generic one.

The framework-specific setup is covered in more detail in the html2img React and Next.js usage guide. If you want to see more template examples beyond blog cards, the product card and testimonial card examples are good starting points for social-share-style imagery. And for the full list of rendering parameters, including webhook support for async generation when you're batch-regenerating a lot of images, the parameters reference has the complete set.

Write the HTML the way you'd write any landing page, let a real browser render it, cache the output. That's the whole pattern.

How to use Tailwinds `safelist` to handle dynamic classes

Accreditly — Fri, 23 Aug 2024 09:25:00 +0000

Tailwind CSS is a popular utility-first CSS framework that allows developers to create custom designs quickly and efficiently. By default, Tailwind CSS generates a wide range of utility classes, which can lead to large file sizes. To address this issue, Tailwind CSS comes with a built-in feature called PurgeCSS that removes unused styles from the production build, making the final CSS file smaller and more performant. However, this automatic removal may sometimes cause issues when certain styles are used dynamically or conditionally in your application. In this article, we'll dive deep into the safelist feature in Tailwind CSS, learn how to whitelist specific styles, and explore various scenarios where using safelist can be helpful.

1. Understanding PurgeCSS in Tailwind CSS

PurgeCSS is a powerful tool that scans your project files for any class names used and removes the unused ones from the final CSS file. This significantly reduces the size of the generated CSS, making your application load faster.

By default, Tailwind CSS includes PurgeCSS configuration that scans your HTML, JavaScript, and Vue files for any class names. You can easily tweak what files are picked up within the content array of the config file.

In some situations, you might need to prevent specific styles from being removed, even if they're not detected in your files. This is where the safelist feature comes into play.

2. Introducing Safelist

Safelist is a feature in Tailwind CSS that allows you to whitelist certain styles so they don't get removed during the purging process. This is particularly useful when you have dynamic class names generated through JavaScript or applied based on user interaction. Another very common use-case for safelist is when colors or styles are driven from a CMS or backend framework. One such example might be a system that allows a website admin to edit the color of a category in a CMS, which in turn changes the color of the nav items for that category. Tailwind won't see the actual class name as the file will contain server-side code that outputs the color.

By adding these class names to the safelist, you ensure that they will always be included in your final CSS file, regardless of whether PurgeCSS can find them in your project files or not.

3. Configuring Safelist in `tailwind.config.js`

To configure the safelist in your Tailwind CSS project, you need to modify the tailwind.config.js file. The safelist is an array of class names that you want to keep in your final CSS file, even if they're not found in your project files. Here's an example of how to add class names to the safelist:

// tailwind.config.js
module.exports = {
  content: [
    // your content files here
  ],
  safelist: [
    'bg-red-500', 
    'text-white', 
    'hover:bg-red-700'
  ],  
  // other configurations
};

In this example, the bg-red-500, text-white, and hover:bg-red-700 classes are added to the safelist. These classes will always be included in your final CSS file, even if PurgeCSS doesn't find them in your project files.

4. More advanced configurations

If you have a lot of classes to manage within safelist, perhaps due to multiple colors and the need to support variants/modifiers such as :hover, :focus, :active and dark: then it can quickly become very challenging to manage these within safelist. The list will become huge very quickly.

That's where patterns come in. Tailwind support regex within the safelist:

safelist: [
  {
    pattern: /from-(blue|green|indigo|pink|orange|rose)-200/
  },
  {
    pattern: /to-(blue|green|indigo|pink|orange|rose)-100/,
  },
],

With these 2 entries we are effectively adding 12 classes. from-{color}-200 and to-{color}-100, where {color} is all of the colors in the list. It makes it much easier to manage the lists. Remember that tailwind.config.js is just a JavaScript file, so you can manage variables at the top of the file if you're managing lists of colors that are repeated heavily.

It's also possible to define variants for everything within the list without needing to explicitly list them in regex:

safelist: [
  {
    pattern: /text-(blue|green|indigo|pink|orange|rose)-(600|400)/,
    variants: ['hover'],
  },
  {
    pattern: /from-(blue|green|indigo|pink|orange|rose)-200/
  },
  {
    pattern: /to-(blue|green|indigo|pink|orange|rose)-100/,
  },
],

5. Safelist Examples and Use Cases

There are several scenarios where using the safelist feature can be helpful:

Dynamic class names: If you're generating class names dynamically based on some data or user input, PurgeCSS may not detect these classes and remove them from the final CSS file. By adding these dynamic classes to the safelist, you can ensure they're always available in your application.

// Example of a dynamic class name based on user input
const userInput = 'success'; // This value might come from an API or user input
const alertClass = `alert-${userInput}`;

// Generated class name: 'alert-success'

In this example, the alertClass variable generates a class name based on user input or data from an API. Since PurgeCSS can't detect this dynamic class name, you should add it to the safelist in your tailwind.config.js file.

Conditional styles: If you have styles that only apply under specific conditions, such as a dark mode or a mobile view, you can use the safelist to ensure those styles are always included in your final CSS file.

// Example of a conditional style based on a media query
@media (max-width: 767px) {
  .hidden-mobile {
    display: none;
  }
}

In this example, the hidden-mobile class is only applied when the viewport width is less than 768 pixels. Since this class might not be detected by PurgeCSS, you should add it to the safelist in your tailwind.config.js file.

6. Best Practices for Safelisting

When using the safelist feature in Tailwind CSS, keep the following best practices in mind:

Only add classes to the safelist that are truly necessary. Adding too many classes can bloat your final CSS file and negate the benefits of PurgeCSS.
If you have many dynamic class names or a complex application, consider using a function or regular expression to generate the safelist array. This can help keep your configuration cleaner and more maintainable.
Test your production build to ensure that all required styles are included. This can help you catch any issues early on and avoid surprises when deploying your application.

Summary

The safelist feature in Tailwind CSS provides a powerful way to whitelist specific styles and ensure they are included in your final CSS file, even if they are not detected by PurgeCSS. By understanding how to configure the safelist and use it effectively in various scenarios, you can make your Tailwind CSS projects more robust and maintainable. Remember to follow best practices when using the safelist to ensure your final CSS file remains lean and performant.

Feel free to look over the Tailwind Docs on Safelist usage.

DEV Community: Accreditly

How we generate code screenshots for socials

Why screenshotting the editor does not scale

The quick route: a browser tool for one-offs

The repeatable route: a code screenshot API

Wiring it into the publishing flow

Getting the screenshots to actually read on social

Which one we reach for

[Boost]

Dynamic OG Images in Rails

Use Laravel to create your own MCP server

Prerequisites

Step 1: Install the package

Step 2: Create a server

Step 3: Register the server

Step 4: Build a tool

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

Step 6: Tell the client how a tool behaves

Step 7: Add a resource and a prompt

Step 8: Secure the server

Step 9: Inspect and test it

Wrapping up

Dynamic OG Images in Rails

The three approaches

Approach 1: image libraries, and why they hurt

Approach 2: headless Chrome with Grover

Approach 3: render an ERB template through an API

Generating off the request path

Caching so you don't regenerate on every save

Wiring up the meta tags

Testing without hitting the API

Which to reach for

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

What was in the stack

The pattern

The brand partial

One format in full: the blog hero

The other four formats

Gotchas

When this is the wrong approach

Why we replaced PDF invoice attachments with inline PNG receipts

Why the PDF attachment is not great

The pattern

What changed in the numbers

The four document types

Gotchas

When this is the wrong approach

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

Why one shared image is not enough

The fan-out pattern

The template that handles three orientations

Gotchas

Closing the loop in your meta tags

The honest verdict

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

Why the obvious Python chart options fall short

The setup

Gotchas worth knowing

HTML Invoice to Image in Laravel

Why the usual Laravel invoice libraries fall short

The setup

Gotchas worth knowing

Replacing Puppeteer on AWS Lambda for Screenshots

Why Puppeteer on Lambda gets expensive to own

The alternative: treat the browser as an API

What the replacement looks like in practice

Gotchas worth knowing

Dynamic OG Images in Next.js Without @vercel/og (1,200 630)

Why @vercel/og falls short once your template gets real

The approach

Building the thing in Next.js

Gotchas I've hit

How to use Tailwinds `safelist` to handle dynamic classes

1. Understanding PurgeCSS in Tailwind CSS

2. Introducing Safelist

3. Configuring Safelist in tailwind.config.js

4. More advanced configurations

5. Safelist Examples and Use Cases

6. Best Practices for Safelisting

Summary

3. Configuring Safelist in `tailwind.config.js`