Add Live Commenting to Val Town Apps

Val Town runs TypeScript on Deno, so a val is a real server. That makes it a good fit for FastComments: the widget is a script tag on the page, and anything that needs a secret, like Secure SSO or verifying a webhook, can run server-side in the same val.

This guide covers adding the comment widget to an HTTP val, showing comment counts on an index page, signing users in with the Val Town account they already have, and receiving comment webhooks.

You don't need an account to try it. The examples use tenantId: "demo", a shared sandbox, and Step 2 covers switching to your own.

Step 1: Add the Widget

The widget is a script tag and a container element, so it drops into whatever your val already renders. This example uses Hono JSX, which is what Val Town's HTTP templates use.

Comment widget in an HTTP val

Copy

Run

/** @jsxImportSource npm:hono@4/jsx */
import { Hono } from "npm:hono@4";
const app = new Hono();
app.get("/:slug", (c) => {
  const slug = c.req.param("slug");
  const url = new URL(c.req.path, c.req.url).toString();
  const config = JSON.stringify({
    tenantId: "demo",
    urlId: slug,
    url,
  });
  return c.html(
    <html>
      <body>
        <h1>{slug}</h1>
        <div id="fastcomments-widget"></div>
        <script src="https://cdn.fastcomments.com/js/embed-v2.min.js"></script>
        <script
          dangerouslySetInnerHTML={{
            __html:
              `window.FastCommentsUI(document.getElementById("fastcomments-widget"), ${config});`,
          }}
        />
      </body>
    </html>,
  );
});
export default app.fetch;

Pick a urlId before you ship

urlId decides which thread a comment lands in. Leave it unset and it defaults to a cleaned version of the current page URL, which is exactly the thing that changes on Val Town: a val has a long *.web.val.run hostname until you claim a subdomain, branches get their own URLs, and renaming a page changes the path. Each variation silently becomes a separate, empty thread, and the symptom reads as "my comments disappeared".

Set it to something stable that you control, like the post slug or a database id, as above. Pass url too, so notification emails and the moderation tools can link back to the real page.

Keeping comments without JavaScript

FastComments renders a full thread server-side, which a val can drop into a <noscript> block:

No-JavaScript fallback

Copy

Run

<noscript>
  <iframe src="https://fastcomments.com/ssr/comments?tenantId=demo&urlId=POST_SLUG&url=PAGE_URL"
          title="FastComments" width="100%" height="1500px" frameborder="0"
          style="width: 1px !important; min-width: 100% !important; border: none !important;"></iframe>
</noscript>

URL-encode the parameters. The server-side version supports anonymous and logged-in commenting, SSO, and nested replies.

Step 2: Use Your Own Account

tenantId: "demo" is a shared public sandbox. It works with no signup, which is why the examples use it, but everyone else trying FastComments writes into the same threads and anyone can moderate them. Switch before you publish anything you care about.

Your tenant ID is on the API secret page.

A tenant ID is public and belongs in browser code. An API secret does not, and nothing on this page needs one.

Read it from an environment variable

Val Town vals are public on the free tier, so their source is world-readable. Keep anything sensitive in environment variables, read with Deno.env.get:

config.ts

Copy

Run

export const TENANT_ID = Deno.env.get("FASTCOMMENTS_TENANT_ID") ?? "demo";
// Only accounts created on eu.fastcomments.com set this, to "eu".
export const REGION = Deno.env.get("FASTCOMMENTS_REGION") ?? "";
export const CDN = REGION === "eu"
  ? "https://cdn-eu.fastcomments.com"
  : "https://cdn.fastcomments.com";

This matters more than usual on Val Town for a second reason: remixing a val copies environment variable keys, but not their values. A secret kept in an environment variable does not follow your val into someone else's account. A secret written into a file does.

Falling back to "demo" keeps the val working for anyone who remixes it before setting their own tenant.

EU accounts

An account, its data, and its keys live in one region. If yours was created on eu.fastcomments.com, every widget config also needs region: "eu", and the scripts load from cdn-eu.fastcomments.com. Otherwise leave both alone.

Comment Counts on an Index Page

On an index page, don't render one comment-count widget per row. That is one request per post. Use the bulk count, which takes a single request for the whole page.

