There's a better ending: a small monthly maintenance retainer. The client pays a modest fixed amount, and in return you keep an eye on the site and fix small things. For the client it's peace of mind. For you it's predictable income and a reason to stay in touch, which is how one-off clients turn into repeat clients.

The hard part is proving the value. "I'll keep an eye on it" is vague. A short monthly report that says "your site was checked every 30 minutes, it was up for all but one check, your SSL certificate renews in 41 days, and the homepage loads in this many milliseconds" is concrete.

This post builds exactly that, for free, using a GitHub repository, a scheduled GitHub Actions workflow and about 100 lines of Node.js. No servers to run, no paid monitoring service.

What we'll check

For each client site:

1. Is it up? HTTP status of one or more key URLs.
2. How fast does it respond? Time to receive the response.
3. When does the SSL certificate expire? Expired certificates take sites down with a scary browser warning, and they're completely preventable.
4. Is the important content there? A keyword check, so a page that returns 200 but shows an error message still counts as down.

Results go into a JSON file per day in the repo, and a second workflow turns a month of results into a Markdown report you can paste into an email.

The repository layout

site-checks/
  sites.json
  check.mjs
  report.mjs
  data/                  # results, committed by the workflow
  .github/workflows/
    check.yml
    report.yml

sites.json lists what to check:

[
  {
    "client": "Bakery Co",
    "url": "https://bakery.example.com/",
    "expect": "Order online"
  },
  {
    "client": "Bakery Co",
    "url": "https://bakery.example.com/menu",
    "expect": "Menu"
  },
  {
    "client": "Clinic",
    "url": "https://clinic.example.org/",
    "expect": "Book an appointment"
  }
]

Use a private repository. Client domains and any notes about their setup aren't something to publish.

The check script

Node 20 and later have fetch built in, so the only imports are from the standard library:

// check.mjs
import { readFile, writeFile, mkdir } from "node:fs/promises";
import tls from "node:tls";

const sites = JSON.parse(await readFile("sites.json", "utf8"));

function certDaysLeft(hostname) {
  return new Promise((resolve) => {
    const socket = tls.connect(
      { host: hostname, port: 443, servername: hostname, timeout: 10_000 },
      () => {
        const cert = socket.getPeerCertificate();
        socket.end();
        if (!cert?.valid_to) return resolve(null);
        const ms = new Date(cert.valid_to).getTime() - Date.now();
        resolve(Math.floor(ms / 86_400_000));
      }
    );
    socket.on("error", () => resolve(null));
    socket.on("timeout", () => { socket.destroy(); resolve(null); });
  });
}

async function checkSite(site) {
  const started = performance.now();
  const result = { client: site.client, url: site.url, time: new Date().toISOString() };
  try {
    const res = await fetch(site.url, {
      redirect: "follow",
      signal: AbortSignal.timeout(15_000),
      headers: { "user-agent": "site-checks/1.0 (maintenance monitoring)" },
    });
    const body = await res.text();
    result.status = res.status;
    result.ms = Math.round(performance.now() - started);
    result.contentOk = site.expect ? body.includes(site.expect) : true;
    result.up = res.ok && result.contentOk;
  } catch (err) {
    result.status = null;
    result.ms = null;
    result.up = false;
    result.error = err.name === "TimeoutError" ? "timeout" : err.message;
  }
  result.certDays = await certDaysLeft(new URL(site.url).hostname);
  return result;
}

const results = await Promise.all(sites.map(checkSite));

const day = new Date().toISOString().slice(0, 10);
await mkdir("data", { recursive: true });
const file = `data/${day}.json`;
let existing = [];
try { existing = JSON.parse(await readFile(file, "utf8")); } catch {}
await writeFile(file, JSON.stringify([...existing, ...results], null, 2));

const down = results.filter((r) => !r.up);
for (const r of results) {
  console.log(`${r.up ? "UP  " : "DOWN"} ${r.url} status=${r.status} ${r.ms ?? "-"}ms cert=${r.certDays ?? "?"}d`);
}
if (down.length) process.exitCode = 1; // makes the workflow run fail, so GitHub notifies you

A few deliberate choices:

• The response time includes reading the body. It's a rough "how long did the page take to arrive", not a lab performance score. It's consistent from run to run, which is what matters for spotting trends.
• The content check catches soft failures. A WordPress site with a broken database often returns a page with an error message. With expect, that counts as down.
• Failing the job on downtime means GitHub's normal failed-workflow email doubles as your alert, with no extra service.
• An honest user agent. Some hosts block unknown bots. If a client's firewall blocks your checks, allowlist the user agent rather than disguising it as a browser.

Scheduling it

# .github/workflows/check.yml
name: Site checks
on:
  schedule:
    - cron: "*/30 * * * *"   # every 30 minutes (UTC)
  workflow_dispatch: {}

permissions:
  contents: write

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Run checks
        id: run
        run: node check.mjs
        continue-on-error: true
      - name: Commit results
        run: |
          git config user.name "site-checks"
          git config user.email "site-checks@users.noreply.github.com"
          git add data
          git commit -m "checks $(date -u +%FT%TZ)" || echo "nothing to commit"
          git pull --rebase --autostash
          git push
      - name: Fail if a site was down
        if: steps.run.outcome == 'failure'
        run: exit 1

Things to know about scheduled workflows:

• Cron is in UTC. Every 30 minutes doesn't care, but if you add a daily job, convert from Pakistan time (UTC+5).
• Schedules aren't exact. Runs can start late when GitHub is busy. For maintenance reporting that's fine; for alerting within a minute, use a dedicated monitoring service.
• Minutes count. Private repositories get a monthly allowance of free Actions minutes depending on your plan. Each run here takes well under a minute of compute, but check your plan's quota and lower the frequency if needed.
• Inactive repositories. GitHub can disable scheduled workflows in a repository with no activity for a long period. Because this workflow commits results, the repository stays active.

The monthly report

// report.mjs  usage: node report.mjs 2026-10
import { readdir, readFile, writeFile } from "node:fs/promises";

const month = process.argv[2] ?? new Date().toISOString().slice(0, 7);
const files = (await readdir("data")).filter((f) => f.startsWith(month));
const rows = (await Promise.all(files.map(async (f) => JSON.parse(await readFile(`data/${f}`, "utf8"))))).flat();

const byUrl = Map.groupBy(rows, (r) => r.url);
let md = `# Website maintenance report: ${month}\n\n`;
md += `| Client | Page | Checks | Up | Uptime | Median response | SSL days left |\n|---|---|---|---|---|---|---|\n`;

for (const [url, list] of byUrl) {
  const up = list.filter((r) => r.up).length;
  const times = list.map((r) => r.ms).filter((n) => n != null).sort((a, b) => a - b);
  const median = times.length ? times[Math.floor(times.length / 2)] : "-";
  const latest = list.at(-1);
  md += `| ${latest.client} | ${url} | ${list.length} | ${up} | ${((up / list.length) * 100).toFixed(2)}% | ${median} ms | ${latest.certDays ?? "?"} |\n`;
}

const incidents = rows.filter((r) => !r.up);
md += `\n## Incidents\n\n`;
md += incidents.length
  ? incidents.map((r) => `- ${r.time}: ${r.url} (${r.error ?? `status ${r.status}`}${r.contentOk === false ? ", expected text missing" : ""})`).join("\n")
  : "No failed checks this month.";

await writeFile(`report-${month}.md`, md + "\n");
console.log(md);

Map.groupBy needs Node 21 or later. On Node 20, replace it with a small reduce, or set node-version: 22 in the workflow.

Run it locally after pulling, or add a monthly workflow (cron: "0 4 1 * *" is 9 am Pakistan time on the 1st) that runs the script and uploads the Markdown as an artifact.

Turning the report into a retainer

The tooling is the easy part. A few notes on the client side:

• Offer it at handover, not months later. The moment you deliver is when the client is most aware of how much work went into the site. Something like: "I'm happy to keep an eye on the site after launch: uptime and SSL checks every 30 minutes, a short monthly report, and up to an hour of small fixes. Here's what that costs per month."
• Define what's included. Monitoring, the report, renewals, small content edits up to a time limit. New features are quoted separately. Without a limit, a retainer quietly turns into unlimited free work.
• Send the report even when nothing happened. "All checks passed, certificate renews automatically on the 12th" is reassuring, and it reminds the client you exist.
• Act before they notice. When a check fails, message the client with what happened and what you did. That one message is worth more than the whole report.

If the project came through Upwork, the follow-up after delivery is the natural moment to suggest this. The Digital Dialogue guide on getting the next job from the same Upwork client covers how to time and word that follow-up; a concrete monitoring offer gives it something useful to say.

Recap

• A private repo, a JSON list of sites and a scheduled workflow give you free monitoring.
• Check status, response time, certificate expiry and a keyword per page.
• Fail the job on downtime so GitHub emails you.
• Generate a monthly Markdown report with uptime, median response and incidents.
• Offer the retainer at handover, define its limits, and send the report every month.

Abid Ali is a web developer and freelancer in Pakistan. He writes beginner-friendly freelancing guides at Digital Dialogue.

Most soundboards handle playback like this:

button.onclick = () => new Audio(sound.url).play();

Every tap creates a new player, nothing ever stops, and every clip adds its full volume on top of the others. This post replaces that with a small audio engine built on the Web Audio API that:

• decodes each clip once and reuses it,
• limits how many sounds can play at the same time,
• lets a sound "choke" (cut off) its own previous instance or a group,
• fades sounds out instead of cutting them with a click,
• and runs everything through a master gain and compressor so stacked sounds don't clip.

It's about 120 lines of plain JavaScript.

Why stacked sounds distort

Digital audio samples live between -1 and 1. When two sounds play at once, the browser adds their samples together. Two loud clips peaking near 1 add up to nearly 2, and anything beyond the limit is flattened ("clipped") at the output. Clipping sounds harsh and crackly, and with meme sounds, which are often already mastered loud, it takes only two or three overlapping clips.

You can't fix that with per-sound volume alone, because you don't know in advance how many will overlap. You need something on the combined signal: a master gain to leave headroom, and a compressor to tame peaks when many sounds stack up.

The audio graph

[source]─[gain]─┐
[source]─[gain]─┼─[master gain]─[compressor]─[destination]
[source]─[gain]─┘

Each playing sound gets its own AudioBufferSourceNode (the thing that plays a decoded clip) and its own GainNode (so it can be faded out independently). All of them feed a shared master chain.

class SoundEngine {
  constructor({ maxVoices = 6, masterVolume = 0.8 } = {}) {
    this.ctx = new AudioContext();
    this.maxVoices = maxVoices;
    this.buffers = new Map();     // url -> Promise<AudioBuffer>
    this.voices = [];             // currently playing voices, oldest first

    this.master = this.ctx.createGain();
    this.master.gain.value = masterVolume;

    this.compressor = this.ctx.createDynamicsCompressor();
    this.compressor.threshold.value = -12; // dB: start compressing here
    this.compressor.knee.value = 6;
    this.compressor.ratio.value = 8;
    this.compressor.attack.value = 0.003;  // seconds
    this.compressor.release.value = 0.25;

    this.master.connect(this.compressor).connect(this.ctx.destination);
  }
}

connect() returns the node you connected to, which is why the chain reads left to right.

The compressor settings are a starting point. A threshold around -12 dB with a high ratio behaves almost like a limiter: quiet single sounds pass through untouched, and only big stacks get squeezed. If single clips sound squashed, raise the threshold.

Decode once, play many times

Fetching and decoding a clip on every tap wastes bandwidth and adds latency. Cache the promise, not the result, so two quick taps on a clip that's still loading share one request:

SoundEngine.prototype.load = function (url) {
  if (!this.buffers.has(url)) {
    const p = fetch(url)
      .then((r) => {
        if (!r.ok) throw new Error(`HTTP ${r.status} for ${url}`);
        return r.arrayBuffer();
      })
      .then((data) => this.ctx.decodeAudioData(data));
    p.catch(() => this.buffers.delete(url)); // allow a retry after failure
    this.buffers.set(url, p);
  }
  return this.buffers.get(url);
};

A decoded AudioBuffer can be played by any number of source nodes at once; the buffer itself is never consumed. Source nodes, on the other hand, are one-shot: once a source has been started, it can't be started again. Creating a new one per play is cheap and is how the API is meant to be used.

Keep in mind that decoded audio is uncompressed and takes far more memory than the MP3. For a board with hundreds of clips, decode on demand and consider evicting buffers that haven't been played in a while.

Playing a voice

SoundEngine.prototype.play = async function (url, { volume = 1, choke = null } = {}) {
  if (this.ctx.state === "suspended") await this.ctx.resume();
  const buffer = await this.load(url);

  // 1. Choke: stop anything in the same group (by default, the same clip).
  const group = choke ?? url;
  for (const v of this.voices) if (v.group === group) this.release(v);

  // 2. Voice limit: if we're full, release the oldest.
  while (this.voices.filter((v) => !v.releasing).length >= this.maxVoices) {
    this.release(this.voices.find((v) => !v.releasing));
  }

  // 3. Build and start the voice.
  const source = this.ctx.createBufferSource();
  source.buffer = buffer;
  const gain = this.ctx.createGain();
  gain.gain.value = volume;
  source.connect(gain).connect(this.master);

  const voice = { source, gain, group, releasing: false };
  source.onended = () => {
    gain.disconnect();
    this.voices = this.voices.filter((v) => v !== voice);
  };

  this.voices.push(voice);
  source.start();
  return voice;
};

Three behaviours are packed in here.

resume() on the first play. Browsers create an AudioContext in a suspended state until there's a user gesture. Calling resume() inside the click handler unlocks it. Do it before awaiting the network if you can, since some browsers want the resume tied closely to the gesture: calling engine.ctx.resume() synchronously at the top of your click handler is the safest pattern.

