Astro, Nuxt, SvelteKit

createFetchMiddleware returns a function with this shape:

(context: { request: Request }, next: () => Promise<Response>) => Promise<Response>

That is exactly Astro’s middleware signature, so on Astro you export it directly. Every other framework has its own shape and needs two or three lines to bridge. They are all below.

Do not export const handle = createFetchMiddleware(beacon) on SvelteKit, or use it as a Nitro handler on Nuxt. Those frameworks call middleware differently and the export will silently never run.

Install

npm install @snowseo/beacon

.env

SNOWSEO_BEACON_KEY=sb_live_...

No VITE_ or PUBLIC_ prefix. Those are inlined into the client bundle, which publishes the key.

Create the beacon once and import it where you need it:

src/lib/beacon.ts

import { createBeacon } from "@snowseo/beacon";

export const beacon = createBeacon({
  siteUrl: "https://example.com",
  dir: "dist",
  analytics: { key: process.env.SNOWSEO_BEACON_KEY! },
});

Wiring it up

// src/middleware.ts
import { createFetchMiddleware } from "@snowseo/beacon";
import { beacon } from "./lib/beacon";

export const onRequest = createFetchMiddleware(beacon);

// src/hooks.server.ts
import { createFetchMiddleware } from "@snowseo/beacon";
import type { Handle } from "@sveltejs/kit";
import { beacon } from "$lib/beacon";

const middleware = createFetchMiddleware(beacon);

export const handle: Handle = ({ event, resolve }) =>
  middleware({ request: event.request }, () => resolve(event));

import { createFetchMiddleware } from "@snowseo/beacon";
import { beacon } from "./lib/beacon";

const middleware = createFetchMiddleware(beacon);

// Hono's next() resolves to void, so read the response back off the context.
app.use(async (c, next) => {
  c.res = await middleware({ request: c.req.raw }, async () => {
    await next();
    return c.res;
  });
});

import { createFetchMiddleware } from "@snowseo/beacon";
import { beacon } from "./lib/beacon";

const middleware = createFetchMiddleware(beacon);

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    return middleware(
      { request, waitUntil: (p) => ctx.waitUntil(p) },
      () => handleRequest(request, env),
    );
  },
};

import { createFetchMiddleware } from "@snowseo/beacon";
import { beacon } from "./lib/beacon.ts";

const middleware = createFetchMiddleware(beacon);

Deno.serve((request) => middleware({ request }, () => handleRequest(request)));

import { createFetchMiddleware } from "@snowseo/beacon";
import { beacon } from "./lib/beacon";

const middleware = createFetchMiddleware(beacon);

export default async (request: Request, context: Context) =>
  middleware(
    { request, waitUntil: (p) => context.waitUntil(p) },
    () => context.next(),
  );

Verify any of them:

curl -A "GPTBot/1.2" https://example.com/
curl -H "Accept: text/markdown" https://example.com/

Nuxt

Nuxt is the awkward one. Nitro middleware runs before the route handler and cannot wrap its response, so createFetchMiddleware does not fit. Serving twins and reporting hits still work; advertising the twin on HTML responses has to be done by hand.

server/middleware/beacon.ts

import { appendLink, mergeVary } from "@snowseo/beacon";
import { beacon } from "../utils/beacon";

export default defineEventHandler(async (event) => {
  const request = toWebRequest(event);

  // Returning a Response short-circuits the route handler.
  const twin = await beacon.handle(request);
  if (twin) {
    return twin;
  }

  const path = new URL(request.url).pathname;
  if (await beacon.hasTwin(path, request)) {
    const link = `<${beacon.markdownUrlFor(path)}>; rel="alternate"; type="text/markdown"`;
    setResponseHeader(event, "Link", appendLink(getResponseHeader(event, "Link") as string ?? null, link));
    setResponseHeader(event, "Vary", mergeVary(getResponseHeader(event, "Vary") as string ?? null, "Accept"));
  }

  beacon.track(request, { format: "html", path });
});

The Vary: Accept line is not optional. Without it a cache can hand the HTML copy to a client that asked for Markdown, or the reverse.

Serverless runtimes

On Workers, Netlify Edge and similar, pass the platform’s waiting context so a pending report is not killed when the response returns. The snippets above already do:

{ request, waitUntil: (p) => ctx.waitUntil(p) }

Without it the report is cancelled mid-flight and the hit is simply lost, with no error anywhere.

Options

analytics: {
  key: process.env.SNOWSEO_BEACON_KEY!,
  endpoint: "https://beacon.example.com",  // your own collector
  disableCategories: ["training"],         // report only what you want
  onHit: (hit, match) => log.info(match.agent, hit.path),
  onError: (error) => log.warn(error),
}

endpoint accepts a bare origin; the ingest path is appended for you. See self-hosting to run your own, and the SDK reference for every option.

Overview

Install

Self-hosting

Reference

Troubleshooting

Astro, Nuxt, SvelteKit

Install

Wiring it up

Nuxt

Serverless runtimes

Options

​Install

​Wiring it up

​Nuxt

​Serverless runtimes

​Options

Install

Wiring it up

Nuxt

Serverless runtimes

Options