Adding comments to a static Astro blog with Netlify Forms

Comments on a static site are one of those problems that sounds simple until you actually sit down to solve it. You’ve got a few options.

You can reach for a third-party widget: Disqus, Commento, or Giscus. They all work, and Giscus in particular is clever if your readers are likely to have GitHub accounts. But they all introduce an external dependency you don’t control, and most of them inject JavaScript you didn’t write.

You can build a full backend: a database, an API, authentication for moderation. That’s a lot of infrastructure for what is, on a personal blog, a fairly low-volume use case.

Or you can use what you already have. If you’re hosting on Netlify, you’ve already got Netlify Forms and serverless Functions available. The approach I settled on uses both, inspired by Phil Hawksworth’s jamstack-comments-engine.

The approach

The system runs in four steps:

1. A visitor submits the comment form. Netlify intercepts the POST and stores it in its Forms queue. No backend code needed.
2. A webhook triggers comment-handler, which sends an email with HMAC-signed approve and delete links.
3. Clicking Approve calls approve-comment, which re-posts the comment data to a second form (approved-comments) and removes it from the queue.
4. get-comments reads only from approved-comments, so only reviewed content ever reaches readers.

There’s no database to provision, no moderation dashboard to watch, and no third-party script on the page. Comments don’t go live until I explicitly approve them from my inbox.

The form

Netlify detects forms at build time by scanning the static HTML for data-netlify="true". Because this is an Astro site, the form is a server-rendered .astro component, which means it appears in the built HTML and Netlify registers it automatically on first deploy.

1
<form
2
  name="blog-comments"
3
  method="POST"
4
  data-netlify="true"
5
  netlify-honeypot="bot-field"
6
>
7
  <input type="hidden" name="form-name" value="blog-comments" />
8
  <input type="hidden" name="postSlug" value={postId} />
9
  <!-- honeypot -->
10
  <input name="bot-field" style="display:none" tabindex="-1" />
11
  <!-- fields: name, email (optional), comment -->
12
</form>

A few things worth noting here:

• The form-name hidden field is required when submitting via fetch rather than a native form POST. Netlify uses it to route the payload to the right form bucket.
• postSlug stores the post identifier. When reading comments back, this is what ties each submission to its post.
• The netlify-honeypot="bot-field" attribute tells Netlify to silently drop any submission that fills in the bot-field input. Real users don’t see it; bots typically fill every field.

The form submits via fetch with Content-Type: application/x-www-form-urlencoded to the current page URL; Netlify intercepts those requests before they hit the origin.

The functions

There are three Netlify Functions in total.

get-comments

netlify/functions/get-comments.js takes a ?slug= query param and fetches submissions from the approved-comments form via the Netlify API, filtered by slug.

Email addresses are hashed server-side before the response leaves the function; the raw address is never sent to the browser:

1
import crypto from "node:crypto";
2

3
function gravatarHash(email) {
4
  return crypto.createHash("md5").update(email.trim().toLowerCase()).digest("hex");
5
}
6

7
const comments = submissions
8
  .filter((s) => s.data?.postSlug === slug)
9
  .map((s) => ({
10
    name: s.data.name,
11
    comment: s.data.comment,
12
    // Use the original submission date, not the approval date
13
    date: s.data.originalDate || s.created_at,
14
    emailHash: s.data.email ? gravatarHash(s.data.email) : null,
15
  }))
16
  .sort((a, b) => new Date(a.date) - new Date(b.date));

MD5 is the hash format Gravatar’s API requires; hashing also means the raw email address never leaves the server.

Using originalDate rather than created_at matters here: created_at on an approved submission reflects the moment it was approved, not when the visitor wrote it. The approval function stamps the original queue date into originalDate when it copies the submission across.

The access token lives in an environment variable; it never touches the browser. The function returns an empty array if the variables aren’t set, so the site degrades gracefully in local dev.

comment-handler

netlify/functions/comment-handler.js is triggered by a Netlify outgoing webhook whenever a new submission hits the blog-comments queue. It sends an HTML email via Resend (the same delivery layer used for new post notifications) containing the comment text and two HMAC-SHA256-signed action links:

1
import crypto from "node:crypto";
2

3
function hmac(submissionId, action, secret) {
4
  return crypto
5
    .createHmac("sha256", secret)
6
    .update(`${submissionId}:${action}`)
7
    .digest("hex");
8
}
9