Choke groups. By default, tapping the same button again stops the previous instance of that clip before starting a new one. That's what most people expect from a sound button: tapping the airhorn ten times gives you ten restarts, not ten stacked airhorns. Pass a shared choke name to make related sounds cut each other off. For example, put every "music sting" in one group so only one plays at a time, while short effects stack freely.

A voice limit. When too many sounds are playing, the oldest gets released. Six is a reasonable default for a soundboard; nobody can tell a seventh overlapping clip apart anyway, and mobile devices thank you for not running dozens of nodes.

Release with a fade, not a cut

Calling source.stop() immediately cuts the waveform wherever it is, which causes an audible click. A fade of a few tens of milliseconds sounds clean and still feels instant:

SoundEngine.prototype.release = function (voice, fade = 0.04) {
  if (!voice || voice.releasing) return;
  voice.releasing = true;
  const t = this.ctx.currentTime;
  const g = voice.gain.gain;
  g.cancelScheduledValues(t);
  g.setValueAtTime(g.value, t);           // anchor the ramp at the current value
  g.linearRampToValueAtTime(0, t + fade);
  voice.source.stop(t + fade);
};

SoundEngine.prototype.stopAll = function () {
  for (const v of [...this.voices]) this.release(v);
};

The setValueAtTime(g.value, t) line matters. Ramps in the Web Audio API start from the previous scheduled event. Without an anchor at the current time, the ramp might start from an earlier point and jump.

The onended handler from play() cleans up after the scheduled stop, so released voices disappear from the list on their own.

Wiring it to the UI

const engine = new SoundEngine({ maxVoices: 6 });

document.querySelector(".board").addEventListener("click", (e) => {
  const btn = e.target.closest("button[data-src]");
  if (!btn) return;
  engine.ctx.resume(); // synchronous call inside the gesture
  engine.play(btn.dataset.src, {
    volume: Number(btn.dataset.volume ?? 1),
    choke: btn.dataset.choke || null,
  });
});

document.querySelector("#stop-all").addEventListener("click", () => engine.stopAll());

// Optional: warm the cache for visible buttons so the first tap is instant.
for (const btn of document.querySelectorAll("button[data-src]")) {
  engine.load(btn.dataset.src).catch(() => {});
}

Preloading every button on a big board isn't a good idea on mobile data. Warm the cache only for the buttons on screen, or for the ones the user is likely to tap next.

A big Stop all button is the single most appreciated feature on any soundboard used in a group. Make it easy to find.

Volume per clip

Clips from different sources come in at very different levels. Storing a per-clip volume (a number from 0 to 1 set once when you add the clip) and passing it to play() is a cheap way to keep a loud airhorn from drowning out a quiet voice line. The real fix is normalising clips when you add them to the library, but a per-clip trim is useful for the stragglers.

Testing what you built

• Mash test. Tap five different buttons as fast as you can. You should hear all of them, without crackling.
• Repeat test. Tap one button ten times quickly. You should hear restarts, not a growing pile.
• Mobile test. Try it on a mid-range Android phone. If audio stutters, lower maxVoices.
• Background test. Switch tabs mid-sound and come back. Some browsers suspend the context in the background; check ctx.state and resume on the next tap.

See it in context

Boards full of short, punchy effects are where this matters most. Try mashing a few buttons on Meme Tap's sound effects soundboard and you'll hear why stacking needs managing. The code in this post is a general pattern I'd use for any soundboard, not the site's actual source.

Recap

• Decode each clip once; create a new AudioBufferSourceNode per play.
• Give each voice its own GainNode so it can fade independently.
• Choke the previous instance of the same sound, and optionally whole groups.
• Cap the number of simultaneous voices and release the oldest.
• Fade out over a few tens of milliseconds instead of hard stops.
• Leave headroom with a master gain, and catch big stacks with a DynamicsCompressorNode.

Abid Ali is a full-stack web developer in Pakistan. He builds Meme Tap, a free browser soundboard with one-tap meme sound buttons.

Product pages also break previews in ways blog posts don't. Prices change, stock runs out, one URL can mean six colours, and images live on a CDN with odd URLs. This post walks through the decisions that matter for product link previews, with markup you can copy.

Start with the basics every product page needs

The minimum set that every major chat app and social platform understands:

<meta property="og:type" content="product" />
<meta property="og:title" content="Embroidered Lawn Kurta, Sea Green" />
<meta property="og:description" content="Unstitched 3-piece lawn suit with embroidered neckline. Machine washable." />
<meta property="og:url" content="https://shop.example.com/products/embroidered-lawn-kurta-sea-green" />
<meta property="og:image" content="https://shop.example.com/og/products/elk-sea-green.jpg" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="og:image:alt" content="Sea green embroidered lawn kurta on a plain background" />
<meta property="og:site_name" content="Example Shop" />
<meta name="twitter:card" content="summary_large_image" />

A note on og:type: chat apps mostly treat any type the same way and just render title, description and image. Setting product is still worthwhile because some platforms that care about commerce (Pinterest's product pins and Facebook's commerce features, for example) read product-specific tags, and they look for product as the type.

The image: product photos are usually the wrong shape

Product photography is typically square or portrait, on white. Link preview cards in most apps are wide, roughly 1.91:1. Hand a crawler a square photo and one of two things happens: it gets cropped to a strip through the middle (goodbye neckline and hem) or the app falls back to a small thumbnail layout.

The fix is to generate a dedicated share image per product, not to reuse the catalogue photo:

• Place the square product photo on a 1200×630 canvas with your brand background, product on one side.
• Leave the other side for the product name, and only the product name. More on price below.
• Keep the product inside the central area, because each app crops a little differently.
• Export as JPEG or PNG with a stable URL.

If you're on Next.js, you can generate this per product with ImageResponse from next/og in an opengraph-image.tsx route, reading the product's photo and name. Just make sure the generated image URL is absolute in the final HTML.

Stable image URLs matter more than you'd think. Many e-commerce platforms serve images through URLs with signatures or expiry timestamps. That's fine for your page, but platforms cache previews, sometimes for a long time. If the cached card points at a URL that expires next week, the preview silently turns into a grey box. Use a permanent URL for og:image, and change the filename (or add a version query string) when the image actually changes.

Price: tempting, and risky

The obvious idea is to put the price in the title or on the image: "Embroidered Lawn Kurta, Rs 4,500". It does make the card more useful. But think about what happens next.

Previews are cached per URL, often for days or weeks, and you don't control when they refresh. When the sale ends, or the price goes up, people keep sharing a card with the old price. A customer taps through, sees a different number, and feels misled, even though you did nothing wrong.

My rule:

• Don't bake the price into og:title, og:description or the image unless the price really never changes.
• Do use structured product price tags where platforms that support them can read the current value:

<meta property="product:price:amount" content="4500.00" />
<meta property="product:price:currency" content="PKR" />
<meta property="product:availability" content="in stock" />
<meta property="product:condition" content="new" />
<meta property="product:retailer_item_id" content="ELK-SEA-GREEN" />

Ordinary chat previews ignore these, so they don't put a stale price into anyone's group chat, and the platforms that do read them treat them as structured data rather than as text baked into a cached card. For search engines, the equivalent is schema.org Product JSON-LD with an Offer. Keep all three (visible price, product tags, JSON-LD) generated from the same field so they can't disagree.

Variants: one URL per thing people actually share

A product with six colours is where most shops get previews wrong. Typical setups:

1. One URL, colour picked with JavaScript. Everyone shares the same URL, and the preview always shows the default colour. Someone asking "this one or the blue?" sends two links that render identical cards.
2. One URL, colour in a query parameter (?variant=123). Better, but only if your server reads that parameter and renders matching tags. If the tags are the same for every variant, you're back to case 1.
3. A distinct URL per variant (/products/kurta-sea-green, /products/kurta-blue). Each variant has its own tags and image.

Option 3 gives the best previews, but you should decide based on how people share. For clothes, colour is the decision, so per-variant previews are worth it. For a phone case in fifteen colours that looks the same in a thumbnail, one preview is fine.

If you go with query parameters, render the tags on the server from the parameter. In Next.js App Router:

// app/products/[slug]/page.tsx
import type { Metadata } from "next";
import { getProduct } from "@/lib/catalog";

type Props = {
  params: Promise<{ slug: string }>;
  searchParams: Promise<{ variant?: string }>;
};

export async function generateMetadata({ params, searchParams }: Props): Promise<Metadata> {
  const { slug } = await params;
  const { variant: variantId } = await searchParams;
  const product = await getProduct(slug);
  const variant = product.variants.find((v) => v.id === variantId) ?? product.defaultVariant;

  const url = variant === product.defaultVariant
    ? `/products/${slug}`
    : `/products/${slug}?variant=${variant.id}`;

  return {
    title: `${product.name}, ${variant.label}`,
    description: product.shortDescription,
    alternates: { canonical: `/products/${slug}` },
    openGraph: {
      type: "website", // Next's typed options don't include "product"; see the note below
      url,
      title: `${product.name}, ${variant.label}`,
      description: product.shortDescription,
      images: [{ url: variant.shareImage, width: 1200, height: 630, alt: `${product.name} in ${variant.label}` }],
    },
    other: {
      "product:price:amount": variant.price.toFixed(2),
      "product:price:currency": "PKR",
      "product:availability": variant.inStock ? "in stock" : "out of stock",
    },
  };
}

Two things to notice. The canonical stays on the base product (so search engines see one page), while og:url points at the variant (so the share card matches what was shared). And Next's openGraph.type doesn't accept "product" in its typed options; if you need og:type to be product, render that one tag yourself and verify the final HTML.

The other field renders as <meta name="...">, not property. Many parsers accept either for product:* tags, but if a specific platform needs property, render those tags yourself. Always check the real HTML instead of trusting the framework.

Out of stock and discontinued products

Products disappear, but links to them live on in chats for months. Decide what the preview should do:

• Out of stock, coming back: keep the page and the card. Don't swap the image for an "out of stock" banner; the card might get cached that way and stay "sold out" after restock. Show stock status on the page itself, where it's always live.
• Discontinued: keep the URL alive with a page that says so and links to similar products. Its tags should describe that page honestly. A 404 means future shares of the old link render as a bare URL, or a generic error card.
• Never redirect a dead product to the homepage silently. The preview becomes your homepage card with no explanation, which looks like a broken or suspicious link.

Testing: share the way customers do

Product previews fail in ways you only see from outside:

1. Fetch the page as a crawler would, without cookies or JavaScript, and look at the tags. A product page that renders tags client-side shows nothing to most crawlers.
2. Check the image URL directly: it should return 200, an image content type, and no redirect to a login or a geo-block.
3. Paste the URL into a chat with yourself before announcing a launch.
4. For Facebook groups and Marketplace-style sharing, preview how the card will look, and refresh Facebook's cache after you change the image. I use the Facebook link preview checker on OG Scope to see what Facebook's card will show and catch missing or mis-sized images before the link goes out.

Checklist

• Dedicated 1200×630 share image per product (or per variant), with a stable URL.
• No price in title, description or image unless it never changes.
• product:price:* tags and schema.org Offer generated from the same price field.
• Per-variant og:url and image if variants are what people compare.
• Out-of-stock pages keep their normal card; discontinued pages stay alive.
• Tags rendered on the server, verified from the outside.

A product link is usually shared at the exact moment someone is deciding whether to buy. It's worth a few hours to make sure the card in that chat shows the right thing.

Abid Ali is a web developer in Pakistan. He builds OG Scope, a free tool for checking Open Graph tags and link previews.

Developers have good tools for reviewing each other's code. We rarely give clients a review process with the same structure. This post is the one I'd set up for any small client site: a stable staging link per milestone, one place for feedback with a template, a simple triage, and an approval gate before you mark the milestone as done.

1. One stable staging URL per milestone

Clients get confused by moving targets. If every push gives them a new preview URL, they'll review an old one and report bugs you fixed yesterday.

Give them one stable address for the milestone under review, for example staging.clientsite.com, or a fixed preview alias your host lets you assign to a branch. Your own throwaway previews can stay per-commit. The client only ever sees the stable one.

A simple branch model:

main         -> production (after final approval)
staging      -> staging.clientsite.com (what the client reviews)
feature/*    -> your own previews

Merge to staging when a batch is ready for review, not on every commit. Each merge to staging is a "review round".

Put a small banner on staging so nobody confuses it with the real site, and keep it out of search:

// components/StagingBanner.tsx
export function StagingBanner() {
  if (process.env.NEXT_PUBLIC_ENV !== "staging") return null;
  return (
    <div style={{ background: "#fde68a", padding: 8, textAlign: "center", fontSize: 14 }}>
      Review copy: round {process.env.NEXT_PUBLIC_REVIEW_ROUND}. Changes here are not live.
    </div>
  );
}

<meta name="robots" content="noindex, nofollow" />

If the content is sensitive, add basic auth or your host's password protection. Send the password once, in the same message as the link.

2. One place for feedback, with a template

The single biggest improvement is a rule: feedback counts when it's in the feedback place. Voice notes are fine for a conversation, but someone has to write the item down, and that someone should be the client, using a template that forces the useful details.

If the client is comfortable with GitHub, an issue form works well. Create .github/ISSUE_TEMPLATE/feedback.yml:

name: Site feedback
description: Something to change or fix on the staging site
labels: ["feedback"]
body:
  - type: input
    id: page
    attributes:
      label: Page URL
      description: Copy it from the address bar on the staging site
    validations:
      required: true
  - type: dropdown
    id: device
    attributes:
      label: Device
      options: ["Phone", "Tablet", "Laptop / desktop"]
    validations:
      required: true
  - type: textarea
    id: what
    attributes:
      label: What do you see now?
    validations:
      required: true
  - type: textarea
    id: want
    attributes:
      label: What should it be instead?
    validations:
      required: true
  - type: textarea
    id: screenshot
    attributes:
      label: Screenshot (optional)
      description: Paste or drag an image here

Most clients aren't on GitHub, and that's fine. The same five fields work as a shared spreadsheet, a simple form, or a pinned message format in chat:

Page:
Device:
What I see:
What I want instead:
Screenshot:

What matters is that every item says where, on what device, what's wrong and what right looks like. "Make the header better" becomes "Home page, phone: the menu button overlaps the logo; the logo should be fully visible."

3. Triage every item into one of three labels

Before touching code, label each item. Do it within a day so the client knows where they stand:

Then reply with a short summary, not a debate:

Round 2 feedback: 9 items
- 3 bugs: fixing today
- 4 in scope: done by Thursday
- 2 new requests (blog search, Urdu version): I'll send a separate quote,
  they won't block this milestone

The new-request label is where most scope arguments get defused. You're not saying no. You're saying "yes, separately", in writing, before it's done for free.

4. Make review rounds countable

If your agreement includes two revision rounds, make the rounds visible. Tag the commit you deploy to staging for each round:

git checkout staging
git merge --no-ff feature/round-2-fixes
git tag -a review-m1-r2 -m "Milestone 1, review round 2"
git push origin staging --tags

Now you can generate a plain-language changelog for the client between rounds:

git log review-m1-r1..review-m1-r2 --pretty=format:"- %s" --no-merges

That only works if your commit messages are readable by a non-developer, which is a good habit anyway: "Fix menu overlapping logo on phones" rather than "fix nav z-index".

5. An approval gate before the milestone is submitted

Here's the step that protects both sides. Before you mark a milestone as complete on the platform or send the final invoice, send an approval checklist that maps to the agreed deliverables:

## Milestone 1 approval: Home, About, Services, Contact

- [ ] All four pages are on staging and match the approved design
- [ ] Contact form sends to info@clientsite.com (test message received)
- [ ] Checked on a phone and a laptop
- [ ] Round 1 and 2 feedback items are closed or labelled new-request
- [ ] Copy and images are final, or listed below as pending from you

Pending from client: team photos for the About page

Ask for a short written "approved" on that checklist. Then deploy staging to main, tag it, and submit the milestone.

If you work through Upwork, this fits how the platform already works. On a fixed-price contract the client funds a milestone, you submit the work against it, and the client approves it (or the review window ends) before payment can move. Digital Dialogue's guide on how Upwork works for a freelance web developer walks through that loop, including why you shouldn't start building on an unfunded milestone. A written approval on staging before you submit means the platform approval is a formality, not a surprise.

6. Keep a review record

At the end of each round, save:

• the staging tag (review-m1-r2),
• the triage summary you sent,
• the client's approval message.

It takes two minutes. If there's ever a disagreement about what was agreed or approved, you have dates and specifics instead of memory. It's also a ready-made source for your next case study.

What this looks like from the client's side

From the client's point of view, the process is simple:

1. "Here's the link for this round, and the five things to include when you send feedback."
2. "Here's what I'm fixing, what's in scope, and what's a separate request."
3. "Here's what changed since last round."
4. "Here's the checklist. Reply 'approved' when you're happy."

Clients don't experience this as bureaucracy. They experience it as a developer who has done this before. And you stop losing evenings to the fourth version of "just one more small thing".

Abid Ali is a web developer who freelances from Pakistan and writes practical freelancing guides at Digital Dialogue.

It's also a surprisingly easy place to get service worker caching wrong. Audio has quirks that images and JSON don't: browsers request media in byte ranges, cross-origin audio without CORS fills your storage quota much faster than you'd expect, and a big library can't be cached all at once.

This post walks through a caching setup for short audio clips that handles those cases. It's plain service worker code, no library, so you can see what's going on. If you use Workbox, the same ideas map onto its strategies and its range-requests plugin.

Decide what to cache before you write code

A board with thousands of clips (Meme Tap's memes soundboard alone has thousands of buttons) can't be precached. You'd download a huge amount of audio the user will never play. So choose a policy:

• App shell: precache HTML, CSS, JS and icons on install. Small, required.
• Clips the user plays: cache on first play ("runtime caching"), with a size cap.
• Favourites: cache explicitly when the user favourites a clip, and keep them out of normal eviction.

That gives you two audio caches with different rules: a general one that can be trimmed, and a favourites one that only shrinks when the user unfavourites.

// sw.js
const SHELL = "shell-v3";
const CLIPS = "clips-v1";      // runtime, capped
const FAVS = "favs-v1";        // explicit, not auto-evicted
const MAX_CLIPS = 150;

Gotcha 1: Media elements ask for byte ranges

When an <audio> element loads a file, many browsers send a Range: bytes=0- header and expect a 206 Partial Content response. Safari is the strictest about this. If your service worker answers a range request with a full cached 200 response, some browsers play it, some refuse, and seeking can break.

The fix is to store the full response in the cache, then slice it when a range is requested:

async function rangeResponse(request, cached) {
  const header = request.headers.get("range");
  if (!header) return cached;

  const buf = await cached.arrayBuffer();
  const size = buf.byteLength;
  const match = /bytes=(\d*)-(\d*)/.exec(header);
  if (!match) return cached;

  let start = match[1] ? Number(match[1]) : 0;
  let end = match[2] ? Number(match[2]) : size - 1;
  if (!match[1] && match[2]) {        // "bytes=-500" means the last 500 bytes
    start = size - Number(match[2]);
    end = size - 1;
  }
  if (start >= size || end >= size || start > end) {
    return new Response(null, { status: 416, headers: { "Content-Range": `bytes */${size}` } });
  }

  return new Response(buf.slice(start, end + 1), {
    status: 206,
    headers: {
      "Content-Type": cached.headers.get("Content-Type") || "audio/mpeg",
      "Content-Range": `bytes ${start}-${end}/${size}`,
      "Content-Length": String(end - start + 1),
      "Accept-Ranges": "bytes",
    },
  });
}

Short clips make this cheap: reading a small file into memory to slice it is nothing.

There's a related trap when filling the cache. If you cache the network response to a range request, you might store a 206 with only part of the file. The Cache API rejects 206 responses in put(), so fetch the full file separately without a Range header:

async function fetchFull(url) {
  const res = await fetch(url, { mode: "cors", credentials: "omit" });
  if (!res.ok || res.status !== 200) throw new Error(`Bad status ${res.status}`);
  return res;
}

Gotcha 2: Opaque responses eat your quota

If your audio is on a CDN and you fetch it with mode: "no-cors", you get an opaque response. You can cache it, but you can't read its status or size, and Chromium-based browsers count each opaque response against your quota as a padded size that's far bigger than the real file. Cache a few hundred opaque clips and you can hit the limit long before the actual bytes would.

Opaque responses also can't be sliced for range requests, since you can't read the body.

So: serve audio with CORS headers (Access-Control-Allow-Origin on the CDN) and fetch with mode: "cors". If the <audio> elements on the page load from that origin too, add crossorigin="anonymous" so the page's requests and the service worker's requests match.

The fetch handler

Putting it together: serve audio from either cache if present, otherwise go to the network and cache the full file in the background.

self.addEventListener("fetch", (event) => {
  const url = new URL(event.request.url);
  if (!url.pathname.startsWith("/audio/")) return; // let other requests pass

  event.respondWith(handleAudio(event));
});

async function handleAudio(event) {
  const { request } = event;
  const key = new Request(request.url); // ignore headers like Range in the cache key

  const cached = (await caches.match(key, { cacheName: FAVS })) ||
                 (await caches.match(key, { cacheName: CLIPS }));
  if (cached) return rangeResponse(request, cached);

  // Not cached: answer from the network now, fill the cache in the background
  event.waitUntil(
    fetchFull(request.url)
      .then(async (res) => {
        const cache = await caches.open(CLIPS);
        await cache.put(key, res);
        await trimCache(CLIPS, MAX_CLIPS);
      })
      .catch(() => {}) // offline or failed: nothing to cache
  );

  return fetch(request);
}

This downloads a clip twice on first play (once for playback, once for the cache). For tiny clips that's an acceptable trade for simpler code. If it bothers you, fetch the full file first, cache a clone, and answer the range request from it.

Trimming the runtime cache

The Cache API has no built-in eviction policy, so cap it yourself. cache.keys() returns requests in insertion order, which gives you a simple "oldest first" trim:

async function trimCache(name, max) {
  const cache = await caches.open(name);
  const keys = await cache.keys();
  for (let i = 0; i < keys.length - max; i++) {
    await cache.delete(keys[i]);
  }
}

To make it closer to "least recently used", delete and re-put an entry when it's served from cache, so it moves to the end. For a soundboard, insertion order is usually good enough.

Favourites: cache on purpose

When the user favourites a clip, the page tells the service worker:

// page
async function onFavourite(clip) {
  const reg = await navigator.serviceWorker.ready;
  reg.active?.postMessage({ type: "fav-add", url: clip.audioUrl });
}

// sw.js
self.addEventListener("message", (event) => {
  const { type, url } = event.data || {};
  if (type === "fav-add") {
    event.waitUntil(fetchFull(url).then(async (res) => (await caches.open(FAVS)).put(url, res)));
  }
  if (type === "fav-remove") {
    event.waitUntil(caches.open(FAVS).then((c) => c.delete(url)));
  }
});

Favourites stay out of trimCache, so the clips someone cares about survive even after they've played hundreds of others.

Check your storage, and ask to keep it

Browsers can evict a site's storage when the device is low on space. Two APIs help:

const { usage, quota } = await navigator.storage.estimate();
console.log(`Using ${(usage / 1e6).toFixed(1)} MB of ~${(quota / 1e6).toFixed(0)} MB`);

if (navigator.storage.persist && !(await navigator.storage.persisted())) {
  const granted = await navigator.storage.persist();
  console.log("Persistent storage:", granted);
}

persist() is a request, not a guarantee. Browsers decide based on their own heuristics. A good moment to ask is right after someone favourites their first few clips, when keeping them offline is obviously useful.

Cleaning up on update

When you change the audio cache format, bump the version and delete old caches in activate:

self.addEventListener("activate", (event) => {
  const keep = new Set([SHELL, CLIPS, FAVS]);
  event.waitUntil(
    caches.keys().then((names) => Promise.all(names.filter((n) => !keep.has(n)).map((n) => caches.delete(n))))
  );
});

Be careful bumping FAVS: deleting it throws away the user's offline favourites. Migrate instead, copying entries from the old cache into the new one before deleting it.

Testing

• In DevTools, set the network to Offline, then tap a cached clip and an uncached one. The first should play; the second should fail gracefully (show a small "not available offline" state, not a frozen button).
• Test seeking and replaying on Safari, where range handling is strictest.
• Watch the storage panel while playing many clips to confirm the cap works.

Recap

• Precache the shell, runtime-cache played clips with a cap, and cache favourites explicitly.
• Answer Range requests with proper 206 slices from the full cached file.
• Never put() a 206; fetch the full file for the cache.
• Use CORS, not no-cors, so you avoid opaque-response quota padding.
• Request persistent storage at a moment that makes sense to the user.

Offline isn't a big feature for a soundboard. It's the difference between a button that works everywhere and one that quietly doesn't on the bus.

Abid Ali is a full-stack web developer in Pakistan and the builder of Meme Tap, a free meme soundboard and browser meme tools.

This isn't the platforms being random. Link previews are built and cached per URL, and your site is quietly telling crawlers that one article has many addresses. The fix is to give every piece of content exactly one address and make every signal agree on it: redirects, <link rel="canonical">, og:url, and your sitemap.

Why the URL matters so much to a preview

When a chat app or social network builds a card, it fetches the URL it was given, reads the tags and stores the result. Two URLs that differ by a query string or a trailing slash are, to a cache, simply two different keys. Fix the image on your page and one of those cached cards might refresh while the other keeps showing the old one for days.

og:url is your chance to say which address is the real one. Facebook's sharing documentation, for example, describes og:url as the canonical URL for the object, the one it should treat as the main address. On OG Scope's Facebook link preview estimate, the domain line on the card is taken from og:url, which is a quick way to notice when it's wrong.

Not every platform honours og:url the same way, so you can't rely on it alone. That's why the goal is agreement: if the redirect, the canonical link and og:url all point at the same address, every crawler ends up in the same place no matter which variant it was given.

Decide your one true URL format

Write the rules down once. For example:

• Scheme: always https.
• Host: www.example.com (or the bare domain, but pick one).
• Trailing slash: never, except the root.
• Case: lowercase paths.
• Query string: only parameters that change the content (pagination, maybe language). Never tracking parameters.

Then enforce it in three places.

1. Redirect the variants

Anything that isn't the canonical format should 301 to the version that is. Most hosts handle http → https and bare → www in their domain settings. Trailing slashes and casing are usually yours to handle. In Next.js, trailingSlash: false is the default, and a small middleware can lowercase paths:

// middleware.ts
import { NextResponse, type NextRequest } from "next/server";

export function middleware(req: NextRequest) {
  const { pathname } = req.nextUrl;
  if (pathname !== pathname.toLowerCase()) {
    const url = req.nextUrl.clone();
    url.pathname = pathname.toLowerCase();
    return NextResponse.redirect(url, 301);
  }
}

export const config = { matcher: ["/blog/:path*"] };

Don't redirect away tracking parameters. Analytics tools need to see utm_* on the landing request. Instead, leave them in the address bar and let the canonical signals say "the real page is the clean one".

2. Build canonical URLs with one helper

The most common bug I see is canonical and og:url being built in different places with different logic: one strips the query string, one doesn't; one adds a trailing slash, one doesn't. Use a single function:

// lib/canonical.ts
const SITE = "https://www.example.com";

// Query params that genuinely change the content of a page
const KEEP_PARAMS = new Set(["page", "lang"]);

export function canonicalUrl(pathOrUrl: string): string {
  const url = new URL(pathOrUrl, SITE);

  url.protocol = "https:";
  url.host = new URL(SITE).host;
  url.hash = "";
  url.pathname = url.pathname.toLowerCase().replace(/\/+$/, "") || "/";

  const kept = new URLSearchParams();
  [...url.searchParams.keys()]
    .filter((k) => KEEP_PARAMS.has(k))
    .sort()
    .forEach((k) => kept.set(k, url.searchParams.get(k)!));

  // page=1 is the same content as no page parameter
  if (kept.get("page") === "1") kept.delete("page");

  url.search = kept.toString();
  return url.toString();
}

Tracking parameters like utm_source, fbclid and gclid are dropped automatically because they're not on the allowlist. An allowlist is safer than a blocklist here: new tracking parameters appear all the time.

Then use the helper for both tags. In the App Router:

// app/blog/[slug]/page.tsx
import type { Metadata } from "next";
import { canonicalUrl } from "@/lib/canonical";
import { getPost } from "@/lib/posts";

export async function generateMetadata(
  { params }: { params: Promise<{ slug: string }> }
): Promise<Metadata> {
  const { slug } = await params;
  const post = await getPost(slug);
  const url = canonicalUrl(`/blog/${slug}`);

  return {
    title: post.title,
    alternates: { canonical: url },
    openGraph: { url, title: post.title, description: post.excerpt, images: [post.ogImage] },
  };
}

In plain HTML the result is just two lines that must match exactly:

<link rel="canonical" href="https://www.example.com/blog/post-title" />
<meta property="og:url" content="https://www.example.com/blog/post-title" />

3. Sitemap and internal links use the same URL

Your sitemap should list the canonical URLs only, and your own internal links should point at them too. If your navigation links to /Blog/Post-Title/ and every click causes a redirect, you're making the inconsistent version the one people copy.

The template bug that turns every share into your homepage

A very common one: a layout sets og:url to the site root, and individual pages never override it.

<!-- in the shared <head> template -->
<meta property="og:url" content="https://www.example.com/" />

Now every article tells crawlers "I am the homepage". Depending on the platform, shares of any article may show the homepage card, or engagement gets attributed to the homepage. If your articles all preview with the same title, check og:url before anything else.

Similarly, don't hardcode og:url with the URL of the page you copied the template from. I've seen a whole site's og:url pointing at its "About" page.

Parameters that should stay

Not every query string is noise.

• Pagination: /blog?page=2 is different content from /blog. Keep page (except page=1).
• Language: if ?lang=ur serves different text, keep it, or better, move languages to paths like /ur/... and give each its own canonical.
• Filters and sorts: usually not separate canonical pages. /products?sort=price should canonicalize to /products.
• Product variants: depends. If ?color=red changes the main image and title, it might deserve its own preview. If it only preselects a dropdown, canonicalize to the base product.

The test: would you want this exact variant to have its own card when shared? If not, it shouldn't have its own og:url.

A quick script to catch drift

Run this against a few URL variants after deploys. It fetches each one and checks that the final URL, the canonical and og:url all agree:

// scripts/check-canonical.ts
const variants = [
  "http://example.com/blog/post-title",
  "https://www.example.com/blog/post-title/",
  "https://www.example.com/Blog/Post-Title",
  "https://www.example.com/blog/post-title?utm_source=newsletter&utm_medium=email",
];

const pick = (html: string, re: RegExp) => html.match(re)?.[1] ?? "(missing)";

for (const v of variants) {
  const res = await fetch(v, { redirect: "follow" });
  const html = await res.text();
  const canonical = pick(html, /<link[^>]+rel=["']canonical["'][^>]+href=["']([^"']+)/i);
  const ogUrl = pick(html, /<meta[^>]+property=["']og:url["'][^>]+content=["']([^"']+)/i);
  const ok = canonical === ogUrl;
  console.log(ok ? "OK  " : "DIFF", v, "\n     final:", res.url, "\n     canonical:", canonical, "\n     og:url:", ogUrl);
}

Run it with npx tsx scripts/check-canonical.ts. The regexes assume the attribute order your framework emits; swap in an HTML parser if your markup varies.

Checklist

• One documented URL format: scheme, host, slash, case.
• Variants 301 to the canonical format (except tracking parameters).
• Canonical link and og:url come from the same helper and match exactly.
• Query parameters on an allowlist, not a blocklist.
• No template-level og:url pointing at the homepage.
• Sitemap and internal links use canonical URLs only.

When the URL is consistent, the preview stops being a lottery. Fix the page once, and the card updates in one place instead of five.

Abid Ali is a web developer in Pakistan who builds small, free tools, including OG Scope, an Open Graph and link preview checker.

Most hobby leaderboards ignore this. They apply a rating change when a match is saved and hope nobody ever edits anything. fun-board, a small Next.js app by Amir Ali, handles it properly, and the way it does that is worth a look even if you never build a leaderboard.

What fun-board is

fun-board is a multi-tenant leaderboard for FIFA nights with friends. Each registered user gets their own board with players, matches, knockout or round-robin tournaments, a points table and Elo ratings. Every board also has a public, read-only link you can drop in a group chat. You can see the seeded demo at fun-board.vercel.app/l/demo.

The stack, from the README: Next.js 16 (App Router), React 19, TypeScript, Tailwind v4, Turso/libSQL with raw SQL (no ORM), Auth.js v5, Zod for every mutation, and Vitest for the ranking logic.

The interesting part isn't the UI. It's one design decision in lib/recompute.ts.

The Elo maths is the easy part

The rating code in lib/elo.ts is the textbook formula. Everyone starts at 1000 and K is 32:

const K = 32

export function expectedScore(ratingA: number, ratingB: number): number {
  return 1 / (1 + Math.pow(10, (ratingB - ratingA) / 400))
}

export function newRating(current: number, expected: number, actual: number): number {
  return Math.round(current + K * (actual - expected))
}

Nothing clever here, and that's fine. The hard part is deciding when to run it.

Why patching ratings breaks

The obvious approach is to update two players' ratings each time a match is saved. That works until you need to:

• edit the score of an older match,

• delete a match that was entered by mistake, or

• change the date of a match so it moves earlier in the timeline.

With patch-style updates, each of these needs its own undo logic, and you need to work out which later matches to adjust and in what order. It's easy to get wrong, and once the stored numbers drift, nothing tells you.

Replay instead: ratings as a function of history

Amir's answer is to never patch. Ratings, win/draw/loss counts, goals and points are all treated as derived data. The source of truth is the list of matches. Anything computed from it can be thrown away and rebuilt.

The core is a pure function that takes matches in chronological order and folds over them:

/**
 * Pure Elo + aggregate replay. Matches MUST be in chronological order.
 */
export function replayElo(matches: ReplayMatch[]): {
  snapshots: ReplaySnapshot[]
  players: Map<string, PlayerAgg>
} {
  // ...
  for (const m of matches) {
    const home = get(m.home_player_id)
    const away = get(m.away_player_id)
    const homeBefore = home.elo
    const awayBefore = away.elo
    const result =
      m.home_score > m.away_score ? "home" : m.away_score > m.home_score ? "away" : "draw"
    const { homeAfter, awayAfter } = calculateEloChanges(homeBefore, awayBefore, result)
    home.elo = homeAfter
    away.elo = awayAfter
    // ...goals, wins/draws/losses, points (3/1/0)
    snapshots.push({ matchId: m.id, homeBefore, homeAfter, awayBefore, awayAfter })
  }
  return { snapshots, players }
}

It touches no database and has no hidden state. It also returns a before/after snapshot for every match, which is what feeds each player's Elo history chart.

A side effect I liked: in knockout ties decided on penalties, the stored score is level, so Elo treats the game as a draw. The shootout only decides who goes through. That's a reasonable rule, and it falls out of the design without any special-case code.

One batch rebuilds everything

recomputeUser(userId) wraps the pure function. It loads that user's matches with ORDER BY played_at ASC, rowid ASC (so two matches with the same timestamp keep a stable order), runs replayElo, and builds a list of SQL statements:

1. Reset every player on the board to 1000 / zero, then write the replayed aggregates.

2. Write the before/after Elo snapshot onto each match row.

3. Delete and rebuild elo_history from scratch.

4. Recompute tournament participant standings from tournament matches.

Then it sends them all at once:

await db.batch(stmts, "write")

A libSQL batch runs as a single transaction, so a reader never sees half-rebuilt standings. Every mutation endpoint ends the same way: the match PATCH and DELETE handlers write their change and then call recomputeUser(userId). There's one code path for "make the numbers right", and it gets used every time.

Downstream effects in tournaments

Knockout brackets have the same order problem. If you change the result of a quarter-final, the semi-final pairing may now be wrong. The match PATCH route deals with that directly:

if (isKnockout) {
  // Downstream rounds may now be invalid — drop and rebuild them.
  await db.execute({
    sql: "DELETE FROM tournament_matches WHERE tournament_id = ? AND round > ?",
    args: [tm.tournament_id as string, tm.round as number],
  })
  // ...reset champion/runner-up and remove the bonus points they earned
}

After that it recomputes and calls advanceKnockout to pair the winners again. It's the same idea as before: throw away what depends on the changed fact, then derive it again.

Tests that check properties, not just examples

Because replayElo is pure, it's easy to test, and the tests in lib/recompute.test.ts check the properties that matter rather than a couple of hand-picked numbers:

it("chains Elo across matches using the updated rating", () => {
  const { players } = replayElo([
    mk("m1", "A", "B", 1, 0), // A 1000->1016, B 1000->984
    mk("m2", "A", "B", 1, 0), // A now favourite, smaller gain
  ])
  const a = players.get("A")!
  const b = players.get("B")!
  expect(a.elo).toBeGreaterThan(1016)
  expect(a.elo).toBeLessThan(1032)
  expect(a.elo + b.elo).toBe(2000) // zero-sum
})

There are also tests for draws between equal players leaving ratings unchanged, goal totals, points-table tiebreaks (points, then goal difference, then goals scored, then head-to-head), streaks and bracket pairing. I cloned the repo and ran pnpm test: 4 files, 36 tests, all passing in well under a second.

Multi-tenancy without trusting the UI

Two smaller details are worth mentioning.

Ownership is checked in SQL. Every row belongs to a user (players.user_id, matches.recorded_by, tournaments.created_by), and every write checks that the caller owns it, for example SELECT * FROM matches WHERE id = ? AND recorded_by = ?. The README states the rule outright: read-only access "is enforced server-side, not just by hiding buttons." Public boards are reached through a share slug, and the slug generator takes an injectable RNG so its tests are deterministic.

Migrations that survive production. The schema runs itself on first use. One commit fixed a real deployment problem: hosted Turso over HTTP rejects statements like PRAGMA journal_mode=WAL, so the migration filters them out with a comment explaining why. New columns are added through an ensureColumn helper that checks PRAGMA table_info first, so older databases upgrade in place.

Trade-offs

Replaying every match on every edit is O(n) in the size of a board's history. For a friend group recording a few hundred matches, that's a few hundred statements in one batch, which is nothing. A league with millions of games would need snapshots or incremental replay from the edited match onward. For this app, Amir picked the simplest design that can't drift, and the code makes the trade-off easy to change later because the pure part is separate from the database part.

What this says about the developer

Plenty of developers can write the Elo formula. What I look for is whether someone sees the edge cases before a user hits them: edits, deletions, reordering, a bracket that no longer makes sense. fun-board handles all of them with one idea applied consistently, backed by tests and an honest README that lists what v0 doesn't do yet.

That matches how Amir describes his client work on Upwork: building and taking over Next.js and TypeScript SaaS apps, in small pull requests that he reviews himself.

Work with Amir

Amir Ali is a full-stack developer in Karachi, Pakistan, working remotely with React, Next.js, TypeScript, Node.js and Supabase/Postgres. He's open to full-time roles and freelance projects.

• GitHub: github.com/amirsaeed671 (fun-board is here)

• Upwork: Amir A., Full Stack SaaS Developer

• LinkedIn: linkedin.com/in/amirsaeed671

• Portfolio: amir-ali.me

The handover is the most underrated moment in client work. It's the last thing the client experiences, and it decides whether they come back to you or start over with someone else. It's also where developers are at their most tired and most likely to cut corners.

This post is the handover kit I'd recommend to any freelance developer: a short checklist, a client-friendly README, a .env.example that actually explains things, a clean access transfer, and a one-command deploy. Templates included.

Why handover is a sales moment

There's a business reason to care beyond being tidy. A client who just received working software is the warmest lead you'll ever have. They've seen your work and they trust you. Digital Dialogue's guide on customer follow-up and getting the next job from the same Upwork client makes this point well: close the contract cleanly, ask for the review at the right time, and make one specific follow-on offer instead of a vague "let me know if you need anything".

A clean handover is what makes that follow-on offer land. A messy one makes it awkward.

The checklist

Copy this into your project template and tick it off before you submit the final milestone:

## Handover checklist

### Code
- [ ] Repo transferred to client's account (or client added as owner)
- [ ] Default branch is clean; no stray debug code or TODOs that matter
- [ ] README.md written for a *future developer*, not for me
- [ ] HANDOVER.md written for the *client*, in plain language
- [ ] .env.example lists every variable with a comment

### Access
- [ ] Domain, hosting, DNS, email, analytics owned by the client's accounts
- [ ] My personal accounts removed or downgraded
- [ ] Every password I created rotated or handed over via a password manager share
- [ ] API keys in the client's name (not mine)

### Running it
- [ ] One-command local setup verified on a clean machine
- [ ] One-command deploy documented
- [ ] Backups: what's backed up, where, how to restore

### Closing
- [ ] Short walkthrough video (5–10 min)
- [ ] Final message: what was delivered, what's not included, one next-step offer

The Access block is the one that bites. Developers often set up hosting, analytics or a transactional email service on their own accounts "to move fast". That's fine during the build and a time bomb after it. If your card is on the hosting account, the client doesn't own their own website.

README.md: for the next developer

Write it as if the next person to open the repo is a stranger with no context, because it might be. That person might also be you in eight months.

# Acme Plumbing — website

Next.js site deployed on Vercel. Contact form sends email through Resend.

## Requirements
- Node 20+
- pnpm 9+

## Local setup
pnpm install
cp .env.example .env.local   # fill in values (see comments in the file)
pnpm dev                     # http://localhost:3000

## Deploy
Pushing to `main` deploys to production automatically.
Preview deploys are created for every pull request.

## Where things live
- Pages: `app/`
- Service content: `content/services/*.md` (edit text here, no code needed)
- Contact form handler: `app/api/contact/route.ts`

## Known limitations
- Gallery images are not resized automatically; upload images under 500 KB.

The "Known limitations" section is a gift to the next developer and a quiet protection for you. It shows these were known trade-offs, agreed within scope, not mistakes.

HANDOVER.md: for the client

The client won't read your README. Give them a separate, plain-language document:

# Your website: how it works

**Your site:** https://acmeplumbing.example
**Where it's hosted:** Vercel (account: owner@acme.example)
**Your domain:** registered at Namecheap (account: owner@acme.example), renews every March

## Changing text
Service descriptions live in your GitHub repository under content/services.
The walkthrough video (link) shows how to edit one in the browser.

## If the contact form stops sending
1. Check the Resend dashboard for errors.
2. Check the spam folder of owner@acme.example.

## What I'm still able to help with
Small edits, new pages, or a monthly care plan. Just message me.

Name the accounts and renewal dates. The single most common post-launch emergency I've seen isn't a bug. It's an expired domain nobody knew was renewing on someone else's card.

.env.example that actually explains things

A list of variable names is not documentation. Comment each one with what it's for and where to get it:

# .env.example

# Public site URL, used for canonical links and social share images.
NEXT_PUBLIC_SITE_URL=https://acmeplumbing.example

# Resend API key for the contact form.
# Create at: resend.com → API Keys (use the client's account, not the developer's).
RESEND_API_KEY=

# Where contact form messages are delivered.
CONTACT_TO_EMAIL=owner@acme.example

# Optional: analytics. Leave empty to disable.
NEXT_PUBLIC_ANALYTICS_ID=

Add a tiny guard so a missing variable fails loudly at startup instead of silently in production:

// lib/env.ts
const required = ["NEXT_PUBLIC_SITE_URL", "RESEND_API_KEY", "CONTACT_TO_EMAIL"] as const;

for (const key of required) {
  if (!process.env[key]) {
    throw new Error(`Missing environment variable: ${key}. See .env.example`);
  }
}

export const env = {
  siteUrl: process.env.NEXT_PUBLIC_SITE_URL!,
  resendKey: process.env.RESEND_API_KEY!,
  contactTo: process.env.CONTACT_TO_EMAIL!,
};

One-command setup and deploy

If the site isn't on a platform that deploys from git automatically, give the client (or the next dev) a script instead of a page of instructions:

#!/usr/bin/env bash
# scripts/deploy.sh: build and deploy to the VPS
set -euo pipefail

: "${DEPLOY_HOST:?Set DEPLOY_HOST, e.g. user@1.2.3.4}"
: "${DEPLOY_PATH:=/var/www/acme}"

pnpm install --frozen-lockfile
pnpm build

rsync -az --delete .next public package.json pnpm-lock.yaml next.config.mjs \
  "$DEPLOY_HOST:$DEPLOY_PATH/"

ssh "$DEPLOY_HOST" "cd $DEPLOY_PATH && pnpm install --prod --frozen-lockfile && pm2 reload acme"
echo "Deployed to $DEPLOY_HOST"

Then test it the honest way: clone the repo into a fresh folder (or a throwaway container), follow only the README, and see if you get a running site. Every step you had to "just know" goes into the README.

Transfer access without leaking secrets

A few rules that keep both sides safe:

• Never paste passwords into the project chat. Use a password manager's share feature, or have the client create the account and invite you.
• Rotate what you created. Any key or password you generated during the build should be rotated after handover so only the client holds it.
• Downgrade yourself. Remove your admin access, or ask the client to, once they confirm everything works. Offer to stay as a limited collaborator if they want ongoing help.

Clients rarely ask for this. They remember when you offer it.

The final message

Close with one message in the contract thread:

Everything from the final milestone is live at https://acmeplumbing.example.

Delivered: 5 pages, contact form, deployment, 2 revision rounds (both used).
Handover: repo transferred, HANDOVER.md + walkthrough video (link), all
accounts in your name, my access removed from hosting.

One idea for later: a "Service areas" page would help people searching for
plumbers in specific neighbourhoods. I can build it as a new milestone for
$120, about 2 days.

Thank you, this was a great project to work on.

What's delivered, what's handed over, one specific next step with a price. No pressure, no vague "happy to help in future".

Make it a template

You don't need to write any of this from scratch per project. Keep a handover/ folder in your starter repo with the checklist, README skeleton, HANDOVER template and env guard. It adds maybe two hours to a project, and it's the two hours most likely to bring the next contract.

Abid Ali is a full-stack web developer who freelances from Pakistan. He writes practical freelancing guides at Digital Dialogue.

This post walks through building a small, fully client-side caption generator with the Canvas 2D API, and the handful of details that make it feel solid. Everything runs in the browser, which is also a nice privacy story: the user's photo never leaves their device.

For a live reference of the finished idea, Meme Tap has a free meme caption generator: upload an image or pick a template, add Roman Urdu or English text, drag the boxes around, and download a PNG or JPG. The code below is my own minimal version of that pattern, not that tool's source.

The shape of the app

Keep state separate from drawing. The canvas is just a render target; the truth lives in a plain object:

const state = {
  image: null,            // ImageBitmap or HTMLImageElement
  boxes: [
    { id: "top",    text: "JAB CLIENT KAHE",      x: 0.5, y: 0.08, size: 0.09 },
    { id: "bottom", text: "BAS CHHOTA SA CHANGE", x: 0.5, y: 0.92, size: 0.09 },
  ],
  activeId: null,
};

Positions and font sizes are stored as fractions of the image size, not pixels. That one decision makes everything else easier: the preview can be any size on screen, and export at full resolution uses the same numbers.

Loading the image (and the sideways photo problem)

Use createImageBitmap for user files. It decodes off the main thread in most browsers and can respect EXIF orientation, which is where the "my photo is sideways" bug comes from:

async function loadFile(file) {
  if (!file.type.startsWith("image/")) throw new Error("Not an image");
  state.image = await createImageBitmap(file, { imageOrientation: "from-image" });
  render();
}

input.addEventListener("change", (e) => loadFile(e.target.files[0]));

No upload, no server: the File goes straight into the decoder.

Templates from your own server

Templates are different, because they're URLs. If they're on another origin (a CDN, for example), drawing them taints the canvas and toBlob() will throw. Two requirements:

function loadTemplate(url) {
  return new Promise((resolve, reject) => {
    const img = new Image();
    img.crossOrigin = "anonymous";   // must be set before src
    img.onload = () => resolve(img);
    img.onerror = reject;
    img.src = url;
  });
}

…and the server must respond with Access-Control-Allow-Origin for those image files. Forget either one and everything renders fine until the user hits Download.

Rendering crisp text

Set the canvas backing size to the image's real resolution and let CSS scale the element down for display. You get a sharp export for free, and the preview still fits the screen:

function render() {
  const { image } = state;
  if (!image) return;
  canvas.width = image.width;
  canvas.height = image.height;
  const ctx = canvas.getContext("2d");
  ctx.drawImage(image, 0, 0);
  for (const box of state.boxes) drawBox(ctx, box, image.width, image.height);
}

canvas { max-width: 100%; height: auto; touch-action: none; }

touch-action: none matters later, for dragging on phones.

The classic meme look

The classic style is a heavy sans font, white fill and a thick black outline. Draw the stroke first, then the fill on top, and use lineJoin = "round". Without it, sharp letter corners (and many emoji edges) produce those spiky "barbed wire" artefacts:

function drawLine(ctx, text, x, y, px) {
  ctx.font = `900 ${px}px Impact, "Arial Black", sans-serif`;
  ctx.textAlign = "center";
  ctx.textBaseline = "middle";
  ctx.lineJoin = "round";
  ctx.miterLimit = 2;
  ctx.lineWidth = Math.max(2, px * 0.12);
  ctx.strokeStyle = "#000";
  ctx.fillStyle = "#fff";
  ctx.strokeText(text, x, y);
  ctx.fillText(text, x, y);
}

If you use a web font, wait for it before the first render, or the first frame draws in a fallback font and the measurements are wrong:

await document.fonts.load('900 48px "Anton"');

Word wrapping and auto-fit

Canvas has no text wrapping. You write it yourself with measureText:

function wrap(ctx, text, maxWidth) {
  const words = text.split(/\s+/).filter(Boolean);
  const lines = [];
  let line = "";
  for (const w of words) {
    const test = line ? `${line} ${w}` : w;
    if (ctx.measureText(test).width <= maxWidth || !line) line = test;
    else { lines.push(line); line = w; }
  }
  if (line) lines.push(line);
  return lines;
}

Then auto-fit: start at the requested size and shrink until the wrapped block fits in a maximum height. Users type long captions; it's kinder to shrink than to overflow off the image.

function drawBox(ctx, box, W, H) {
  const maxWidth = W * 0.92;
  const maxHeight = H * 0.3;
  let px = Math.round(box.size * H);
  let lines;
  do {
    ctx.font = `900 ${px}px Impact, "Arial Black", sans-serif`;
    lines = wrap(ctx, box.text.toUpperCase(), maxWidth);
    if (lines.length * px * 1.1 <= maxHeight) break;
    px -= 2;
  } while (px > 12);

  const lineHeight = px * 1.1;
  const startY = box.y * H - ((lines.length - 1) * lineHeight) / 2;
  lines.forEach((l, i) => drawLine(ctx, l, box.x * W, startY + i * lineHeight, px));

  box._bounds = {               // remember for hit-testing
    x: box.x * W - maxWidth / 2, y: startY - lineHeight / 2,
    w: maxWidth, h: lines.length * lineHeight,
  };
}

A note on toUpperCase(): it suits English and Roman Urdu captions. If you support Urdu script (Nastaliq), skip it, load a proper Urdu font, and set ctx.direction = "rtl". Canvas handles the shaping, but only if the font has the glyphs.

Draggable boxes with Pointer Events

Pointer Events give you mouse, touch and pen in one API. The only conversion you need is from screen coordinates to canvas coordinates, because the canvas is CSS-scaled:

function toCanvas(e) {
  const r = canvas.getBoundingClientRect();
  return {
    x: (e.clientX - r.left) * (canvas.width / r.width),
    y: (e.clientY - r.top) * (canvas.height / r.height),
  };
}

let drag = null;

canvas.addEventListener("pointerdown", (e) => {
  const p = toCanvas(e);
  const hit = [...state.boxes].reverse().find(({ _bounds: b }) =>
    b && p.x >= b.x && p.x <= b.x + b.w && p.y >= b.y && p.y <= b.y + b.h);
  if (!hit) return;
  drag = { box: hit, dx: p.x - hit.x * canvas.width, dy: p.y - hit.y * canvas.height };
  canvas.setPointerCapture(e.pointerId);
});

canvas.addEventListener("pointermove", (e) => {
  if (!drag) return;
  const p = toCanvas(e);
  drag.box.x = Math.min(1, Math.max(0, (p.x - drag.dx) / canvas.width));
  drag.box.y = Math.min(1, Math.max(0, (p.y - drag.dy) / canvas.height));
  requestAnimationFrame(render);
});

canvas.addEventListener("pointerup", () => (drag = null));

setPointerCapture keeps the drag alive when the finger slides off the canvas edge. Combined with touch-action: none, the page doesn't scroll while you're dragging text on a phone.

Re-rendering a full 4000-pixel image on every move can lag on older phones. If it does, render the preview from a downscaled copy of the image and only draw full resolution on export, using the same fractional positions.

Export: PNG vs JPG

function download(type = "image/png") {
  canvas.toBlob((blob) => {
    const a = document.createElement("a");
    a.href = URL.createObjectURL(blob);
    a.download = `meme.${type === "image/png" ? "png" : "jpg"}`;
    a.click();
    setTimeout(() => URL.revokeObjectURL(a.href), 1000);
  }, type, 0.9);
}

• PNG keeps text edges perfectly crisp and supports transparency. Files are larger.
• JPG at 0.85–0.9 quality is much smaller and fine for sharing in chat apps, which will recompress anyway. JPG has no alpha channel, so if your image has transparent areas, fill the canvas with white first or they turn black.

Small things users notice

• Accessibility: keep caption inputs as real <input> elements outside the canvas. The canvas is a picture; the form is the interface.
• iOS memory: huge canvases can fail silently on Mobile Safari, so cap the export size.

Wrapping up

The core of a caption generator is about a hundred lines. The polish is in the edges: EXIF orientation, CORS for templates, round line joins, auto-fit, pointer capture and choosing the right export format. Get those right and the tool feels instant and trustworthy, especially when you can honestly say nothing gets uploaded.

Abid Ali is a full-stack web developer in Pakistan and the builder of Meme Tap, a free meme soundboard and browser meme tools.

X's card system has a few quirks that don't apply to Facebook or LinkedIn, and the official Card Validator stopped showing previews back in 2022, so a lot of people are debugging blind. This post covers how X decides what to show, the fallbacks it uses, and a short troubleshooting order that fixes most cases.

The tag that decides the layout

X supports a few card types, but for normal web pages only two matter:

• summary – compact card, small square image beside the title.

• summary_large_image – wide image above the title.

The layout comes from one tag:

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

This is the single most common cause of "my image is tiny on X". If twitter:card is missing, you don't get the large layout. Open Graph tags can fill in the title, description, and image, but no Open Graph tag selects the large card. og:type="article" won't do it either.

Note the attribute: Twitter tags were specified with name=, while Open Graph uses property=. X is generally tolerant of either in practice, but name="twitter:..." is the documented form, so use it.

The full minimal set

<!-- Open Graph: used by Facebook, LinkedIn, WhatsApp, Slack, Discord... and by X as a fallback -->
<meta property="og:title" content="How we cut our build time by 70%" />
<meta property="og:description" content="Caching, parallel jobs, and one embarrassing config flag." />
<meta property="og:image" content="https://example.com/og/build-time.jpg" />
<meta property="og:url" content="https://example.com/blog/build-time" />

<!-- X-specific -->
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:site" content="@example" />

That's enough. X falls back to og:title, og:description and og:image when twitter:title, twitter:description and twitter:image are absent. You only need the Twitter-specific versions when you want different text or a different crop on X than everywhere else.

How the fallbacks work (and where they bite)

The fallback chain is roughly:

Two things bite people here.

1. Conflicting values. A CMS plugin writes og:image, your theme hard-codes an old twitter:image. X prefers the Twitter tag, so it shows the old picture while Facebook shows the new one. If you see different images on different platforms, look for a stale twitter:image first:

curl -s https://example.com/blog/build-time | grep -iE 'twitter:|og:image'

2. The reverse doesn't apply. LinkedIn and Facebook don't use twitter:image as a fallback for og:image. If you only set Twitter tags, X looks fine and LinkedIn shows nothing. Set Open Graph first, Twitter second.

Image requirements for the large card

For summary_large_image, the image needs to be big enough to fill a wide card. Practical guidance:

• Aspect ratio: about 2:1 or 1.91:1. A 1200×630 image (the common Open Graph size) works well for X too; X will crop slightly toward 2:1, so keep important content away from the top and bottom edges.

• Size: X's docs have long listed a minimum of 300×157 and a maximum file size of 5 MB. Aim for something far smaller in bytes; a compressed JPG or WebP around 1200×630 is usually 100–300 KB.

• Format: JPG, PNG, WebP, or GIF (only the first frame is used). SVG isn't supported.

• URL: absolute https://, publicly reachable, no login, no expiring signature.

For a summary card the image is shown small and square, so a centered logo or icon works; a wide banner will be cropped to its middle.

Why no card appears at all

When X shows only a plain link, work through this in order:

1. The tags aren't in the raw HTML. X's crawler doesn't run JavaScript. If your framework adds meta tags client-side, X never sees them. Check with curl, not with DevTools; DevTools shows the DOM after JavaScript.

2. The crawler is blocked. X's crawler identifies as Twitterbot. A robots.txt that disallows it, a WAF challenge, or bot protection on your CDN will kill the card. Check robots:

User-agent: Twitterbot
Allow: /

and test the response it gets:

curl -sI -A "Twitterbot/1.0" https://example.com/blog/build-time

You want a 200, not a 403 or a challenge page.

3. The image fails. The tags are fine, but the image URL 404s, redirects to HTML, or times out. You'll usually get a text-only card or no card. Request the image URL directly with the same curl -sI command and confirm content-type: image/....

4. It's cached. X caches card data per URL. Once a link has been crawled, changes to your tags may not show up immediately. With the old validator's preview gone, the practical options are to wait, or to share a slightly different URL (adding a harmless query parameter like ?v=2 makes X treat it as a new URL). If you changed the image itself, also change the image's URL, so caches between you and X don't serve the old file.

A faster way to see what X will read

Reading raw HTML works, but it's easy to miss which tag is winning when Open Graph and Twitter tags disagree.

I built the OG Scope Twitter card checker for that. Paste a public URL and it reads twitter:card and the tags around it, draws an estimated X card, and adds notes when it's using a fallback: for example when twitter:card is missing and the summary layout is assumed, or when the image comes from og:image because twitter:image isn't set. It's free and needs no account.

Two honest limits: it's an estimate built from your public HTML, not X's own renderer, and it can't see what X has cached. Player and app cards appear in the metadata table but aren't rendered as players.

Quick checklist before you post

• twitter:card is set on purpose: summary_large_image if the image matters.

• og:title, og:description, og:image exist in the raw HTML; Twitter-specific tags only where you want different values.

• No stale twitter:image overriding a newer og:image.

• Image is absolute HTTPS, loads without login, roughly 1200×630, well under 5 MB.

• Twitterbot gets a 200 from both the page and the image.

• If the link was shared before, you've changed the URL or waited out the cache.

Most "X card not showing" problems are one missing tag or one blocked request. Find which, fix it once, and every future post gets the card you designed.

Abid Ali builds small web tools from Pakistan. OG Scope, his free link preview checker, lives at ogscope.pk.

You added react-helmet-async or set document.title per route. It works in the browser tab. It does nothing for Slack, LinkedIn, WhatsApp or Facebook. Here's why, and three practical ways out, from cheapest to most thorough.

Why the per-route tags never reach the crawler

When a social platform builds a link preview, its crawler requests your URL and reads the HTML it gets back. That's it. For a Vite SPA, every route returns the same file:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Vite + React</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/assets/index-a1b2c3.js"></script>
  </body>
</html>

Your route-specific tags are created later, by JavaScript, inside the browser. Most preview crawlers don't execute JavaScript at all. Some search engines do render JS, which is why SEO tutorials sometimes say client-side meta tags are "fine". For link previews, they aren't.

You can confirm this in five seconds:

curl -s https://yourapp.com/blog/my-post | grep -iE '<title>|og:'

If you only see the index.html title, crawlers are seeing the same thing.

Option 1: Good static defaults (10 minutes)

If most of your shared links go to the homepage, or the app is behind a login anyway, you may not need per-route previews at all. Just make the shell's card good:

<!-- index.html -->
<title>Acme – Invoices that chase themselves</title>
<meta name="description" content="Send invoices, get paid, and stop writing reminder emails." />
<meta property="og:title" content="Acme – Invoices that chase themselves" />
<meta property="og:description" content="Send invoices, get paid, and stop writing reminder emails." />
<meta property="og:image" content="https://acme.com/og/default.jpg" />
<meta property="og:url" content="https://acme.com/" />
<meta property="og:type" content="website" />
<meta name="twitter:card" content="summary_large_image" />

Two rules: the image URL must be absolute, and the file should be about 1200×630. Every route now shares a decent generic card instead of "Vite + React". This is honestly enough for many dashboards and internal tools.

Option 2: Prerender the routes that get shared (an afternoon)

For marketing pages and blog posts whose content is known at build time, generate a static HTML file per route with the right tags baked in. The SPA still hydrates normally for users.

A minimal approach without adopting a whole framework: after vite build, write one HTML file per route by injecting tags into the built index.html.

// scripts/prerender-meta.mjs
import { readFile, writeFile, mkdir } from "node:fs/promises";
import { dirname } from "node:path";

const SITE = "https://acme.com";
const routes = [
  { path: "/pricing", title: "Pricing – Acme", description: "Simple plans, no per-seat surprises.", image: "/og/pricing.jpg" },
  { path: "/blog/late-payments", title: "Why clients pay late (and what fixes it)", description: "Data from 4,000 invoices.", image: "/og/late-payments.jpg" },
];

const esc = (s) => s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
const shell = await readFile("dist/index.html", "utf8");

for (const r of routes) {
  const tags = `
    <title>${esc(r.title)}</title>
    <meta name="description" content="${esc(r.description)}" />
    <meta property="og:title" content="${esc(r.title)}" />
    <meta property="og:description" content="${esc(r.description)}" />
    <meta property="og:image" content="${SITE}${r.image}" />
    <meta property="og:url" content="${SITE}${r.path}" />
    <meta property="og:type" content="article" />
    <meta name="twitter:card" content="summary_large_image" />`;

  const html = shell
    .replace(/<title>.*?<\/title>/s, "")
    .replace(/<meta (property="og:|name="twitter:|name="description")[^>]*>\s*/g, "")
    .replace("</head>", `${tags}\n  </head>`);

  const out = `dist${r.path}/index.html`;
  await mkdir(dirname(out), { recursive: true });
  await writeFile(out, html);
}

