Forem: Accreditly

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.

Send email from WordPress the right way

Accreditly — Tue, 20 Aug 2024 09:14:46 +0000

Sending emails is a critical feature for many WordPress websites, whether it’s for account confirmations, notifications, or customized alerts. While many developers might default to using PHP’s mail() function, WordPress offers more robust and reliable alternatives. Let's explore the best practices for sending both plaintext and HTML emails within WordPress.

Why Avoid PHP’s `mail()` Function?

While PHP’s mail() function is straightforward, it has several drawbacks, particularly in terms of flexibility and reliability. It lacks support for SMTP authentication, which can lead to emails being flagged as spam. WordPress's built-in functions are designed to overcome these limitations, offering better formatting options and more consistent delivery rates.

Sending Plaintext Emails with WordPress

WordPress makes it easy to send plaintext emails using the wp_mail() function, which is more versatile than PHP’s native mail() function.

Here’s a basic example of how you can use wp_mail():

$recipient = 'user@example.com';
$subject = 'Welcome to Our Platform!';
$body = 'Thank you for joining us.';
wp_mail($recipient, $subject, $body);

If you need to add headers, such as a custom "From" address or "Reply-To," you can do so with an array:

$headers = array('From: Support Team <support@example.com>', 'Reply-To: support@example.com');
wp_mail($recipient, $subject, $body, $headers);

This approach ensures that your emails are sent with the correct headers, improving deliverability and reducing the likelihood of your emails being marked as spam.

Crafting HTML Emails in WordPress

If you want to send emails that are more visually engaging, such as newsletters or account information emails, HTML is the way to go. To send HTML emails in WordPress, you’ll need to set the content type to text/html. This can be achieved by using the wp_mail_content_type filter.

Here’s an example:

function set_html_mail_content_type() {
    return 'text/html';
}
add_filter('wp_mail_content_type', 'set_html_mail_content_type');

$recipient = 'user@example.com';
$subject = 'Your Account Information';
$body = '<html><body>';
$body .= '<h1>Welcome to Our Platform!</h1>';
$body .= '<p>Here are your account details.</p>';
$body .= '</body></html>';

wp_mail($recipient, $subject, $body);

// Reset content type to avoid affecting other emails
remove_filter('wp_mail_content_type', 'set_html_mail_content_type');

In this example, we first define a function to set the content type to HTML and then add it as a filter. After sending the email, the filter is removed to ensure that subsequent emails are not inadvertently sent as HTML.

For a more in-depth discussion on the best practices for sending emails from WordPress, including additional code examples and troubleshooting tips, check out our full article here.

Enhance Your WordPress Skills

If you're looking to deepen your understanding of WordPress, including how to handle email functionality more effectively, consider pursuing our WordPress Development Certification. It’s a comprehensive program designed to take your skills to the next level, covering everything from basic setup to advanced customization techniques.

The Differences Between "Test Coverage" and "Code Coverage"

Accreditly — Thu, 13 Jun 2024 08:06:54 +0000

As developers, we often hear terms like "test coverage" and "code coverage" thrown around in discussions about software quality. While they may sound similar, they represent different aspects of testing and development. Understanding the nuances between these two concepts is essential for improving code quality and ensuring robust software.

In this article, we’ll delve into what test coverage and code coverage mean, their importance, how they differ, and how you can effectively use them to enhance your development process.

Understanding Test Coverage

Test coverage is a metric that helps us understand how much of our application has been tested. It focuses on the completeness of the testing effort and is usually expressed as a percentage. Test coverage metrics can include:

Ensuring all user requirements have corresponding test cases, known as 'requirements coverage'.
Verifying that all functions or methods are tested, known as 'functional coverage'.
Confirming that every branch (e.g., if-else conditions) in the code has been tested, known as 'branch coverage'.

Why Test Coverage Matters

Test coverage helps identify untested parts of your application, pointing out areas that may need more thorough testing.
By ensuring all aspects of your application are tested, you can catch bugs early, leading to higher quality software.
High test coverage can give developers and stakeholders confidence that the application has been thoroughly vetted. This is especially true when introducing new developers to the project who may not understand some intricacies.

