Agregar Comentarios en Vivo a las Aplicaciones de Val Town

Val Town ejecuta TypeScript en Deno, por lo que un val es un servidor real. Eso lo hace adecuado para FastComments: el widget es una etiqueta script en la página, y cualquier cosa que necesite un secreto, como Secure SSO o la verificación de un webhook, puede ejecutarse del lado del servidor en el mismo val.

Esta guía cubre cómo agregar el widget de comentarios a un val HTTP, mostrar recuentos de comentarios en una página de índice, iniciar sesión de usuarios con la cuenta de Val Town que ya poseen, y recibir webhooks de comentarios.

No necesitas una cuenta para probarlo. Los ejemplos usan tenantId: "demo", un sandbox compartido, y el Paso 2 cubre cómo cambiar a tu propio.

Paso 1: Añadir el 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.

Widget de comentarios en 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;

Elija un urlId antes de lanzar

urlId decide en qué hilo cae un comentario. Déjelo sin establecer y por defecto será una versión limpiada de la URL de la página actual, que es exactamente lo que cambia en Val Town: un val tiene un hostname largo *.web.val.run hasta que reclama un subdominio, las ramas obtienen sus propias URLs, y renombrar una página cambia la ruta. Cada variación se convierte silenciosamente en un hilo separado y vacío, y el síntoma se lee como “mis comentarios desaparecieron”.

Establézcalo a algo estable que usted controle, como el slug de la publicación o un id de base de datos, como se muestra arriba. Pase también url, para que los correos electrónicos de notificación y las herramientas de moderación puedan enlazar de vuelta a la página real.

Mantener comentarios sin JavaScript

FastComments renderiza un hilo completo del lado del servidor, que un val puede colocar dentro de un bloque <noscript>:

Alternativa sin 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>

Codifique los parámetros en URL. La versión del lado del servidor admite comentarios anónimos y con sesión iniciada, SSO y respuestas anidadas.

Paso 2: Usa tu propia cuenta

tenantId: "demo" es un sandbox público compartido. Funciona sin registro, por eso los ejemplos lo usan, pero todos los demás que prueban FastComments escriben en los mismos hilos y cualquiera puede moderarlos. Cambia antes de publicar cualquier cosa que te importe.

Tu ID de inquilino está en la página de secretos de API.

Un ID de inquilino es público y pertenece al código del navegador. Un secreto de API no lo es, y nada en esta página necesita uno.

Léelo desde una variable de entorno

Los vals de Val Town son públicos en el nivel gratuito, por lo que su origen es legible por todos. Mantén cualquier cosa sensible en variables de entorno, leídas con 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";

Esto es más importante de lo habitual en Val Town por una segunda razón: remixar un val copia las claves de variables de entorno, pero no sus valores. Un secreto guardado en una variable de entorno no sigue a tu val en la cuenta de otra persona. Un secreto escrito en un archivo sí lo hace.

Revertir a "demo" mantiene el val funcionando para cualquiera que lo remixe antes de establecer su propio inquilino.

Cuentas EU

Una cuenta, sus datos y sus claves viven en una sola región. Si la tuya se creó en eu.fastcomments.com, cada configuración de widget también necesita region: "eu", y los scripts se cargan desde cdn-eu.fastcomments.com. De lo contrario, déjalos tal cual.

Conteo de Comentarios en una Página de Índice

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:

Recuentos de comentarios en bloque en un índice

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.

SSO Seguro con 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) {
  // el id debe ser estable para la misma persona, o recibirán una nueva identidad de comentario en cada inicio de sesión.
  const id = `vt-${user.id}`;
  return new SecureSSOPayloadBuilder(Deno.env.get("FASTCOMMENTS_API_SECRET"), {
    id,
    // el correo electrónico es obligatorio y debe ser único.
    email: user.email ?? `${id}@users.noreply.val.town`,
    // el nombre de usuario es obligatorio y no puede ser un correo electrónico.
    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.

Configuración del widget con 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" } }),
  };
  // ...renderizar el widget con esta configuración
});
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.

Recibiendo Webhooks

A val es un receptor de webhook natural: tiene una URL estable, puede verificar una firma y tiene SQLite y almacenamiento de blobs incorporados.

FastComments firma ${timestamp}.${body} con el secreto API de tu cuenta y envía dos encabezados:

Encabezados del webhook

Copy

Run

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