Mark each row with the urlId its thread uses, then load the bulk widget once:

Bulk comment counts on an index

Copy

Run

<ul>
  {posts.map((post) => (
    <li>
      <a href={post.slug}>{post.title}</a>{" "}
      <span class="fast-comments-count" data-fast-comments-url-id={post.slug}></span>
    </li>
  ))}
</ul>
<script
  dangerouslySetInnerHTML={{
    __html: `window.FastCommentsBulkCountConfig = ${
      JSON.stringify({ tenantId: TENANT_ID })
    };`,
  }}
/>
<script src="https://cdn.fastcomments.com/js/embed-widget-comment-count-bulk.min.js"></script>

The script finds every .fast-comments-count element on the page and fills in its count.

data-fast-comments-url-id has to match the urlId that post's comment widget uses. If the widget uses the slug, the marker uses the slug. A mismatch shows zero on a thread that has comments.

The script polls for window.FastCommentsBulkCountConfig, so it does not matter whether you set the config before or after the script tag.

Secure SSO with std/oauth

If your val already knows who the visitor is, Secure SSO hands that identity to the widget so they never see a second login. There are no endpoints to build and nothing to call at runtime: you compute three values server-side and pass them in the widget config.

Val Town ships zero-config login with std/oauth, so the visitor can sign in with the Val Town account they already have. Swap that for whatever your app uses; the FastComments half does not change.

Build the payload on the server

The API secret signs the payload and must never reach browser code. Install the SDK from npm, which works on Val Town's Deno runtime as-is:

sso.ts

Copy

Run

import { SecureSSOPayloadBuilder } from "npm:fastcomments-sdk/server";
export function buildSSOPayload(user) {
  // id must be stable for the same person, or they get a new comment identity on every login.
  const id = `vt-${user.id}`;
  return new SecureSSOPayloadBuilder(Deno.env.get("FASTCOMMENTS_API_SECRET"), {
    id,
    // email is required and must be unique.
    email: user.email ?? `${id}@users.noreply.val.town`,
    // username is required and cannot be an email.
    username: user.username ?? id,
    displayName: user.username ?? undefined,
    avatar: user.links.profileImageUrl ?? undefined,
  }).getPayload();
}

getPayload() returns { userDataJSONBase64, verificationHash, timestamp }. Those three values are all that reach the browser. The secret signs them and is then dropped, so nothing in the page lets a reader forge a different user.

Widget config with SSO

Copy

Run

import { getOAuthUserData, oauthMiddleware } from "https://esm.town/v/std/oauth/middleware.ts";
app.get("/", async (c) => {
  const session = await getOAuthUserData(c.req.raw);
  const user = session?.user;
  const config = {
    tenantId: TENANT_ID,
    urlId: "my-thread",
    ...(user
      ? { sso: { ...buildSSOPayload(user), logoutURL: "/logout" } }
      : { sso: { loginURL: "/auth/login" } }),
  };
  // ...render the widget with this config
});
export default oauthMiddleware(app.fetch);

oauthMiddleware adds GET /auth/login, GET /auth/callback and POST /auth/logout for you. Note that logout is a POST, while the widget navigates to logoutURL with a GET, so point logoutURL at a small route of your own that submits the POST.

When the visitor is logged out, pass sso with only a loginURL. The widget then shows a login prompt instead of an anonymous comment box.

Things that go wrong

timestamp is epoch milliseconds, must not be in the future, and must not be more than two days old. Generate it on the server in the same request that computes the hash. Generating it in the browser is the classic failure: the value differs from the one that was hashed and every comment is rejected.

Never set isAdmin or isModerator from the identity provider. Signing in with a Val Town account says nothing about who should moderate your site.

See the SSO guide for the full field list, group-gated threads, and badges.

Receiving Webhooks

A val is a natural webhook receiver: it has a stable URL, it can verify a signature, and it has SQLite and blob storage built in.

FastComments signs ${timestamp}.${body} with your account's API secret and sends two headers:

Webhook headers

Copy

Run

X-FastComments-Timestamp: 1789004710        unix seconds, not milliseconds
X-FastComments-Signature: sha256=<hex>

The method carries the event: PUT for a created or updated comment, DELETE for a deleted one.

