Live Webmentions on a Static Site

Webmentions rendered at build time plus a silent client-side refresh, so new likes and replies show up on a static Astro site without SSR or a redeploy.

Article Created Updated

Reviewed by adrian on

The first version of my WebMentions component fetched from webmention.io at build time and baked the result into the static HTML (Receiving and sending webmentions). The limit showed up within a day: a new like or reply only appeared after the next deploy. On a site that rebuilt once a day, a reaction from the morning might not surface until the next day.

The setup

  • Site: a static Astro 6 build, deployed by a shell script that rsynced it to a VPS.
  • Data: webmention.io, fed by Bridgy with likes and replies from Bluesky and Mastodon.
  • Constraint: no SSR. The rest of the site was plain static HTML served from a container.

Why not SSR

SSR would have fixed the staleness: fetch fresh data on every request, render, send. But it brings cold-start latency on every page load, a server process to keep alive, and no more static delivery from a CDN edge. The webmention component was the only dynamic element on otherwise static pages, and switching the whole render pipeline for one component was the wrong trade.

Build first, refresh after

I kept the static build and added a silent refresh in the browser:

  1. At build time the component fetches webmention.io and renders complete HTML. Visitors see the mentions at once, with no loading state and no flash of empty content.
  2. In the browser, after the page has loaded, a small script fetches the API again. If the count has changed since the build, it updates the DOM; otherwise it does nothing.

The build-time fetch

let mentions: Mention[] = [];
try {
  const res = await fetch(
    `https://webmention.io/api/mentions.jf2?target=${encodeURIComponent(url)}&per-page=100`
  );
  if (res.ok) {
    const data = await res.json();
    mentions = data.children ?? [];
  }
} catch {
  // Unavailable at build time, client-side will handle it
}

A network hiccup during the build is not fatal. The component renders empty and the script fills it in on the next page view. With zero mentions the template writes a hidden placeholder:

{mentions.length === 0 && (
  <section class="webmentions" data-url={url} data-empty></section>
)}

data-empty sets display: none in CSS. When the browser fetch finds mentions, it removes the attribute and inserts the content.

The refresh in the browser

The script runs once on page load and re-renders only when the count differs:

async function refreshWebmentions(section) {
  const url = section.dataset.url;
  const res = await fetch(
    `https://webmention.io/api/mentions.jf2?target=${encodeURIComponent(url)}&per-page=100`
  );
  const data = await res.json();
  const mentions = data.children ?? [];

  const currentCount = section.querySelectorAll("[data-wm-id]").length;
  const isEmpty = section.hasAttribute("data-empty");

  if (mentions.length !== currentCount || (isEmpty && mentions.length > 0)) {
    if (mentions.length > 0) renderMentions(section, mentions);
  }
}

document.querySelectorAll(".webmentions[data-url]").forEach(refreshWebmentions);

The static render puts data-wm-id on each mention, so counting those gives the current number. On most page loads the counts match and nothing happens.

Scoped styles and innerHTML

Astro scopes component styles: it adds a data-astro-cid-* attribute to every element in the template and limits the generated selectors to it. HTML that the script writes through innerHTML does not get that attribute, so the styles silently stopped applying. The fix was <style is:global>:

<style is:global>
  .webmentions { ... }
  .webmentions__avatar { ... }
</style>

Plain class selectors apply to the static render and to inserted content alike. The price is global scope, which was acceptable because the .webmentions__ prefix does not collide with anything else on the site.

The result

  • Visitors saw webmentions on page load, with no loading state.
  • New reactions appeared without a redeploy, as soon as Bridgy had polled and forwarded them to webmention.io.
  • The pages stayed static HTML served from a container.

Later I extended the refresh so that it also handles removed mentions, not only new ones (Troubleshooting Mastodon backfeed).

Takeaways

  • Count-based diffing saves DOM work. If the API returns the same count, skip the re-render.
  • is:global is the way out when the same styles must cover static markup and innerHTML content.
  • A hidden empty placeholder is the hook the script needs for mentions that did not exist at build time.

Based on

  • Live Webmentions Without SSR: A Hybrid Approach (raw/2026/2026-03-23/live-webmentions-without-ssr-a-hybrid-approach.md) [post]

More on this

Topic

  • IndieWeb Publishing on your own domain first and connecting personal websites with open standards such as Webmention and Microformats.

Basis for

  • Troubleshooting Mastodon Backfeed A runbook for Mastodon, Bridgy and webmention.io: token scopes, deploy order, trailing slashes, 429s on media uploads and reactions that are gone upstream.

Builds on

  • Receiving and Sending Webmentions Incoming webmentions through webmention.io, rendered at build time in Astro, and outgoing ones sent by webmention.app after every deploy.

Uses

  • Astro Tool for building websites from content such as Markdown. Ships plain HTML by default and only loads JavaScript where it is needed.

Show in the graph view