Measuring Test Coverage

Tools like JUnit for Java, NUnit for .NET, and pytest for Python, PHPUnit and the newer Pest for PHP provide features for measuring test coverage. These tools generate reports that show which parts of the application were executed during tests, helping developers identify untested sections.

Here's a simple example using pytest in Python:

# test_example.py

def add(a, b):
    return a + b

def test_add():
    assert add(1, 2) == 3
    assert add(-1, 1) == 0

# To run the test and measure coverage
# Use the following command:
# pytest --cov=.

The pytest-cov plugin generates a report showing the percentage of code covered by the tests.

Understanding Code Coverage

Code coverage, on the other hand, measures the extent to which your code has been executed. It's about ensuring that your codebase has been thoroughly exercised by tests. Key metrics for code coverage include:

The percentage of lines of code executed, known as 'line coverage'.
The percentage of executable statements run, known as 'statement coverage'.
The percentage of possible execution paths tested, known as 'path coverage'.
The percentage of functions executed, known as 'function coverage'.

Why Code Coverage Matters

Code coverage can help identify dead or redundant code that’s never executed, allowing you to clean up your codebase.
Well-covered code is often easier to maintain because it’s more likely to have fewer hidden bugs.
High code coverage ensures that changes or refactors don’t introduce new bugs since most paths and lines are tested.

Measuring Code Coverage

Popular tools for measuring code coverage include Istanbul for JavaScript, Jacoco for Java, and coverage.py for Python and PHPUnit (with XDebug, PCOV and phpdbg support) for PHP. These tools integrate with CI/CD pipelines to ensure continuous monitoring of code coverage.

Here's an example using coverage.py with a Python script:

# example.py

def multiply(a, b):
    return a * b

def divide(a, b):
    if b == 0:
        raise ValueError("Cannot divide by zero")
    return a / b

# test_example.py

import pytest
from example import multiply, divide

def test_multiply():
    assert multiply(2, 3) == 6

def test_divide():
    assert divide(10, 2) == 5
    with pytest.raises(ValueError):
        divide(10, 0)

# To run the coverage report
# Use the following command:
# coverage run -m pytest
# coverage report

The coverage tool will produce a report showing how much of the code has been executed during the tests.

Key Differences Between Test Coverage and Code Coverage

Focus

Test Coverage: Focuses on the extent to which the testing suite covers the application's functionality, requirements, and conditions.
Code Coverage: Concentrates on the extent to which the actual lines of code have been executed.

Measurement

Test Coverage: Measures how well the tests cover the requirements and functionality of the application.
Code Coverage: Measures how well the tests execute the code itself, identifying which lines or branches have been run.

Purpose

Test Coverage: Ensures all user scenarios and requirements are tested.
Code Coverage: Ensures the written code is exercised and validated, uncovering dead or untested code.

Using Test Coverage and Code Coverage Together

While both metrics provide valuable insights, relying solely on one can be misleading. High test coverage doesn't guarantee that all the code has been executed, and high code coverage doesn’t mean all functional requirements are tested. Combining both gives a more comprehensive view of your testing effectiveness.

Showing Off Coverage

If you run an open source project (or even closed source, I suppose), it is common to show badges on the README.md file of your project that show off the coverage of your project. Check out the very popular repo-badges GitHub repo for a bunch of examples.

Example Workflow

Write Tests: Write comprehensive tests covering all functional requirements and edge cases.
Measure Test Coverage: Use tools like pytest or JUnit to measure and report on test coverage.
Measure Code Coverage: Use tools like coverage.py or Istanbul to measure code execution.
Combine Reports: Analyze combined reports to ensure all aspects are covered.
Refactor and Improve: Refactor code and tests based on coverage insights to improve overall quality.

DRY: What is it and how to implement it. Don't Repeat Yourself

Accreditly — Tue, 07 May 2024 13:44:35 +0000