Add it to your build: "build": "vite build && node scripts/prerender-meta.mjs". Static hosts (Netlify, Cloudflare Pages, Vercel, S3 behind a CDN) will serve dist/pricing/index.html for /pricing before falling back to your SPA catch-all.

Notice the script strips the shell's default tags before injecting new ones. Skip that and you'll ship two og:title tags, and crawlers will pick one, often the wrong one.

If you want real prerendered content (not just tags), Vike (formerly vite-plugin-ssr), or moving content pages to Astro or Next.js, are the longer-term answer.

Option 3: Inject tags at the edge for dynamic routes

Prerendering can't help with /u/:username or /p/:id when you have thousands of records created after the build. For those, put a tiny function in front of your static files that rewrites the <head> on the fly.

Here's the idea with a Cloudflare Worker using HTMLRewriter (Netlify Edge Functions and Vercel Middleware can do the same thing):

export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    const res = await env.ASSETS.fetch(request);
    const match = url.pathname.match(/^\/p\/([\w-]+)$/);
    if (!match) return res;

    const post = await fetch(`https://api.acme.com/posts/${match[1]}`).then((r) => r.ok ? r.json() : null);
    if (!post) return res;

    const set = (prop, value) => ({
      element(el) { el.setAttribute("content", value); },
    });

    return new HTMLRewriter()
      .on('meta[property="og:title"]', set("og:title", post.title))
      .on('meta[property="og:description"]', set("og:description", post.summary))
      .on('meta[property="og:image"]', set("og:image", post.imageUrl))
      .on('meta[property="og:url"]', set("og:url", url.toString()))
      .transform(res);
  },
};