Verifying a delivery

Copy

Run

import { createHmac, timingSafeEqual } from "node:crypto";
async function receive(c) {
  // The exact bytes that arrived. Do NOT use c.req.json() and re-serialize.
  const rawBody = await c.req.raw.text();
  const timestamp = c.req.raw.headers.get("X-FastComments-Timestamp");
  const signature = c.req.raw.headers.get("X-FastComments-Signature");
  if (!timestamp || !signature) return new Response("Missing headers", { status: 400 });
  // Reject stale deliveries so a captured request cannot be replayed later.
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp)) > 300) {
    return new Response("Timestamp outside window", { status: 400 });
  }
  const expected = "sha256=" + createHmac("sha256", Deno.env.get("FASTCOMMENTS_API_SECRET"))
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  const a = new TextEncoder().encode(signature);
  const b = new TextEncoder().encode(expected);
  if (a.length !== b.length || !timingSafeEqual(a, b)) {
    return new Response("Signature mismatch", { status: 401 });
  }
  // ...handle JSON.parse(rawBody)
  return Response.json({ received: true });
}
app.put("/", receive);
app.delete("/", receive);

Two things that bite

Verify the raw bytes. Parsing the JSON and re-serializing it changes key order and whitespace, so the hash differs and every delivery fails with no obvious cause. This is the usual reason a webhook receiver "just doesn't work".

Compare in constant time. A plain === on the signature leaks how many bytes matched, which is enough to forge one byte at a time.

Handling events

Answer quickly. FastComments retries on a non-2xx, and an endpoint that keeps failing is eventually disabled automatically, so do real work after responding rather than inline.

Make that work idempotent on the comment id. A retry is re-signed with a fresh timestamp, and the same comment id arrives again on edit and delete, so there is nothing stable to deduplicate on.

Example Vals

Four public vals you can remix, each covering one piece of this guide.

Blog with comments (live) is a Markdown blog with a thread under every post and bulk comment counts on the index. It works the moment you remix it, and one environment variable points it at your own account.

SSO demo (live) signs the visitor in with their Val Town account and hands that identity to the widget, so there is no second login.

Webhook receiver (live) verifies the HMAC signature on every delivery and stores events in SQLite. It has a button that signs a test payload and delivers it to itself, so you can watch verification succeed before configuring a real webhook.

Agent skills (live) is a library of FastComments agent skills covering the widget, SSO, the REST API, moderation, and migrating off Disqus. Remix it and Val Town's agent, Townie, picks the skills up out of skills/ automatically, so your agent knows how to wire up comments without you pasting documentation into the chat.

The same skills install anywhere else with npx skills add fastcomments/skills.

Domain Errors

Once you switch off the demo tenant, the widget may refuse to load with an authorization error. This is because FastComments doesn't know it's supposed to allow your account to be used on that domain.

Go here to add your site to your account.

Val Town is worth a second look here, because a val can be reachable at more than one hostname:

Every HTTP val has a long default endpoint, <org>--<id>.web.val.run.
Claiming a custom subdomain adds <name>.val.run.
A custom domain adds a third.
Branches get their own URLs.

Add whichever hostnames you actually serve the widget from. If you claim a subdomain after setting things up, add that too, or the widget works on the old URL and fails on the new one.

Val Town Installation

Add Live Commenting to Val Town Apps

Step 1: Add the Widget

Pick a urlId before you ship

Keeping comments without JavaScript

Step 2: Use Your Own Account

Read it from an environment variable

EU accounts

Comment Counts on an Index Page

Secure SSO with std/oauth

Build the payload on the server

Pass it to the widget

Things that go wrong

Receiving Webhooks

Two things that bite

Handling events

Example Vals

Domain Errors

Language 🇺🇸 English

Val Town Installation

Add Live Commenting to Val Town Apps

Step 1: Add the Widget

Pick a urlId before you ship

Keeping comments without JavaScript

Step 2: Use Your Own Account

Read it from an environment variable

EU accounts

Comment Counts on an Index Page

Secure SSO with std/oauth

Build the payload on the server

Pass it to the widget

Things that go wrong

Receiving Webhooks

Two things that bite

Handling events

Example Vals

Domain Errors