Adding comments to a static Astro blog with Netlify Forms

Original post: Adding comments to a static Astro blog with Netlify Forms

Series: Part of How this blog was built — documenting every decision that shaped this site.

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.

Diagram fallback for Dev.to. View the canonical article for the full version: https://sourcier.uk/blog/comments-netlify-forms-astro

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.

<form

  name="blog-comments"

  method="POST"

  data-netlify="true"

  netlify-honeypot="bot-field"

>

  <input type="hidden" name="form-name" value="blog-comments" />

  <input type="hidden" name="postSlug" value={postId} />

  <!-- honeypot -->

  <input name="bot-field" style="display:none" tabindex="-1" />

  <!-- fields: name, email (optional), comment -->

</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:

import crypto from "node:crypto";



function gravatarHash(email) {

  return crypto.createHash("md5").update(email.trim().toLowerCase()).digest("hex");

}



const comments = submissions

  .filter((s) => s.data?.postSlug === slug)

  .map((s) => ({

    name: s.data.name,

    comment: s.data.comment,

    // Use the original submission date, not the approval date

    date: s.data.originalDate || s.created_at,

    emailHash: s.data.email ? gravatarHash(s.data.email) : null,

  }))

  .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:

import crypto from "node:crypto";



function hmac(submissionId, action, secret) {

  return crypto

    .createHmac("sha256", secret)

    .update(`${submissionId}:${action}`)

    .digest("hex");

}



const approveToken = hmac(id, "approve", secret);

const deleteToken  = hmac(id, "delete",  secret);



const approveUrl =

  `${siteUrl}/.netlify/functions/approve-comment` +

  `?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
   

function verifyToken(submissionId, action, token, secret) {

  const expected = hmac(submissionId, action, secret);

  if (token.length !== expected.length) return false;

  return crypto.timingSafeEqual(

    Buffer.from(token, "hex"),

    Buffer.from(expected, "hex")

  );

}

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:

function escapeHtml(str) {

  return String(str)

    .replace(/&/g, "&")

    .replace(/</g, "<")

    .replace(/>/g, ">")

    .replace(/"/g, """)

    .replace(/'/g, "'");

}

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:

const avatarInner = c.emailHash

  ? `<img src="https://www.gravatar.com/avatar/${c.emailHash}?s=72&d=404"

         onload="this.nextElementSibling.style.display='none'"

         onerror="this.style.display='none'" />

     <span class="comment__avatar-initial">${initial}</span>`

  : `<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():

/* scoped — applies to server-rendered elements */

.comments__heading { ... }



/* global — applies to runtime-injected elements */

:global(.comment) { ... }

: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:

<form name="approved-comments" data-netlify="true" hidden aria-hidden="true">

  <input type="hidden" name="postSlug" />

  <input type="hidden" name="name" />

  <input type="hidden" name="email" />

  <input type="hidden" name="comment" />

  <input type="hidden" name="originalDate" />

</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:

function renderComments(comments, animate = false) {

  const html = buildCommentsHtml(comments);

  if (!animate) {

    listEl.innerHTML = html;

    return;

  }

  listEl.classList.add("is-fading");

  listEl.addEventListener("animationend", () => {

    listEl.innerHTML = html;

    listEl.classList.remove("is-fading");

    listEl.classList.add("is-entering");

    listEl.addEventListener(

      "animationend",

      () => listEl.classList.remove("is-entering"),

      { once: true },

    );

  }, { once: true });

}

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:

@keyframes comments-fade-out {

  from { opacity: 1; transform: translateY(0); }

  to   { opacity: 0; transform: translateY(-6px); }

}



@keyframes comments-fade-in {

  from { opacity: 0; transform: translateY(8px); }

  to   { opacity: 1; transform: translateY(0); }

}



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

: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.