El método lleva el evento: PUT para un comentario creado o actualizado, DELETE para uno eliminado.

Verificando una entrega

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

Dos cosas que muerden

Verifica los bytes crudos. Analizar el JSON y volver a serializarlo cambia el orden de las claves y los espacios en blanco, por lo que el hash difiere y cada entrega falla sin una causa evidente. Esta es la razón habitual por la que un receptor de webhook "simplemente no funciona".

Compara en tiempo constante. Un simple === sobre la firma revela cuántos bytes coinciden, lo que es suficiente para falsificar un byte a la vez.

Manejo de eventos

Responde rápidamente. FastComments reintenta en caso de una respuesta que no sea 2xx, y un endpoint que sigue fallando se desactiva automáticamente al final, así que realiza el trabajo real después de responder en lugar de hacerlo en línea.

Haz que ese trabajo sea idempotente respecto al id del comentario. Un reintento se vuelve a firmar con una marca de tiempo nueva, y el mismo id de comentario llega de nuevo en la edición y eliminación, por lo que no hay nada estable sobre lo que deduplicar.

Vals de ejemplo

Cuatro vals públicos que puedes remezclar, cada uno cubriendo una parte de esta guía.

Blog con comentarios (live) es un blog en Markdown con un hilo bajo cada publicación y recuentos de comentarios en bloque en el índice. Funciona en el momento en que lo remezclas, y una variable de entorno lo apunta a tu propia cuenta.

Demo SSO (live) inicia sesión al visitante con su cuenta de Val Town y entrega esa identidad al widget, por lo que no hay un segundo inicio de sesión.

Receptor de Webhook (live) verifica la firma HMAC en cada entrega y almacena los eventos en SQLite. Tiene un botón que firma una carga de prueba y la entrega a sí mismo, para que puedas observar la verificación exitosa antes de configurar un webhook real.

Habilidades de agente (live) es una biblioteca de habilidades de agente de FastComments que cubren el widget, SSO, la API REST, la moderación y la migración desde Disqus. Remezcla esto y el agente de Val Town, Townie, recoge automáticamente las habilidades de skills/, de modo que tu agente sepa cómo integrar los comentarios sin que tengas que pegar la documentación en el chat.

Las mismas habilidades se instalan en cualquier otro lugar con npx skills add fastcomments/skills.

Errores de dominio

Una vez que desactives el inquilino demo, el widget puede negarse a cargarse con un error de autorización. Esto se debe a que FastComments no sabe que debe permitir que tu cuenta se use en ese dominio.

Ve aquí para agregar tu sitio a tu cuenta.

Val Town merece una segunda mirada aquí, porque un val puede ser accesible en más de un nombre de host:

Cada val HTTP tiene un endpoint predeterminado largo, <org>--<id>.web.val.run.
Reclamar un subdominio personalizado agrega <name>.val.run.
Un dominio personalizado agrega un tercero.
Las ramas obtienen sus propias URLs.

Agrega los nombres de host desde los que realmente sirvas el widget. Si reclamas un subdominio después de configurar todo, agrégalo también, de lo contrario el widget funcionará en la URL antigua y fallará en la nueva.

Instalación de Val Town

Agregar Comentarios en Vivo a las Aplicaciones de Val Town

Paso 1: Añadir el Widget

Elija un urlId antes de lanzar

Mantener comentarios sin JavaScript

Paso 2: Usa tu propia cuenta

Léelo desde una variable de entorno

Cuentas EU

Conteo de Comentarios en una Página de Índice

SSO Seguro con std/oauth

Build the payload on the server

Pass it to the widget

Things that go wrong

Recibiendo Webhooks

Dos cosas que muerden

Manejo de eventos

Vals de ejemplo

Errores de dominio

Idioma 🇪🇸 Español

Instalación de Val Town

Agregar Comentarios en Vivo a las Aplicaciones de Val Town

Paso 1: Añadir el Widget

Elija un urlId antes de lanzar

Mantener comentarios sin JavaScript

Paso 2: Usa tu propia cuenta

Léelo desde una variable de entorno

Cuentas EU

Conteo de Comentarios en una Página de Índice

SSO Seguro con std/oauth

Build the payload on the server

Pass it to the widget

Things that go wrong

Recibiendo Webhooks

Dos cosas que muerden

Manejo de eventos

Vals de ejemplo

Errores de dominio