Ajouter les commentaires en direct aux applications Val Town

Val Town exécute TypeScript sur Deno, donc un val est un vrai serveur. Cela en fait un bon choix pour FastComments : le widget est une balise script sur la page, et tout ce qui nécessite un secret, comme le SSO sécurisé ou la vérification d’un webhook, peut s’exécuter côté serveur dans le même val.

Ce guide couvre l’ajout du widget de commentaires à un val HTTP, l’affichage du nombre de commentaires sur une page d’index, la connexion des utilisateurs avec le compte Val Town qu’ils possèdent déjà, et la réception des webhooks de commentaires.

Vous n’avez pas besoin de compte pour l’essayer. Les exemples utilisent tenantId: "demo", un bac à sable partagé, et l’étape 2 explique comment passer au vôtre.

Étape 1 : Ajouter le widget

Le widget est une balise script et un élément conteneur, il s’insère donc où que votre val rende déjà. Cet exemple utilise Hono JSX, qui est ce que les modèles HTTP de Val Town utilisent.

Widget de commentaire dans un val HTTP

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;

Choisissez un urlId avant de déployer

urlId détermine dans quel fil un commentaire atterrit. Laissez‑le non défini et il prendra par défaut une version nettoyée de l’URL de la page actuelle, ce qui correspond exactement à ce qui change sur Val Town : un val possède un long nom d’hôte *.web.val.run jusqu’à ce que vous réclamiez un sous‑domaine, les branches obtiennent leurs propres URL, et le renommage d’une page modifie le chemin. Chaque variation devient silencieusement un fil séparé et vide, et le symptôme apparaît comme « mes commentaires ont disparu ».

Attribuez‑lui quelque chose de stable que vous contrôlez, comme le slug du post ou un identifiant de base de données, comme ci‑dessus. Transmettez également url, afin que les e‑mails de notification et les outils de modération puissent renvoyer à la vraie page.

Conserver les commentaires sans JavaScript

FastComments rend un fil complet côté serveur, qu’un val peut placer dans un bloc <noscript> :

Solution de secours sans 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>

Encodez les paramètres dans l’URL. La version côté serveur prend en charge les commentaires anonymes et connectés, le SSO et les réponses imbriquées.

Étape 2 : Utiliser votre propre compte

tenantId: "demo" est un bac à sable public partagé. Il fonctionne sans inscription, c’est pourquoi les exemples l’utilisent, mais tous les autres utilisateurs de FastComments écrivent dans les mêmes fils et n’importe qui peut les modérer. Changez-le avant de publier quoi que ce soit d’important.

Votre ID de locataire se trouve sur la page des secrets API.

Un ID de locataire est public et doit être présent dans le code du navigateur. Un secret API ne l’est pas, et rien sur cette page n’en a besoin.

Lire depuis une variable d’environnement

Les vals de Val Town sont publiques dans le niveau gratuit, donc leur source est lisible par tous. Conservez tout ce qui est sensible dans des variables d’environnement, lues avec Deno.env.get :

config.ts

Copy

Run

export const TENANT_ID = Deno.env.get("FASTCOMMENTS_TENANT_ID") ?? "demo";
// Seuls les comptes créés sur eu.fastcomments.com définissent cela, à "eu".
export const REGION = Deno.env.get("FASTCOMMENTS_REGION") ?? "";
export const CDN = REGION === "eu"
  ? "https://cdn-eu.fastcomments.com"
  : "https://cdn.fastcomments.com";

Cela importe plus que d’habitude sur Val Town pour une deuxième raison : remixer un val copie les clés des variables d’environnement, mais pas leurs valeurs. Un secret stocké dans une variable d’environnement ne suit pas votre val dans le compte d’un autre utilisateur. Un secret écrit dans un fichier le fait.

Revenir à "demo" permet au val de fonctionner pour quiconque le remixe avant de définir son propre locataire.

Comptes EU

Un compte, ses données et ses clés résident dans une seule région. Si le vôtre a été créé sur eu.fastcomments.com, chaque configuration de widget doit également contenir region: "eu", et les scripts se chargent depuis cdn-eu.fastcomments.com. Sinon, laissez les deux tels quels.

Nombre de commentaires sur une page d'index

Sur une page d'index, n'affichez pas un widget de compteur de commentaires par ligne. Cela représente une requête par article. Utilisez le comptage en masse, qui ne nécessite qu'une seule requête pour toute la page.

Marquez chaque ligne avec le urlId utilisé par son fil, puis chargez le widget en masse une seule fois :

Comptes de commentaires en masse sur un 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>

Le script trouve chaque élément .fast-comments-count sur la page et remplit son compteur.

data-fast-comments-url-id doit correspondre au urlId utilisé par le widget de commentaires du post. Si le widget utilise le slug, le marqueur utilise le slug. Un décalage affiche zéro sur un fil qui possède des commentaires.

Le script interroge window.FastCommentsBulkCountConfig, il n'importe donc pas si vous définissez la configuration avant ou après la balise script.

SSO sécurisé avec 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) {
  // l'identifiant doit être stable pour la même personne, sinon ils obtiennent une nouvelle identité de commentaire à chaque connexion.
  const id = `vt-${user.id}`;
  return new SecureSSOPayloadBuilder(Deno.env.get("FASTCOMMENTS_API_SECRET"), {
    id,
    // l'email est requis et doit être unique.
    email: user.email ?? `${id}@users.noreply.val.town`,
    // le nom d'utilisateur est requis et ne peut pas être un 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.

Configuration du widget avec 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" } }),
  };
  // ...rendre le widget avec cette configuration
});
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.

Réception des webhooks