This works because Option 1 already put default tags in the shell; the edge function just swaps the values. Users and crawlers get the same HTML, so there's no user-agent sniffing and no cloaking concerns.

Keep the API call fast and cached. A preview crawler won't wait long, and a slow response can mean no card at all.

Checking the result

After deploying, verify what a crawler actually receives, route by route. curl works, but reading raw HTML for every page gets tedious and doesn't show you the card.

I check these with OG Scope's Open Graph preview, a free tool I built. It fetches the public HTML on the server without running JavaScript (which is exactly the crawler's view of an SPA), lists the Open Graph and Twitter tags it found, flags missing or relative images, and draws estimated cards for platforms like LinkedIn, WhatsApp, Facebook, X and Slack. If it shows "Vite + React", so will the crawlers.

One caveat for any checker: platforms cache previews. If you fixed the tags but a link shared yesterday still shows the old card, ask the platform to re-scrape (Facebook's Sharing Debugger, LinkedIn's Post Inspector) or change the image URL.

Which option should you pick?

• App behind login, few public pages: Option 1.

• Marketing site or blog inside the SPA: Option 1 + Option 2.

• User-generated public pages: Option 1 + Option 3.

• Content is the product: consider moving those pages to an SSR or static framework and keeping the SPA for the app itself.

Whatever you choose, the rule doesn't change: if the tag isn't in the first HTML response, it doesn't exist for a link preview.