The DRY (Don't Repeat Yourself) principle is a key concept in software development that focuses on reducing code duplication and improving maintainability. By following the DRY principle, developers can create cleaner, more efficient, and less error-prone codebases. In this article, we will discuss the importance of the DRY principle and illustrate its application in JavaScript with two practical examples.

If you're looking for an example of writing DRY code then check out our article about safelist classes in Tailwind, which rewrites the ruleset to make them DRY.

Section 1: Understanding the DRY Principle

The DRY principle states that each piece of logic in a codebase should have a single, unambiguous representation. In other words, you should avoid duplicating code and extract repetitive parts into reusable components or functions. This approach ensures that when you need to make changes or fix bugs, you only have to do it in one place, making your code more maintainable and less prone to errors.

Section 2: Benefits of the DRY Principle

Improved maintainability: With less duplicated code, it is easier to understand, modify, and extend your codebase.
Reduced likelihood of bugs: By centralizing logic, you reduce the chances of introducing inconsistencies and errors when updating your code.
Enhanced readability: DRY code is generally more concise and easier to read, making it simpler for other developers to understand and work with your code.
Easier debugging: When logic is centralized, it's simpler to track down and fix issues, as you only need to investigate one location instead of multiple instances of the same logic.

Section 3: DRY Principle in JavaScript – Example 1

Consider the following code that calculates the price of items after applying a discount:

Before applying DRY:

function getPriceAfterDiscountA(price) {
  const discountA = 0.1;
  return price * (1 - discountA);
}

function getPriceAfterDiscountB(price) {
  const discountB = 0.2;
  return price * (1 - discountB);
}

console.log(getPriceAfterDiscountA(100)); // 90
console.log(getPriceAfterDiscountB(100)); // 80

In this example, we have two functions with nearly identical logic, except for the discount values. This code is repetitive and not DRY.

After applying DRY:

function applyDiscount(price, discount) {
  return price * (1 - discount);
}

function getPriceAfterDiscountA(price) {
  const discountA = 0.1;
  return applyDiscount(price, discountA);
}

function getPriceAfterDiscountB(price) {
  const discountB = 0.2;
  return applyDiscount(price, discountB);
}

console.log(getPriceAfterDiscountA(100)); // 90
console.log(getPriceAfterDiscountB(100)); // 80

We've extracted the common logic into an applyDiscount() function, which is now used by both getPriceAfterDiscountA() and getPriceAfterDiscountB(). This change makes our code DRY and more maintainable.

As an of maintainability, imagine we have 10 discounts instead of the 2 above, and we have a change to this code where we want to apply some kind of pre or post-tax discount across all available discounts. Using the original method we would have to make that change in 10 places, but in the DRY code we just change the applyDiscount function. The extra layer of abstraction will result in less code, less bugs, easier to read code and more maintainable code.

Section 4: DRY Principle in JavaScript – Example 2

Let's look at another example where we want to calculate the area of different shapes:

Before applying DRY:

function calculateCircleArea(radius) {
  return Math.PI * radius * radius;
}

function calculateRectangleArea(length, width) {
  return length * width;
}

function calculateTriangleArea(base, height) {
  return (base * height) / 2;
}

After applying DRY:

function calculateArea(shape, ...dimensions) {
  switch (shape) {
    case "circle":
      const [radius] = dimensions;
      return Math.PI * radius * radius;
    case "rectangle":
      const [length, width] = dimensions;
      return length * width;
    case "triangle":
      const [base, height] = dimensions;
      return (base * height) / 2;
    default:
      throw new Error("Invalid shape");
  }
}

console.log(calculateArea("circle", 5)); // 78.53981633974483
console.log(calculateArea("rectangle", 4, 6)); // 24
console.log(calculateArea("triangle", 3, 7)); // 10.5

In this example, we've extracted the logic for calculating the area of different shapes into a single calculateArea() function. This function takes the shape and its dimensions as arguments and uses a switch statement to determine the appropriate calculation. By doing so, we've made our code DRY and easier to maintain.

Conclusion:

Embracing the DRY principle in JavaScript is an essential practice for writing clean, maintainable, and efficient code. By identifying repetitive code patterns and extracting them into reusable functions, you can reduce the likelihood of bugs and make your codebase more readable and easier to understand. Remember to always be on the lookout for opportunities to apply the DRY principle in your projects, as doing so will significantly improve the quality of your code.

Please note: This article was originally posted on Accreditly, the home of web development certifications for PHP, JavaScript, WordPress and Database Design.

Don't nest ternary operators. Please!

Accreditly — Thu, 25 Jan 2024 13:27:00 +0000

In JavaScript, the ternary operator (also known as the "conditional operator") is a concise and handy tool for conditional logic. However, when it comes to nesting these operators, you might be stepping into a tangled web of complexity. Let's discuss why nesting ternaries can be problematic and explore alternative approaches for cleaner code.

Understanding Ternary Operators

A ternary operator in JavaScript is a one-liner alternative to an if-else statement. It takes three operands: a condition, a result upon the condition being true, and a result if it's false.

Syntax:

condition ? exprIfTrue : exprIfFalse;

Example:

let isAdult = age >= 18 ? 'Yes' : 'No';

The Temptation of Nesting Ternaries

Nesting ternary operators means using one ternary inside another. It's often seen as a shortcut to handle multiple conditions.

Example of Nested Ternaries:

let category = age > 18 ? (age > 65 ? 'Senior' : 'Adult') : 'Minor';

While this might seem like an efficient use of space, it introduces several issues.

1. Readability Concerns

Nested ternaries can quickly become hard to read and understand, especially for someone new to the code. What seems straightforward to you now might be a puzzle for future-you or other developers.

Hard-to-Read Example:

let message = user.isAuthenticated ? (user.hasPremium ? 'Welcome, premium user!' : 'Welcome, user!') : 'Please log in.';

2. Debugging Difficulties

Debugging nested ternaries can be challenging. Isolating which part of the ternary chain is causing an issue is more complex than debugging a simple if-else statement or a switch case.

3. Maintainability Issues

As your codebase grows and evolves, maintaining nested ternaries becomes problematic. Any modification might require a significant unraveling and reworking of the logic.

4. Performance Misconception

Some developers might think nesting ternaries is faster or more efficient. However, any performance gains are negligible and certainly not worth the trade-off in readability and maintainability.

Alternatives to Nested Ternaries

1. Simple If-Else Statements:

For clarity and ease of understanding, a traditional if-else structure is often best.


   let category;

   if (age > 18) {
       category = age > 65 ? 'Senior' : 'Adult';
   } else {
       category = 'Minor';
   }

2. Switch Statements:

For multiple conditions, a switch statement can be more readable.


   switch (true) {
       case age > 65:
           category = 'Senior';
           break;
       case age > 18:
           category = 'Adult';
           break;
       default:
           category = 'Minor';
   }

3. Function Abstraction:

Encapsulate complex logic in a function for better abstraction and reusability.


   function getCategory(age) {
       if (age > 65) return 'Senior';
       if (age > 18) return 'Adult';
       return 'Minor';
   }

While ternary operators are a useful feature of JavaScript, nesting them can lead to code that's hard to read, debug, and maintain. Opting for clearer, more straightforward alternatives like if-else statements, switch statements, or function abstraction makes your code more accessible and maintainable. Remember, in programming, clarity should almost always trump cleverness. Production code isn't code golf, shorter isn't always better.

How to use Generators in JavaScript

Accreditly — Fri, 10 Nov 2023 11:17:52 +0000

JavaScript, a language that has been consistently evolving, introduced a powerful feature in its ES6 (ECMAScript 2015) iteration: Generators. While they might seem daunting at first, generators are invaluable tools for handling asynchronous operations and creating custom iterable sequences. Let's unwrap the mystique behind JavaScript generators.

What Are Generators?

Generators are special functions in JavaScript that allow you to yield (or produce) multiple values on a per-request basis. They pause their execution when yielding a value and can resume from where they left off. This "pausing" capability makes generators versatile for many scenarios, particularly asynchronous tasks.

Basic Syntax of Generators

Generators are defined similarly to regular functions but with an asterisk (*). The yield keyword is used to produce a sequence of values.

function* myGenerator() {
  yield 'first value';
  yield 'second value';
  yield 'third value';
}

Using a Generator

To use a generator, you must first call it, which returns a generator object:

const gen = myGenerator();

This object follows the iterator protocol and has a next() method:

console.log(gen.next()); // { value: 'first value', done: false }
console.log(gen.next()); // { value: 'second value', done: false }
console.log(gen.next()); // { value: 'third value', done: false }
console.log(gen.next()); // { value: undefined, done: true }

Benefits of Generators

Unlike traditional functions that might build and return a huge array, generators produce values on the fly. This means you're not storing large data structures in memory.
Together with Promises, generators offer a smoother way to handle asynchronous operations. This synergy gave birth to async/await, which is essentially syntactic sugar over generators and promises.
Beyond producing a sequence of values, generators can be used to define custom iteration behaviors.

Yielding Other Generators

Generators can yield other generators, making them composable:

function* generatorA() {
  yield 'A1';
  yield 'A2';
}

function* generatorB() {
  yield* generatorA();
  yield 'B1';
}

const genB = generatorB();
console.log(genB.next()); // { value: 'A1', done: false }

Generators and Error Handling

You can handle errors in generators with try-catch blocks. If an error is thrown inside a generator, it will set the done property of the generator to true.

function* errorGenerator() {
  try {
    yield 'all good';
    throw new Error('Problem occurred');
  } catch (err) {
    yield err.message;
  }
}

Real-world Use Cases

Fetching chunks of data lazily, such as paginated API results or reading large files in segments.
Generating infinite sequences, like an endless series of unique IDs.
Pausing and resuming functions, allowing for more complex flow control.

Generators offer an alternative and often cleaner approach to handling asynchronous operations and generating sequences in JavaScript. While they've been somewhat overshadowed by the rise of async/await, understanding generators gives a deeper insight into the language's capabilities. With generators in your JS toolkit, you're better equipped to tackle a wider range of programming challenges.

Example: Lazy Loading of Data

Imagine you have an application that needs to load large sets of data from a server, like a list of products in an e-commerce site. Instead of loading all data at once, which can be inefficient and slow, you can use a generator to lazily load the data as needed.

Scenario:

You have an API endpoint that returns a list of products.
The API supports pagination, allowing you to fetch a limited number of products per request.
You want to display these products in batches on the user interface, loading more as the user scrolls.

JavaScript Generator Implementation:

function* dataFetcher(apiUrl, pageSize) {
  let offset = 0;
  let hasMoreData = true;

  while (hasMoreData) {
    const url = `${apiUrl}?limit=${pageSize}&offset=${offset}`;
    yield fetch(url)
      .then(response => response.json())
      .then(data => {
        if (data.length < pageSize) {
          hasMoreData = false;
        }
        offset += data.length;
        return data;
      });
  }
}

// Using the generator
const pageSize = 10;
const apiUrl = 'https://api.example.com/products';
const loader = dataFetcher(apiUrl, pageSize);

function loadMore() {
  const nextBatch = loader.next();
  nextBatch.value.then(products => {
    // Update UI with new batch of products
  });
}

// Initial load
loadMore();

// Subsequent loads, e.g., triggered by scrolling
window.addEventListener('scroll', () => {
  // Load more data when the user scrolls down
  loadMore();
});

Example: Multi-Step Form Navigation

In a web application, you might have a multi-step form where the user needs to complete several steps in sequence. Using a generator, you can create a smooth and controlled navigation flow through these steps.

Scenario:

The application has a form divided into multiple steps (e.g., personal details, address information, payment details).
The user should be able to move forward and backward between steps.
The application should keep track of the current step and display it accordingly.

JavaScript Generator Implementation:

function* formWizard(steps) {
  let currentStep = 0;

  while (true) {
    const action = yield steps[currentStep];

    if (action === 'next' && currentStep < steps.length - 1) {
      currentStep++;
    } else if (action === 'prev' && currentStep > 0) {
      currentStep--;
    }
  }
}

// Define the steps of the form
const steps = ['Step 1: Personal Details', 'Step 2: Address Information', 'Step 3: Payment Details'];

// Create an instance of the form wizard
const wizard = formWizard(steps);

// Function to move to the next step
function nextStep() {
  wizard.next('next').value.then(currentStep => {
    // Update UI to show the current step
  });
}

// Function to move to the previous step
function prevStep() {
  wizard.next('prev').value.then(currentStep => {
    // Update UI to show the current step
  });
}

// Initial step
nextStep();

DOM traversal in JavaScript

Accreditly — Mon, 21 Aug 2023 13:39:03 +0000

Introduction

The Document Object Model (DOM) represents the structure of an HTML document. Navigating or "traversing" this structure is a fundamental aspect of web development, enabling developers to select, modify, delete, or add content on a webpage. This comprehensive guide delves deep into the art of DOM traversal using JavaScript, equipping you with a robust toolkit for handling various traversal scenarios.

We've done a more comprehensive version of this article over on Accreditly's website: A guide to DOM traversal in JavaScript.

An remember, if you're interested in showcasing your JavaScript skills then be sure to check out our JavaScript Fundamentals certification.

1. Basic DOM Selectors

Before we jump into traversal, let's review some fundamental DOM selectors.

getElementById(): Returns a reference to the first element with the specified ID.

const header = document.getElementById('header');

getElementsByClassName(): Returns a live HTMLCollection of elements with the given class name.

const buttons = document.getElementsByClassName('btn');

getElementsByTagName(): Returns a live HTMLCollection of elements with the given tag name.

const paragraphs = document.getElementsByTagName('p');

querySelector(): Returns the first element that matches a specified CSS selector.

const mainImage = document.querySelector('.main-image');

querySelectorAll(): Returns a static NodeList representing elements that match a specified CSS selector.

const listItems = document.querySelectorAll('ul li');

2. Parent, Child, and Sibling Relationships

At the core of DOM traversal are the relationships between nodes.

2.1. Parent Nodes

parentNode: Returns the parent node of a specified element.

const parentOfButton = document.querySelector('.btn').parentNode;

2.2. Child Nodes

firstChild & lastChild: Return the first and last child of a node, respectively.

const firstChildOfDiv = document.querySelector('div').firstChild;
const lastChildOfDiv = document.querySelector('div').lastChild;

children: Returns an HTMLCollection of an element's child elements (excludes text and comment nodes).

const divChildren = document.querySelector('div').children;

firstElementChild & lastElementChild: Similar to firstChild and lastChild, but strictly return element nodes.

const firstElementChildOfDiv = document.querySelector('div').firstElementChild;

2.3. Sibling Nodes

nextSibling & previousSibling: Return the next and previous sibling of an element, respectively.

const nextToButton = document.querySelector('.btn').nextSibling;
const prevToButton = document.querySelector('.btn').previousSibling;

nextElementSibling & previousElementSibling: Similar to nextSibling and previousSibling, but strictly for element nodes.

const nextElementToButton = document.querySelector('.btn').nextElementSibling;

3. Traversal Methods

3.1. Node Iteration

childNodes: Returns a NodeList of child nodes.

const listNodes = document.querySelector('ul').childNodes;

3.2. Filtering Elements

Utilize Array.prototype.filter to filter nodes based on conditions.

const listItems = document.querySelector('ul').children;
const redItems = [...listItems].filter(item => item.style.color === 'red');

4. DOM Traversal with Events

Combine event listeners with traversal methods to create interactive elements.

document.querySelector('.btn').addEventListener('click', function(e) {
  const nextElement = e.target.nextElementSibling;
  if (nextElement) {
    nextElement.style.display = 'none';
  }
});

5. Advanced Traversal Techniques

5.1. Recursive Traversal

Traverse the entire DOM tree recursively. This method is useful when the depth is unknown:

function traverseDOM(node) {
  console.log(node);
  const children = node.children;
  for (let child of children) {
    traverseDOM(child);
  }
}

traverseDOM(document.body);

5.2. Climbing Up the DOM

In some cases, you may need to find a parent element with a specific selector:

function findAncestor(el, selector) {
  while ((el = el.parentElement) && !el.matches(selector));
  return el;
}

const listItem = document.querySelector('li');
const containingDiv = findAncestor(listItem, 'div');

Mastering DOM traversal is paramount for any full-stack or frontend developer. JavaScript provides a plethora of methods and properties to navigate the intricate relationships of the DOM.

Streaming Large Files with PHP to Save Memory

Accreditly — Sat, 12 Aug 2023 13:24:52 +0000

Handling large files is a common task for web developers. However, if not done properly, it can lead to high memory usage and slow performance. In this tutorial, we will look at how to stream large files to the browser in a memory-efficient way using PHP.

Prerequisites

Basic knowledge of PHP
An active PHP development environment

Step 1: File Streaming Basics

Before we dive into the code, let's first understand what file streaming is. When you open a file in PHP with fopen(), you can read it line by line or character by character with fgets() or fgetc(), instead of loading the entire file into memory. This is known as file streaming.

Step 2: Setting Up the PHP Script

Let's create a new PHP script, download.php. In this script, we will:

Open the file we want to stream.
Read a portion of the file and output it to the browser.
Repeat step 2 until the entire file has been read and sent.

Here's the code:

<?php
$file = 'path/to/your/largefile.pdf';

// Make sure the file exists
if (!file_exists($file)) {
    die('File not found.');
}

// Set headers to tell the browser to download the file
header('Content-Type: application/octet-stream');
header('Content-Disposition: attachment; filename="'.basename($file).'"');
header('Content-Length: ' . filesize($file));

// Open the file in binary mode
$fp = fopen($file, 'rb');

// Output the file
while (!feof($fp)) {
    // Read and output a chunk of the file
    echo fread($fp, 8192);

    // Flush the output buffer to free up memory
    ob_flush();
    flush();
}

// Close the file
fclose($fp);
exit;

In the above code, we use fopen() to open the file and fread() to read a chunk of 8192 bytes at a time (which is approximately 8KB). We then output this chunk using echo and flush the output buffer to free up the memory used. This process repeats until the end of the file (feof($fp) returns true).

In this tutorial, you've learned how to stream large files to the browser in a memory-efficient way using PHP. This method is very useful when dealing with large files that could otherwise consume significant server memory and lead to performance issues. Always remember to close any open file handles and flush the output buffer to free up memory.

Forem: Accreditly

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

Send email from WordPress the right way

Why Avoid PHP’s mail() Function?

Sending Plaintext Emails with WordPress

Crafting HTML Emails in WordPress

Enhance Your WordPress Skills

The Differences Between "Test Coverage" and "Code Coverage"

Understanding Test Coverage

Why Test Coverage Matters

Measuring Test Coverage

Understanding Code Coverage

Why Code Coverage Matters

Measuring Code Coverage

Key Differences Between Test Coverage and Code Coverage

Focus

Measurement

Purpose

Using Test Coverage and Code Coverage Together

Showing Off Coverage

Example Workflow

Further Reading

DRY: What is it and how to implement it. Don't Repeat Yourself

Section 1: Understanding the DRY Principle

Section 2: Benefits of the DRY Principle

Section 3: DRY Principle in JavaScript – Example 1

Section 4: DRY Principle in JavaScript – Example 2

Conclusion:

Don't nest ternary operators. Please!

Understanding Ternary Operators

The Temptation of Nesting Ternaries

1. Readability Concerns

2. Debugging Difficulties

3. Maintainability Issues

4. Performance Misconception

Alternatives to Nested Ternaries

How to use Generators in JavaScript

What Are Generators?

Basic Syntax of Generators

Using a Generator

Benefits of Generators

Yielding Other Generators

Generators and Error Handling

Real-world Use Cases

Example: Lazy Loading of Data

Example: Multi-Step Form Navigation

DOM traversal in JavaScript

Introduction

1. Basic DOM Selectors

2. Parent, Child, and Sibling Relationships

2.1. Parent Nodes

2.2. Child Nodes

2.3. Sibling Nodes

3. Traversal Methods

3.1. Node Iteration

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

Why Avoid PHP’s `mail()` Function?