10
const approveToken = hmac(id, "approve", secret);
11
const deleteToken  = hmac(id, "delete",  secret);
12

13
const approveUrl =
14
  `${siteUrl}/.netlify/functions/approve-comment` +
15
  `?action=approve&id=${id}&token=${approveToken}`;

Each token encodes both the submission ID and the intended action, so an approve token can’t be replayed as a delete, and tokens for one submission don’t work on another.

approve-comment

netlify/functions/approve-comment.js handles the link clicks. It:

1. Verifies the HMAC token with crypto.timingSafeEqual to prevent timing attacks
2. For approve: fetches the submission from the Netlify API, re-posts it to approved-comments with an originalDate field, then deletes the pending entry
3. For delete: deletes the pending submission directly
4. Returns a minimal HTML confirmation page either way

1
function verifyToken(submissionId, action, token, secret) {
2
  const expected = hmac(submissionId, action, secret);
3
  if (token.length !== expected.length) return false;
4
  return crypto.timingSafeEqual(
5
    Buffer.from(token, "hex"),
6
    Buffer.from(expected, "hex")
7
  );
8
}

The approve step posts to the site’s own URL; Netlify’s edge intercepts it and stores it in the approved-comments bucket, exactly as it does for visitor submissions. No direct Netlify API write is needed.

Rendering comments

Client-side JavaScript calls /.netlify/functions/get-comments?slug={postId} on page load and renders whatever comes back.

One discipline worth keeping here: never use innerHTML with raw user data. Because the comment cards are built as an HTML template string, innerHTML is unavoidable for inserting the full card structure, but all user-supplied values are passed through escapeHtml before they touch the template:

1
function escapeHtml(str) {
2
  return String(str)
3
    .replace(/&/g, "&")
4
    .replace(/</g, "&lt;")
5
    .replace(/>/g, "&gt;")
6
    .replace(/"/g, "&quot;")
7
    .replace(/'/g, "&#39;");
8
}

No raw user content ever reaches the HTML parser.

Gravatar avatars

Each commenter gets an avatar. If they provided an email address, the emailHash from the function is used to fetch their Gravatar. If they didn’t, or if no Gravatar is registered, a pink circle with their initial is shown instead.

The d=404 parameter tells Gravatar to return a 404 rather than a default image. onerror hides the <img> and the initial shows through. onload hides the initial when a real Gravatar loads successfully:

1
const avatarInner = c.emailHash
2
  ? `<img src="https://www.gravatar.com/avatar/${c.emailHash}?s=72&d=404"
3
         onload="this.nextElementSibling.style.display='none'"
4
         onerror="this.style.display='none'" />
5
     <span class="comment__avatar-initial">${initial}</span>`
6
  : `<span class="comment__avatar-initial">${initial}</span>`;

The <span> is always in the DOM behind the image, so the fallback requires no extra logic.

Styling dynamically injected content in Astro

This tripped me up. Astro’s scoped CSS works by adding a unique attribute (e.g. data-astro-cid-xxx) to every element it renders, and then qualifying all the CSS selectors with that attribute. That means the styles only match elements that were rendered at build time.

Comment cards are injected via innerHTML at runtime; they never get the scoping attribute. The fix is to wrap those selectors in :global():

1
/* scoped — applies to server-rendered elements */
2
.comments__heading { ... }
3

4
/* global — applies to runtime-injected elements */
5
:global(.comment) { ... }
6
:global(.comment__avatar) { ... }

Everything that’s server-rendered stays scoped. Only the comment card classes need to escape scoping.

Registering the approved-comments form

Netlify discovers forms by scanning built HTML at deploy time. The blog-comments form lives in the Comments.astro component, so it’s found automatically. The approved-comments form is never rendered on a page; it only receives programmatic POSTs from approve-comment. Without an explicit registration it would never be created in the Netlify dashboard.

The fix is a hidden placeholder form in Comments.astro, alongside the visible blog-comments form that visitors submit:

1
<form name="approved-comments" data-netlify="true" hidden aria-hidden="true">
2
  <input type="hidden" name="postSlug" />
3
  <input type="hidden" name="name" />
4
  <input type="hidden" name="email" />
5
  <input type="hidden" name="comment" />
6
  <input type="hidden" name="originalDate" />
7
</form>

Netlify only needs to find a form in one built page to register it. Since Comments.astro is rendered on every blog post, the form is present in every post page’s HTML and will be picked up on the first deploy. The hidden attribute keeps it invisible; aria-hidden="true" removes it from the accessibility tree.

Setting it up on Netlify

After the first deploy:

1. Get a personal access token: Netlify → User settings → Applications → Personal access tokens
2. Set up a Resend account and verify a sender domain (their free tier covers 3,000 emails per month, more than enough). If you already followed the mailing list post, your Resend account and sender domain are already configured.
3. Add these environment variables in Netlify → Site configuration → Environment variables:
   • NETLIFY_PAT: personal access token from step 1. Avoid the name NETLIFY_ACCESS_TOKEN; Netlify auto-overwrites it at runtime with a limited machine token
   • APPROVAL_SECRET: a random secret for HMAC signing (openssl rand -hex 32 works well)
   • SITE_URL: the public URL, e.g. https://sourcier.uk
   • RESEND_API_KEY: Resend API key
   • NOTIFY_FROM_EMAIL: verified Resend sender address
   • NOTIFY_EMAIL: where to receive approval emails
4. Add a webhook: Netlify → Forms → blog-comments → Form notifications → Add notification → Outgoing webhook → URL: https://your-site/.netlify/functions/comment-handler
5. Submit a test comment to create the first approved-comments entry, then copy its Form ID from the Netlify Forms dashboard URL
6. Add the final variable:
   • APPROVED_COMMENTS_FORM_ID: form ID from step 5
7. Trigger a redeploy

After that, every new comment fires a notification email. Approve or delete it by clicking the link. No dashboard visit required.

Refreshing the list after submission

After a successful POST, loadComments() is called a second time so the list reflects whatever the server currently holds. Because Netlify Forms requires manual approval before submissions appear via the API, the newly posted comment won’t show up immediately, but any comments approved in the meantime will, and the list stays in sync rather than going stale.

To make the refresh feel intentional rather than jarring, renderComments accepts an animate flag. When set, the list container fades out, swaps its HTML, then fades back in:

1
function renderComments(comments, animate = false) {
2
  const html = buildCommentsHtml(comments);
3
  if (!animate) {
4
    listEl.innerHTML = html;
5
    return;
6
  }
7
  listEl.classList.add("is-fading");
8
  listEl.addEventListener("animationend", () => {
9
    listEl.innerHTML = html;
10
    listEl.classList.remove("is-fading");
11
    listEl.classList.add("is-entering");
12
    listEl.addEventListener(
13
      "animationend",
14
      () => listEl.classList.remove("is-entering"),
15
      { once: true },
16
    );
17
  }, { once: true });
18
}

The initial page-load call passes no flag, so the first render is instant with no flash. The post-submission refresh passes animate = true.

The two CSS keyframes are defined in the component’s scoped styles:

1
@keyframes comments-fade-out {
2
  from { opacity: 1; transform: translateY(0); }
3
  to   { opacity: 0; transform: translateY(-6px); }
4
}
5

6
@keyframes comments-fade-in {
7
  from { opacity: 0; transform: translateY(8px); }
8
  to   { opacity: 1; transform: translateY(0); }
9
}
10

11
:global(#comments-list.is-fading)  { animation: comments-fade-out 0.2s ease forwards; }
12
:global(#comments-list.is-entering) { animation: comments-fade-in  0.25s ease forwards; }

The selectors need :global() for the same reason comment card styles do; the list element is in the server-rendered HTML but the classes are toggled at runtime by JavaScript, so Astro’s scoped-CSS attribute won’t be present on the selector when the animation fires.

What I’d do differently

The main remaining limitation is that comments don’t appear immediately after submission; the visitor sees a “submitted for review” message and has to come back later to see it live. The list refreshes after submission, but an unapproved comment can’t show up in that refresh.

The cleanest fix would be to optimistically insert the pending comment into the DOM immediately, marked visually as “awaiting approval”, and then confirm or remove it on the next real fetch. That adds state management I haven’t needed yet; volume is low enough that the current UX is fine for now.

Wrap-up

The full implementation spans four files: Comments.astro and the three serverless functions. Netlify Forms handles the queue and webhook delivery, Resend sends the notification email, and the HMAC signing keeps approve and delete actions tamper-proof. Nothing goes live until I’ve clicked a link from my inbox, with no database to provision and no third-party script on the page.

The Comments.astro component and all three functions are in the sourcier.uk repository if you want to use them as a starting point.