Live commentaar toevoegen aan Val Town-apps

Val Town draait TypeScript op Deno, dus een val is een echte server. Dat maakt het een goede match voor FastComments: de widget is een script‑tag op de pagina, en alles wat een geheim nodig heeft, zoals Secure SSO of het verifiëren van een webhook, kan server‑side draaien in dezelfde val.

Deze gids behandelt het toevoegen van de commentaarwidget aan een HTTP val, het tonen van commentaartellingen op een indexpagina, het aanmelden van gebruikers met het Val Town‑account dat ze al hebben, en het ontvangen van commentaar‑webhooks.

Je hebt geen account nodig om het te proberen. De voorbeelden gebruiken `tenantId: "demo"`, een gedeelde sandbox, en Stap 2 behandelt het overschakelen naar je eigen.

Stap 1: Voeg de widget toe

The widget is een script‑tag en een container‑element, dus hij wordt ingevoegd waar jouw val al rendert. Dit voorbeeld gebruikt Hono JSX, wat de HTTP‑templates van Val Town gebruiken.

Commentaarwidget in een 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;

Kies een urlId voordat je publiceert

urlId bepaalt in welke thread een opmerking terechtkomt. Laat je het leeg, dan wordt standaard een opgeschoonde versie van de huidige pagin URL gebruikt, wat precies het element is dat verandert op Val Town: een val heeft een lange *.web.val.run hostnaam totdat je een subdomein claimt, takken krijgen hun eigen URL’s, en het hernoemen van een pagina wijzigt het pad. Elke variatie wordt stilletjes een aparte, lege thread, en het symptoom leest als “mijn opmerkingen zijn verdwenen”.

Stel het in op iets stabiels dat je controleert, zoals de post‑slug of een database‑id, zoals hierboven. Geef ook url door, zodat notificatie‑e‑mails en de moderatietools kunnen linken naar de echte pagina.

Reacties behouden zonder JavaScript

FastComments rendert een volledige thread server‑side, die een val kan invoegen in een <noscript>‑blok:

Fallback zonder JavaScript

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 de parameters. De server‑side versie ondersteunt anonieme en ingelogde opmerkingen, SSO, en geneste antwoorden.

Stap 2: Gebruik je eigen account

tenantId: "demo" is een gedeelde openbare sandbox. Het werkt zonder aanmelding, daarom gebruiken de voorbeelden het, maar iedereen die FastComments probeert, schrijft in dezelfde threads en iedereen kan ze modereren. Schakel over voordat je iets publiceert waar je om geeft.

Je tenant‑ID staat op de API secret page.

Een tenant‑ID is openbaar en hoort in de browsercode te staan. Een API secret is dat niet, en niets op deze pagina heeft er een nodig.

Read it from an environment variable

Val Town vals zijn openbaar op het gratis niveau, dus hun bron is wereldwijd leesbaar. Houd alles wat gevoelig is in omgevingsvariabelen, lees ze met 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";

Dit is belangrijker dan normaal op Val Town om een tweede reden: het remixen van een val kopieert de sleutels van omgevingsvariabelen, maar niet hun waarden. Een geheim dat in een omgevingsvariabele wordt bewaard, volgt je val niet naar het account van iemand anders. Een geheim dat in een bestand wordt geschreven, wel.

Terugvallen op "demo" houdt de val werkend voor iedereen die deze remixt voordat ze hun eigen tenant instellen.

EU accounts

Een account, de bijbehorende gegevens en sleutels bevinden zich in één regio. Als die van jou is aangemaakt op eu.fastcomments.com, moet elke widget config ook region: "eu" bevatten, en worden de scripts geladen van cdn-eu.fastcomments.com. Laat anders beide ongewijzigd.

Reactietellingen op een indexpagina

Op een indexpagina moet je niet per rij één comment-count widget renderen. Dat is één verzoek per bericht. Gebruik de bulk‑telling, die één enkel verzoek voor de hele pagina doet.

Markeer elke rij met de urlId die de thread gebruikt, en laad vervolgens de bulk‑widget één keer:

Bulk commentaartellingen op een 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>

Het script vindt elk .fast-comments-count‑element op de pagina en vult de telling in.

data-fast-comments-url-id moet overeenkomen met de urlId die de commentaarwidget van het bericht gebruikt. Als de widget de slug gebruikt, gebruikt de marker de slug. Een mismatch toont nul op een thread die wel reacties heeft.

Het script pollt naar window.FastCommentsBulkCountConfig, dus het maakt niet uit of je de configuratie vóór of na de script‑tag instelt.

Beveiligde SSO met 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.

Widgetconfiguratie met 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.

Webhooks ontvangen

A val is een natuurlijke webhook‑ontvanger: het heeft een stabiele URL, het kan een handtekening verifiëren, en het heeft SQLite en blob‑opslag ingebouwd.

FastComments ondertekent ${timestamp}.${body} met het API‑geheim van uw account en stuurt twee headers:

Webhook-headers

Copy

Run

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

De methode draagt het evenement: PUT voor een aangemaakt of bijgewerkt commentaar, DELETE voor een verwijderd commentaar.

Levering verifiëren

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);

Twee dingen die bijten

Verifieer de ruwe bytes. Het parseren van de JSON en opnieuw serialiseren verandert de sleutelvolgorde en witruimte, waardoor de hash verschilt en elke levering faalt zonder duidelijke oorzaak. Dit is de gebruikelijke reden waarom een webhook‑ontvanger “gewoon niet werkt”.

Vergelijk in constante tijd. Een eenvoudige === op de handtekening lekt hoeveel bytes overeenkomen, wat genoeg is om één byte per keer te vervalsen.

Gebeurtenissen afhandelen

Antwoord snel. FastComments probeert opnieuw bij een non-2xx, en een endpoint die blijft falen wordt uiteindelijk automatisch uitgeschakeld, dus voer het echte werk uit na het beantwoorden in plaats van inline.

Maak dat werk idempotent op basis van de commentaar‑id. Een retry wordt opnieuw ondertekend met een verse timestamp, en dezelfde commentaar‑id komt opnieuw terug bij bewerken en verwijderen, dus er is niets stabiels om te dedupliceren op.

Voorbeeld Vals

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

Blog met reacties (live) is een Markdown-blog met een thread onder elk bericht en bulkreactietellingen op de index. Het werkt meteen nadat je het remixt, en één omgevingsvariabele wijst het naar je eigen account.

SSO-demo (live) meldt de bezoeker aan met hun Val Town-account en geeft die identiteit door aan de widget, zodat er geen tweede login nodig is.

Webhook-ontvanger (live) verifieert de HMAC-handtekening bij elke levering en slaat gebeurtenissen op in SQLite. Het heeft een knop die een testpayload ondertekent en naar zichzelf verzendt, zodat je de verificatie kunt zien slagen voordat je een echte webhook configureert.

Agent-vaardigheden (live) is een bibliotheek van FastComments-agentvaardigheden die de widget, SSO, de REST API, moderatie en het migreren van Disqus behandelen. Remix het en de agent van Val Town, Townie, haalt de vaardigheden automatisch uit skills/, zodat je agent weet hoe commentaren moeten worden opgezet zonder dat je documentatie in de chat plakt.

Dezelfde vaardigheden kun je overal anders installeren met npx skills add fastcomments/skills.

Domeinfouten

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.

Ga hierheen om je site aan je account toe te voegen.

Val Town verdient hier een tweede blik, omdat een val via meer dan één hostnaam bereikbaar kan zijn:

Elke HTTP val heeft een lange standaard endpoint, <org>--<id>.web.val.run.
Het claimen van een aangepast subdomein voegt <name>.val.run toe.
Een aangepast domein voegt een derde toe.
Branches krijgen hun eigen URL's.

Voeg de hostnamen toe waarvan je de widget daadwerkelijk bedient. Als je een subdomein claimt nadat je alles hebt ingesteld, voeg dat dan ook toe, anders werkt de widget op de oude URL en faalt op de nieuwe.

Val Town Installatie

Live commentaar toevoegen aan Val Town-apps

Je hebt geen account nodig om het te proberen. De voorbeelden gebruiken `tenantId: "demo"`, een gedeelde sandbox, en Stap 2 behandelt het overschakelen naar je eigen.

Stap 1: Voeg de widget toe

Kies een urlId voordat je publiceert

Reacties behouden zonder JavaScript

Stap 2: Gebruik je eigen account

Read it from an environment variable

EU accounts

Reactietellingen op een indexpagina

Beveiligde SSO met std/oauth

Build the payload on the server

Pass it to the widget

Things that go wrong

Webhooks ontvangen

Twee dingen die bijten

Gebeurtenissen afhandelen

Voorbeeld Vals

Domeinfouten

Taal 🇳🇱 Nederlands

Val Town Installatie

Live commentaar toevoegen aan Val Town-apps

Je hebt geen account nodig om het te proberen. De voorbeelden gebruiken tenantId: "demo", een gedeelde sandbox, en Stap 2 behandelt het overschakelen naar je eigen.

Stap 1: Voeg de widget toe

Kies een urlId voordat je publiceert

Reacties behouden zonder JavaScript

Stap 2: Gebruik je eigen account

Read it from an environment variable

EU accounts

Reactietellingen op een indexpagina

Beveiligde SSO met std/oauth

Build the payload on the server

Pass it to the widget

Things that go wrong

Webhooks ontvangen

Twee dingen die bijten

Gebeurtenissen afhandelen

Voorbeeld Vals

Domeinfouten

Je hebt geen account nodig om het te proberen. De voorbeelden gebruiken `tenantId: "demo"`, een gedeelde sandbox, en Stap 2 behandelt het overschakelen naar je eigen.