A val est un récepteur de webhook naturel : il possède une URL stable, il peut vérifier une signature, et il intègre SQLite et le stockage de blobs.

FastComments signe ${timestamp}.${body} avec le secret API de votre compte et envoie deux en‑têtes :

En‑têtes du webhook

Copy

Run

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

La méthode transporte l'événement : PUT pour un commentaire créé ou mis à jour, DELETE pour un commentaire supprimé.

Vérification d'une livraison

Copy

Run

import { createHmac, timingSafeEqual } from "node:crypto";
async function receive(c) {
  // Les octets exacts reçus. N'utilisez PAS c.req.json() et ne les re‑sérialisez pas.
  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 });
  // Rejeter les livraisons obsolètes afin qu'une requête capturée ne puisse pas être rejouée plus tard.
  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 });
  }
  // ...traiter JSON.parse(rawBody)
  return Response.json({ received: true });
}
app.put("/", receive);
app.delete("/", receive);

Deux choses qui posent problème

Vérifier les octets bruts. Analyser le JSON et le re‑sérialiser modifie l'ordre des clés et les espaces, ainsi le hachage diffère et chaque livraison échoue sans cause évidente. C’est la raison habituelle pour laquelle un récepteur de webhook « ne fonctionne tout simplement pas ».

Comparer en temps constant. Un simple === sur la signature révèle le nombre d'octets correspondants, ce qui suffit à falsifier un octet à la fois.

Gestion des événements

Répondez rapidement. FastComments réessaye en cas de réponse non‑2xx, et un point de terminaison qui échoue continuellement est finalement désactivé automatiquement, il faut donc effectuer le vrai travail après avoir répondu plutôt qu’en ligne.

Rendez cela idempotent sur l'ID du commentaire. Un nouveau essai est re‑signé avec un nouveau horodatage, et le même ID de commentaire arrive de nouveau lors d'une modification ou d'une suppression, il n’y a donc rien de stable sur quoi dédupliquer.

Exemples de Vals

Quatre vals publics que vous pouvez remixer, chacun couvrant une partie de ce guide.

Blog avec commentaires (en direct) est un blog Markdown avec un fil de discussion sous chaque article et des comptes de commentaires en masse sur l'index. Il fonctionne dès que vous le remixer, et une variable d'environnement le pointe vers votre propre compte.

Démo SSO (en direct) connecte le visiteur avec son compte Val Town et transmet cette identité au widget, de sorte qu'il n'y ait pas de deuxième connexion.

Récepteur de webhook (en direct) vérifie la signature HMAC à chaque livraison et stocke les événements dans SQLite. Il possède un bouton qui signe une charge utile de test et la délivre à lui-même, vous permettant de voir la vérification réussir avant de configurer un vrai webhook.

Compétences d'agent (en direct) est une bibliothèque de compétences d'agent FastComments couvrant le widget, le SSO, l'API REST, la modération et la migration depuis Disqus. Remixez-le et l'agent de Val Town, Townie, récupère automatiquement les compétences dans skills/, de sorte que votre agent sache comment configurer les commentaires sans que vous ayez à coller la documentation dans le chat.

Les mêmes compétences s'installent partout ailleurs avec `npx skills add fastcomments/skills`.

Erreurs de domaine

Une fois que vous désactivez le locataire demo, le widget peut refuser de se charger avec une erreur d'autorisation. Cela est dû au fait que FastComments ne sait pas qu'il doit autoriser votre compte à être utilisé sur ce domaine.

Allez ici pour ajouter votre site à votre compte.

Val Town mérite un second examen ici, car un val peut être accessible à partir de plusieurs noms d'hôte :

Chaque val HTTP possède un point de terminaison par défaut long, <org>--<id>.web.val.run.
Revendiquer un sous-domaine personnalisé ajoute <name>.val.run.
Un domaine personnalisé ajoute un troisième.
Les branches obtiennent leurs propres URL.

Ajoutez les noms d'hôte depuis lesquels vous servez réellement le widget. Si vous revendiquez un sous-domaine après avoir configuré les choses, ajoutez-le également, sinon le widget fonctionnera sur l'ancienne URL et échouera sur la nouvelle.

Installation de Val Town

Ajouter les commentaires en direct aux applications Val Town

Étape 1 : Ajouter le widget

Choisissez un urlId avant de déployer

Conserver les commentaires sans JavaScript

Étape 2 : Utiliser votre propre compte

Lire depuis une variable d’environnement

Comptes EU

Nombre de commentaires sur une page d'index

SSO sécurisé avec std/oauth

Build the payload on the server

Pass it to the widget

Things that go wrong

Réception des webhooks

Deux choses qui posent problème

Gestion des événements

Exemples de Vals

Les mêmes compétences s'installent partout ailleurs avec `npx skills add fastcomments/skills`.

Erreurs de domaine

Langue 🇫🇷 Français (France)

Installation de Val Town

Ajouter les commentaires en direct aux applications Val Town

Étape 1 : Ajouter le widget

Choisissez un urlId avant de déployer

Conserver les commentaires sans JavaScript

Étape 2 : Utiliser votre propre compte

Lire depuis une variable d’environnement

Comptes EU

Nombre de commentaires sur une page d'index

SSO sécurisé avec std/oauth

Build the payload on the server

Pass it to the widget

Things that go wrong

Réception des webhooks

Deux choses qui posent problème

Gestion des événements

Exemples de Vals

Les mêmes compétences s'installent partout ailleurs avec npx skills add fastcomments/skills.

Erreurs de domaine

Les mêmes compétences s'installent partout ailleurs avec `npx skills add fastcomments/skills`.