Abid Ali is a developer in Pakistan who builds small web tools, including OG Scope, a free Open Graph checker.

The fix was not a better gut feeling. It was a tiny bit of arithmetic I now run before every quote. It fits in one TypeScript file, and writing it down forced me to make decisions I used to skip: how many days the work really takes, what I want to keep after fees, and what is not included.

This post walks through that calculator and the reasoning behind each line. The approach comes from the Digital Dialogue guide on how much to charge for a website as a freelancer: price by what you build and how long it takes, then add the fee back in. The code just makes it hard to cheat.

The three numbers you actually need

1. Days. Not hours you hope for. Days the last similar project took, including revisions and deployment. If you have never tracked this, time a demo build this week. A "weekend" five-page site has a way of turning into three weeks.
2. Net day rate. What you want to keep for one working day, after the platform fee and before tax.
3. Fee percent. The current freelancer service fee shown in your own account. Platforms change it, so do not copy a number from a blog post (including this one).

Everything else is scope.

The most common mistake: subtracting the fee instead of grossing up

If you need $700 and the fee is 10%, the client price is not $700 + 10% = $770. The fee is taken from what the client pays, so you need:

client price = net / (1 - fee)
             = 700 / 0.9
             ≈ 778

$770 leaves you $693. It is a small gap on one job and a real gap over a year. The Digital Dialogue breakdown of Upwork fees and how much freelancers actually earn walks through the same math for $100, $500 and $1,000 jobs, plus withdrawal costs, which are smaller but still part of what you keep.

The calculator

// quote.ts
type ProjectKind = "landing" | "business" | "app-slice";

interface QuoteInput {
  kind: ProjectKind;
  days: number;            // from your own history, not optimism
  netDayRate: number;      // what you keep per day, after fees
  feePercent: number;      // from your account today, e.g. 10
  withdrawalFee?: number;  // flat cost per payout, if any
  revisionRounds: number;
  extras?: { label: string; days: number }[]; // copywriting, rush, shop...
}

interface Quote {
  totalDays: number;
  netTarget: number;
  clientPrice: number;
  feeAmount: number;
  youKeep: number;
  floorCheck: string;
}

// Your personal floors: the lowest CLIENT price you accept per product type.
const FLOORS: Record<ProjectKind, number> = {
  landing: 300,
  business: 900,
  "app-slice": 1500,
};

function roundToSayable(n: number): number {
  // Round up to a number you can say out loud without sounding random.
  if (n < 1000) return Math.ceil(n / 25) * 25;
  return Math.ceil(n / 50) * 50;
}

export function quote(input: QuoteInput): Quote {
  const extraDays = (input.extras ?? []).reduce((s, e) => s + e.days, 0);
  const totalDays = input.days + extraDays;

  const netTarget = totalDays * input.netDayRate + (input.withdrawalFee ?? 0);
  const fee = input.feePercent / 100;

  const clientPrice = roundToSayable(netTarget / (1 - fee));
  const feeAmount = +(clientPrice * fee).toFixed(2);
  const youKeep = +(clientPrice - feeAmount - (input.withdrawalFee ?? 0)).toFixed(2);

  const floor = FLOORS[input.kind];
  const floorCheck =
    clientPrice >= floor
      ? "OK: above your floor"
      : `Below your ${input.kind} floor of ${floor}. Shrink the scope or raise the price.`;

  return { totalDays, netTarget, clientPrice, feeAmount, youKeep, floorCheck };
}

Run it with your own numbers:

import { quote } from "./quote";

console.table(
  quote({
    kind: "business",
    days: 8,
    netDayRate: 90,
    feePercent: 10,
    withdrawalFee: 3,
    revisionRounds: 2,
    extras: [{ label: "Client wants a blog section", days: 2 }],
  })
);

That prints a client price of 1,050 for 10 days, about 942 kept after the fee and payout cost, and a floor check. The exact figures do not matter. What matters is that every input is a decision you made on purpose.

Why the code is split by project type

A landing page, a small business site and a small web app are different products, and the calculator refuses to treat them as one sliding scale.

• Landing page: one screen, one action (a form, a booking link, a checkout). Often one to three days. Price the days, not the fact that it is "only one page".
• Business site: home, about, services, contact, maybe a gallery. Shared header and footer, content that arrives late, two revision rounds. Often one to two weeks if you are not also designing the brand.
• App slice: anything with accounts or saved data. Do not quote the whole app. Quote the first slice (sign in, one main screen, one editable record type) and make later slices new milestones.

The FLOORS map is the most useful line in the file. When a job comes in under your floor, the calculator does not offer a discount. It tells you to cut scope until the number fits. If a client's budget matches your landing page floor, sell them a landing page. Do not squeeze five pages into it and call it a package.

Turning the number into a proposal

A price with no page list is a discount waiting to happen. I extend the script to print a scope block I can paste straight into the proposal:

export function scopeBlock(kind: ProjectKind, q: Quote, rounds: number, pages: string[]) {
  return [
    `Scope: ${pages.join(", ")}`,
    `Includes: responsive layout, contact form, deployment to your host, ${rounds} revision round(s)`,
    `Not included: logo design, copywriting, online shop, ongoing edits`,
    `Timeline: about ${Math.ceil(q.totalDays / 5)} week(s)`,
    `Price: ${q.clientPrice} (fixed, for the scope above)`,
    `Extra pages or features become a separate milestone.`,
  ].join("\n");
}

The "not included" line does as much work as the price. Silence reads as yes. The full structure I follow around that block (two lines about their site, the scope, price and timeline, one relevant link, one or two questions) is in the Digital Dialogue Upwork proposal template for a website project.

Things the calculator will not fix for you

• Bad day estimates. Garbage in, polite-looking garbage out. Keep a simple log of how long each project actually took and update your defaults every few jobs.
• Mid-project price changes. Raise the price when the client adds copywriting, a shop or a rush date, before you accept the offer. Raising it halfway through because you feel busy damages trust.
• Moving off-platform to dodge the fee. It breaks the platform's rules, and you lose payment protection and the contract record. If you do not want the fee, find clients somewhere else from the start.
• Hourly work. The same gross-up applies: if you want $40 an hour after a 10% fee, the profile rate is about $45. Publish the higher number.

The short version

1. Count days honestly.
2. Decide your net day rate.
3. Gross up by the fee: net / (1 - fee).
4. Round to a number you can say out loud.
5. Check it against your floor for that product type.
6. Attach it to a written scope with a "not included" line.

It takes two minutes per quote, and it means you stop doing the math after the project is already finished. If you want more practical guides like this on pricing, proposals and platform fees, Digital Dialogue has a whole freelance rates section written for developers who are just starting out.

As a full stack developer from Karachi, I went through exactly that phase. What fixed it was not a fancy CRM. It was treating proposals as data, the same way I would treat any other system I wanted to improve. This post shows the small TypeScript setup I use: a typed log, a CLI to add and update entries, and a report that answers three questions every week.

The three questions

Before writing code, decide what you want to learn. Mine are:

1. Reply rate by job type. Which kinds of jobs actually answer me?
2. Cost per reply. How many Connects do I spend to get one conversation?
3. Follow-ups due. Which clients am I supposed to message today?

Everything in the system exists to answer those three. If a field does not help, it does not go in.

The data model

A single JSON file in a private repo is enough. It is diffable, greppable and survives laptop changes.

// src/types.ts
export type Status =
  | "sent"
  | "viewed"
  | "replied"
  | "interview"
  | "hired"
  | "declined"
  | "no_response";

export type JobType = "landing-page" | "nextjs-app" | "bugfix" | "wordpress" | "api" | "other";

export interface Proposal {
  id: string;            // short slug, e.g. "2026-10-clinic-site"
  jobTitle: string;
  jobUrl?: string;
  jobType: JobType;
  clientCountry?: string;
  paymentVerified: boolean;
  proposalsOnJob?: string; // "5-10", "20-50", as shown on the job
  budget?: number;        // fixed price or estimated total, USD
  connects: number;
  sentAt: string;         // ISO date
  status: Status;
  followUpOn?: string;    // ISO date
  notes?: string;
}

paymentVerified and proposalsOnJob are there because they are the two signals I check before applying. Logging them lets me test whether my instincts are right: do verified clients with few proposals really reply more often? After a couple of months, you will know.

Loading and saving safely

Hand-editing JSON is fine until you typo a status. A small validator keeps the file honest.

// src/store.ts
import { readFileSync, writeFileSync, existsSync } from "node:fs";
import type { Proposal, Status } from "./types";

const FILE = new URL("../data/proposals.json", import.meta.url);
const STATUSES: Status[] = [
  "sent", "viewed", "replied", "interview", "hired", "declined", "no_response",
];

export function load(): Proposal[] {
  if (!existsSync(FILE)) return [];
  const data = JSON.parse(readFileSync(FILE, "utf8")) as Proposal[];
  for (const p of data) {
    if (!STATUSES.includes(p.status)) {
      throw new Error(`Bad status "${p.status}" on ${p.id}`);
    }
    if (Number.isNaN(Date.parse(p.sentAt))) {
      throw new Error(`Bad sentAt on ${p.id}`);
    }
  }
  return data;
}

export function save(all: Proposal[]) {
  const sorted = [...all].sort((a, b) => b.sentAt.localeCompare(a.sentAt));
  writeFileSync(FILE, JSON.stringify(sorted, null, 2) + "\n");
}

If you prefer stronger guarantees, swap the manual checks for a zod schema. For a single-user file, this is plenty.

A CLI that takes ten seconds to use

The system only works if logging a proposal is faster than skipping it. So the CLI does two things: add and update.

// src/cli.ts
import { load, save } from "./store";
import type { Proposal, Status, JobType } from "./types";

const [cmd, ...args] = process.argv.slice(2);
const all = load();
const today = new Date().toISOString().slice(0, 10);

function addDays(iso: string, n: number) {
  const d = new Date(iso);
  d.setDate(d.getDate() + n);
  return d.toISOString().slice(0, 10);
}

if (cmd === "add") {
  // add <id> <jobType> <connects> <verified:y|n> "<title>"
  const [id, jobType, connects, verified, ...title] = args;
  const p: Proposal = {
    id,
    jobType: jobType as JobType,
    connects: Number(connects),
    paymentVerified: verified === "y",
    jobTitle: title.join(" "),
    sentAt: today,
    status: "sent",
    followUpOn: addDays(today, 3),
  };
  save([p, ...all]);
  console.log(`Logged ${id}, follow-up on ${p.followUpOn}`);
} else if (cmd === "set") {
  // set <id> <status> [followUpInDays]
  const [id, status, days] = args;
  const p = all.find((x) => x.id === id);
  if (!p) throw new Error(`No proposal ${id}`);
  p.status = status as Status;
  p.followUpOn = days ? addDays(today, Number(days)) : undefined;
  save(all);
  console.log(`${id} -> ${status}`);
} else {
  console.log("Usage: add | set");
}

Add a script to package.json ("p": "tsx src/cli.ts") and logging becomes:

npm run p -- add 2026-10-clinic nextjs-app 16 y "Rebuild clinic site in Next.js"
npm run p -- set 2026-10-clinic replied 2

The default three-day follow-up is deliberate. On Upwork you generally cannot message a client who has not replied, so for most proposals the "follow-up" is really a reminder to check status and mark it no_response after a week. For clients who did reply, it is a reminder to actually move the conversation forward.

The weekly report

This is where the log pays for itself.

// src/report.ts
import { load } from "./store";

const all = load();
const today = new Date().toISOString().slice(0, 10);
const replied = (s: string) => ["replied", "interview", "hired"].includes(s);

const byType = new Map<string, { sent: number; replies: number; connects: number }>();
for (const p of all) {
  const row = byType.get(p.jobType) ?? { sent: 0, replies: 0, connects: 0 };
  row.sent++;
  row.connects += p.connects;
  if (replied(p.status)) row.replies++;
  byType.set(p.jobType, row);
}

console.table(
  [...byType].map(([type, r]) => ({
    type,
    sent: r.sent,
    replyRate: `${Math.round((r.replies / r.sent) * 100)}%`,
    connectsPerReply: r.replies ? Math.round(r.connects / r.replies) : "—",
  }))
);

const verified = all.filter((p) => p.paymentVerified);
const unverified = all.filter((p) => !p.paymentVerified);
const rate = (xs: typeof all) =>
  xs.length ? `${Math.round((xs.filter((p) => replied(p.status)).length / xs.length) * 100)}%` : "—";
console.log(`Reply rate, verified: ${rate(verified)} | unverified: ${rate(unverified)}`);

const due = all.filter((p) => p.followUpOn && p.followUpOn <= today);
console.log("\nFollow-ups due:");
for (const p of due) console.log(`- ${p.id} (${p.status}): ${p.jobTitle}`);

Run it every Monday. Within a month the table usually tells you something uncomfortable and useful. A common pattern: small bug-fix jobs reply often but rarely turn into long contracts, while full Next.js app builds reply less but are worth far more. Seeing that in your own numbers changes where you spend Connects. If you want a framework for that decision, Digital Dialogue has a guide on deciding when an Upwork job is worth the Connects that maps well onto these numbers.

Using the data to choose better jobs

Numbers do not write proposals for you, but they sharpen your filter. A few rules that tend to fall out of these reports:

• Skip unverified clients unless the job is a perfect fit. If your log shows their reply rate is far below verified clients, trust it.
• Prefer jobs with fewer existing proposals, even if the budget is a bit lower.
• Double down on the job types with the best connects-per-reply, and rewrite the proposal template for the worst ones before abandoning them.

For the qualitative side, which red flags to look for in a posting, the Digital Dialogue article on how to choose Upwork jobs as a web developer pairs nicely with the tracker. It also helps to know exactly what the platform takes from each contract; the breakdown of Upwork fees for freelancers and clients is worth adding to your budget math so you track take-home rather than headline numbers.

After the hire: keep the record going

When a proposal becomes hired, I keep it in the log and add a notes line with the delivery date and a reminder about a month later. Repeat clients are the cheapest work you will ever win, and the tracker is the thing that reminds you to check in. The guide on following up to get the next job from the same Upwork client covers what to actually say in that message.

Wrapping up

This whole system is three files, no database and no subscription. It turns "I think proposals aren't working" into "my reply rate on WordPress jobs is low and costs me a lot of Connects per conversation, so I'll stop applying to them." That is a decision you can act on.

If you are a developer just starting out, especially in Pakistan where many of us learn Upwork and Fiverr by trial and error, more practical guides like these live in the Digital Dialogue freelancing section. Build the tracker this week, log every proposal for a month, and let the data argue with your instincts.

I run Meme Tap, a free browser meme soundboard, and soundboards in general get a lot of keyboard use: streamers with a hand on a game controller, people on Chromebooks in class, folks who just like hotkeys. This post walks through the patterns I would use to build a soundboard grid that is fast with a keyboard and usable with assistive tech. The code is React + TypeScript and framework-agnostic enough to drop into Next.js.

1. Start with real buttons

Every sound tile is a <button>. Not a div with onClick, not an a without an href. Buttons give you focus, Enter and Space activation, and a correct role for free.

type Sound = { id: string; title: string; src: string };

function SoundTile({
  sound,
  playing,
  tabIndex,
  onPlay,
  onFocus,
  refCallback,
}: {
  sound: Sound;
  playing: boolean;
  tabIndex: 0 | -1;
  onPlay: (s: Sound) => void;
  onFocus: () => void;
  refCallback: (el: HTMLButtonElement | null) => void;
}) {
  return (
    <button
      ref={refCallback}
      type="button"
      className="tile"
      tabIndex={tabIndex}
      aria-pressed={playing}
      onClick={() => onPlay(sound)}
      onFocus={onFocus}
    >
      <span className="tile-title">{sound.title}</span>
    </button>
  );
}

aria-pressed tells screen readers that the button is a toggle and whether it is currently playing. The visible title doubles as the accessible name, so there is no need for an extra aria-label unless the tile is icon-only.

2. Roving tabindex for the grid

With 100+ tiles, tabbing through every one is miserable. The standard fix is a roving tabindex: only one tile in the grid has tabIndex={0}, every other tile has -1. Tab moves into and out of the grid in one step, and arrow keys move inside it.

import { useRef, useState, useCallback, KeyboardEvent } from "react";

function useRovingGrid(count: number, columns: number) {
  const [active, setActive] = useState(0);
  const refs = useRef<(HTMLButtonElement | null)[]>([]);

  const focusAt = useCallback(
    (i: number) => {
      const next = Math.max(0, Math.min(count - 1, i));
      setActive(next);
      refs.current[next]?.focus();
    },
    [count]
  );

  const onKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
    const map: Record<string, number> = {
      ArrowRight: active + 1,
      ArrowLeft: active - 1,
      ArrowDown: active + columns,
      ArrowUp: active - columns,
      Home: 0,
      End: count - 1,
    };
    if (e.key in map) {
      e.preventDefault();
      focusAt(map[e.key]);
    }
  };

  return { active, setActive, refs, onKeyDown };
}

The column count should match the CSS layout. If your grid is responsive, read it from the DOM instead of hardcoding it:

function getColumns(grid: HTMLElement | null): number {
  if (!grid) return 1;
  const cols = getComputedStyle(grid).gridTemplateColumns.split(" ");
  return Math.max(1, cols.length);
}

Call it in a ResizeObserver callback and store the value in state so arrow navigation follows the layout as it changes.

3. One audio element, not one per tile

Creating a new Audio() per tile is tempting and wasteful. On mobile it can also trip autoplay rules in odd ways. A single shared player is simpler and makes "now playing" state trivial.

import { createContext, useContext, useRef, useState } from "react";

type PlayerCtx = {
  playingId: string | null;
  play: (s: Sound) => void;
  stop: () => void;
};

const Player = createContext<PlayerCtx | null>(null);

export function PlayerProvider({ children }: { children: React.ReactNode }) {
  const audioRef = useRef<HTMLAudioElement | null>(null);
  const [playingId, setPlayingId] = useState<string | null>(null);
  const [announce, setAnnounce] = useState("");

  const stop = () => {
    audioRef.current?.pause();
    setPlayingId(null);
  };

  const play = (s: Sound) => {
    const audio = (audioRef.current ??= new Audio());
    if (playingId === s.id) return stop(); // second press toggles off
    audio.src = s.src;
    audio.currentTime = 0;
    audio.onended = () => setPlayingId(null);
    audio
      .play()
      .then(() => {
        setPlayingId(s.id);
        setAnnounce(`Playing ${s.title}`);
      })
      .catch(() => setAnnounce(`Could not play ${s.title}`));
  };

  return (
    <Player.Provider value={{ playingId, play, stop }}>
      {children}
      <div aria-live="polite" className="sr-only">
        {announce}
      </div>
    </Player.Provider>
  );
}

export const usePlayer = () => useContext(Player)!;

The hidden aria-live="polite" region is the key accessibility piece here. Sighted users see a tile light up; screen-reader users hear "Playing Bruh" without losing their place. Use polite, not assertive, so announcements do not cut off whatever the screen reader was saying.

4. Global hotkeys that don't fight assistive tech

Power users want shortcuts: Escape to stop, / to jump to search, R for a random sound. The trick is not stealing keys when the user is typing or when a modifier is held.

import { useEffect } from "react";

export function useHotkeys(handlers: Record<string, () => void>) {
  useEffect(() => {
    const onKey = (e: globalThis.KeyboardEvent) => {
      if (e.ctrlKey || e.metaKey || e.altKey) return;
      const t = e.target as HTMLElement;
      const typing =
        t.isContentEditable ||
        ["INPUT", "TEXTAREA", "SELECT"].includes(t.tagName);
      if (typing && e.key !== "Escape") return;

      const fn = handlers[e.key.toLowerCase()];
      if (fn) {
        e.preventDefault();
        fn();
      }
    };
    window.addEventListener("keydown", onKey);
    return () => window.removeEventListener("keydown", onKey);
  }, [handlers]);
}

Memoise the handlers object with useMemo so the listener is not re-attached on every render.

Single-character shortcuts are a known accessibility issue (WCAG 2.1.4): speech-input users can trigger them by accident. Offer a setting to turn them off, and document them in a visible "Keyboard shortcuts" dialog opened with ?.

5. Putting the grid together

function SoundGrid({ sounds }: { sounds: Sound[] }) {
  const gridRef = useRef<HTMLDivElement>(null);
  const [columns, setColumns] = useState(4);
  const { active, setActive, refs, onKeyDown } = useRovingGrid(
    sounds.length,
    columns
  );
  const { playingId, play, stop } = usePlayer();

  useEffect(() => {
    const ro = new ResizeObserver(() => setColumns(getColumns(gridRef.current)));
    if (gridRef.current) ro.observe(gridRef.current);
    return () => ro.disconnect();
  }, []);

  const hotkeys = useMemo(
    () => ({
      escape: stop,
      r: () => {
        const i = Math.floor(Math.random() * sounds.length);
        setActive(i);
        refs.current[i]?.focus();
        play(sounds[i]);
      },
    }),
    [sounds, play, stop]
  );
  useHotkeys(hotkeys);

  return (
    <div
      ref={gridRef}
      role="group"
      aria-label="Sound buttons"
      className="grid"
      onKeyDown={onKeyDown}
    >
      {sounds.map((s, i) => (
        <SoundTile
          key={s.id}
          sound={s}
          playing={playingId === s.id}
          tabIndex={i === active ? 0 : -1}
          onPlay={play}
          onFocus={() => setActive(i)}
          refCallback={(el) => (refs.current[i] = el)}
        />
      ))}
    </div>
  );
}

I use role="group" with a label rather than role="grid". A full ARIA grid implies rows, cells and a lot of extra semantics; a labelled group of toggle buttons with arrow-key navigation is simpler and reads more naturally in screen readers.

6. Visual details that matter

.tile:focus-visible {
  outline: 3px solid #f59e0b;
  outline-offset: 3px;
}
.tile[aria-pressed="true"] {
  background: #1d4ed8;
  color: white;
}
@media (prefers-reduced-motion: no-preference) {
  .tile[aria-pressed="true"] { animation: pulse 0.8s ease-in-out infinite; }
}

• Style :focus-visible, never remove outlines.
• Show playing state with colour and something else (an icon, a border, motion), so it is not colour-only.
• Gate pulsing animations behind prefers-reduced-motion.
• Keep a minimum hit target of around 44×44px for touch users.

Testing it

• Unplug your mouse and try to find, play and stop a sound in under ten seconds.
• Turn on VoiceOver or NVDA and confirm you hear the title, the pressed state and the live announcement.
• Run axe or Lighthouse for the basics, then trust your own manual pass more.

If you want a real data set to test with, category pages like the meme sounds soundboard or the reaction sounds board have dozens of short clips per page, which is exactly where roving focus and a shared player earn their keep. The trending sounds list is handy for checking that your grid copes with titles of wildly different lengths.

A soundboard is a toy. Making it accessible is not much extra work, and it turns a toy that only works for mouse users into one that works for everyone who wants to hit a button and hear a laugh track.

This post covers both halves: generating dynamic OG images with next/og, and validating them with a script plus a quick manual check before you ship.

1. Set metadataBase first

Almost every broken preview I debug in Next.js comes down to relative URLs. Crawlers need absolute og:image URLs. Next.js can build them for you, but only if you tell it where the site lives.

// app/layout.tsx
import type { Metadata } from "next";

export const metadata: Metadata = {
  metadataBase: new URL(
    process.env.NEXT_PUBLIC_SITE_URL ?? "http://localhost:3000"
  ),
  title: { default: "Field Notes", template: "%s · Field Notes" },
  openGraph: { siteName: "Field Notes", type: "website" },
  twitter: { card: "summary_large_image" },
};

Two things to note. Set NEXT_PUBLIC_SITE_URL to your production origin (with https://www. if that is your canonical host), and make sure preview deployments use their own URL, or your staging cards will point at production images that do not exist yet.

2. Generate the image with the opengraph-image convention

The App Router lets you drop an opengraph-image.tsx next to any route. Next.js turns it into an image endpoint and injects the og:image, og:image:width, og:image:height and og:image:type tags automatically.

// app/blog/[slug]/opengraph-image.tsx
import { ImageResponse } from "next/og";
import { getPost } from "@/lib/posts";

export const size = { width: 1200, height: 630 };
export const contentType = "image/png";
export const alt = "Field Notes article cover";

export default async function OgImage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const post = await getPost(slug);

  return new ImageResponse(
    (
      <div
        style={{
          width: "100%",
          height: "100%",
          display: "flex",
          flexDirection: "column",
          justifyContent: "space-between",
          padding: 72,
          background: "linear-gradient(135deg, #0f172a, #1e3a8a)",
          color: "white",
        }}
      >
        <div style={{ fontSize: 28, opacity: 0.8 }}>Field Notes</div>
        <div style={{ fontSize: 64, fontWeight: 700, lineHeight: 1.1 }}>
          {post?.title ?? "Untitled"}
        </div>
        <div style={{ fontSize: 26, opacity: 0.7 }}>
          {post?.readingTime ?? ""} · {post?.author ?? ""}
        </div>
      </div>
    ),
    size
  );
}

A few practical notes:

• Flexbox only. ImageResponse uses Satori under the hood, which supports a subset of CSS. Every div with more than one child needs display: "flex". Grid is not supported.
• Long titles. Clamp them. A 120-character title at 64px will overflow. Either reduce font size based on length or truncate with an ellipsis in code.
• Fonts. Custom fonts must be loaded as ArrayBuffer and passed via the fonts option. If you skip this you get the default font, which is fine for a first pass.
• params is async in recent Next.js versions, so await it as shown.

If you also want a separate X image, add twitter-image.tsx with the same shape. Often re-exporting is enough:

// app/blog/[slug]/twitter-image.tsx
export { default, size, contentType, alt } from "./opengraph-image";

3. Keep generateMetadata honest

The image is only one tag. The title and description that sit beside it come from generateMetadata. Keep them per page and avoid accidentally overriding the generated image.

// app/blog/[slug]/page.tsx
import type { Metadata } from "next";
import { getPost } from "@/lib/posts";

export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string }>;
}): Promise<Metadata> {
  const { slug } = await params;
  const post = await getPost(slug);
  if (!post) return { title: "Not found" };

  return {
    title: post.title,
    description: post.excerpt,
    alternates: { canonical: `/blog/${slug}` },
    openGraph: {
      type: "article",
      title: post.title,
      description: post.excerpt,
      url: `/blog/${slug}`,
      publishedTime: post.publishedAt,
      // no `images` here: the opengraph-image file supplies it
    },
  };
}

One trap: if you define openGraph.images here and have an opengraph-image.tsx, the file-based image normally wins, but mixing the two makes it hard to reason about. Pick one source per route.

Another trap: when you set openGraph in a child route, it does not deep-merge with the parent. Fields like siteName from the root layout can disappear. Re-declare anything you need, or pull shared fields from a helper.

4. Validate in CI, not in the group chat

Now the important part. A green build tells you the route compiled. It tells you nothing about whether a crawler can fetch the image, whether the URL is absolute, or whether the dimensions are right. So I add a small Node script that runs against a deployed preview URL.

// scripts/check-og.ts
// usage: npx tsx scripts/check-og.ts https://preview.example.com/blog/hello
const target = process.argv[2];
if (!target) throw new Error("Pass a URL");

const UA = "Mozilla/5.0 (compatible; og-check/1.0)";

function meta(html: string, key: string): string | undefined {
  const re = new RegExp(
    `<meta[^>]+(?:property|name)=["']${key}["'][^>]*content=["']([^"']+)["']`,
    "i"
  );
  return html.match(re)?.[1];
}

async function main() {
  const res = await fetch(target, { headers: { "user-agent": UA } });
  if (!res.ok) throw new Error(`Page returned ${res.status}`);
  const html = await res.text();

  const required = ["og:title", "og:description", "og:image", "og:url"];
  const found = Object.fromEntries(required.map((k) => [k, meta(html, k)]));
  const missing = required.filter((k) => !found[k]);
  if (missing.length) throw new Error(`Missing: ${missing.join(", ")}`);

  const img = found["og:image"]!;
  if (!/^https:\/\//.test(img)) throw new Error(`og:image not absolute https: ${img}`);

  const imgRes = await fetch(img, { headers: { "user-agent": UA } });
  const type = imgRes.headers.get("content-type") ?? "";
  const bytes = Number(imgRes.headers.get("content-length") ?? 0);
  if (!imgRes.ok || !type.startsWith("image/"))
    throw new Error(`Image failed: ${imgRes.status} ${type}`);
  if (bytes > 5_000_000) console.warn(`Warning: image is ${bytes} bytes`);

  const title = found["og:title"]!;
  if (title.length > 90) console.warn(`Warning: long og:title (${title.length})`);

  console.log("OK", found);
}

main().catch((e) => {
  console.error(e.message);
  process.exit(1);
});

Wire it into the workflow that runs after your preview deployment, and loop over a handful of representative URLs: home, one blog post, one product page. It catches the boring failures early: localhost in og:image, a 500 from the image route because a post had no author, or a missing description on a new template.

What it cannot show you is how the card actually looks on each platform. Crop ratios, title truncation and fallback behaviour differ between LinkedIn, WhatsApp, Slack and X.

5. Do one visual pass before launch

For the visual side I paste the deployed URL into OG Scope's Open Graph checker. It is a free tool I built because I kept doing this check by hand. It fetches the page server-side, without running your client JavaScript (which matches how most crawlers behave), lists the tags it found, and draws estimated cards for LinkedIn, WhatsApp, Facebook, X, Slack, Discord and Telegram.

Two pages are especially useful for dynamic images:

• The OG image checker shows the raw og:image value you published next to the resolved URL, confirms the response is an actual image and reads pixel dimensions from the file. If your opengraph-image route accidentally returns HTML (an error page, say), this is where you see it.
• The Twitter card checker shows which twitter:card layout was read and which fields fell back to Open Graph, which helps when twitter-image.tsx and opengraph-image.tsx drift apart.

Treat both as estimates. Platforms change their rendering and cache previews aggressively, so after fixing a live page you may still need the platform's own refresh tool or a cache-busting query string.

A short checklist

• metadataBase set from an environment variable, correct per environment.
• One image source per route: either opengraph-image.tsx or openGraph.images.
• 1200×630 PNG, titles clamped, fonts loaded explicitly.
• Child openGraph objects re-declare shared fields.
• A CI script that fetches the page and the image like a crawler would.
• One visual pass on the platforms your audience actually uses.

Dynamic OG images are one of the nicest features of the App Router. Validating them takes about twenty extra lines and a minute of looking, and it means the first person to share your link sees the card you designed instead of a grey box.