Skip to main content
Introducing packages.sweber.dev
Documentation menuInsights

Insights

Read statistics for the widget with your own endpoint and an HTML report.

@weber-development/derivative-insights listens to the widget's events and sends them to an endpoint on your own server.

Track

import { trackInsights } from "@weber-development/derivative-insights";

const stop = trackInsights(document, { endpoint: "/api/derivative-insights" });
OptionDefault
endpointrequiredYour route that receives events.
sampleRate1Share of page views that send events, 0 to 1.
respectDoNotTracktrueSends nothing when the browser sets Do Not Track or Global Privacy Control.

Three events are sent: open (the panel opened, with the number of unread releases), read (the reader caught up) and click (a link inside a release). Query strings and fragments are removed from every URL before it leaves the browser and again on the server.

Reactions

Ask readers whether a release was useful. addReactions puts a "Was this helpful?" vote (Yes and No, in English, German, French or Italian) under every release in the widget and sends each vote to the same endpoint:

import { addReactions, trackInsights } from "@weber-development/derivative-insights";

trackInsights(document, { endpoint: "/api/derivative-insights" });
addReactions(document, { endpoint: "/api/derivative-insights" });
OptionDefault
endpointrequiredThe same route as for trackInsights.
messagesby languageReplace question, up, down or thanks.
storageKeyderivative:reactionsWhere the browser remembers its own votes.
respectDoNotTracktrueSends no votes when the browser sets Do Not Track or Global Privacy Control.

There is no cookie and no visitor ID. The browser remembers its votes in localStorage, and a changed vote also names the old one, so it replaces it instead of counting twice. The report and the CSV show helpful and not helpful per release, and the report adds the share of helpful votes overall. The bar uses the widget's derivative-render event, so it needs @sweberdev/derivative 0.5.0 or later. Its look follows the widget's CSS variables, and the wrapper has part="reactions" for your own styles.

Reactions and comments

Besides the helpful vote, readers can react with an emoji and leave a comment on a release. Both are stored in your own database and shown in a disclosure under the release, which loads only when a reader opens it.

// app/api/comments/route.ts
import { createCommentsHandler, sqlCommentStore } from "@weber-development/derivative-insights";

const store = sqlCommentStore(query, { dialect: "postgres" }); // run store.setup() once
const handler = createCommentsHandler({ store, allow: yourRateLimiter });
export const GET = handler;
export const POST = handler;
import { addComments } from "@weber-development/derivative-insights";
addComments(document, { endpoint: "/api/comments" }); // comments: false for reactions only
  • Plain text. Comments are stored as typed and shown as text, never as HTML.
  • Pre-moderation. A new comment stays hidden until you approve it. moderation: "post" publishes at once and lets you reject afterwards.
  • Moderation. createModerationHandler({ store, authorize: bearerAuth(token) }) lists comments (GET ?status=pending) and decides them (POST {id, action: "approve" | "reject" | "delete"}). It is never cached; put it behind your own login.
  • Spam. A hidden website field catches simple bots. The library stores no IP address, so it cannot limit requests by itself: pass allow (return false for a 429) and isSpam to plug in your own rate limit or filter.
  • Emojis. 👍 🎉 ❤️ 🤔 by default (emojis changes the set); a browser's own choice is remembered in localStorage so a changed mind moves the count instead of adding one.
  • Stores. memoryCommentStore for tests, sqlCommentStore(query, { dialect }) for Postgres or SQLite (two tables, commentsSetupSql prints the statements).

Comments are personal data that readers type in. You are the controller: mention them in your privacy notice, delete a comment when its author asks, and keep the form's reminder not to enter data that should stay private. Reactions carry no identifier.

Receive

// app/api/derivative-insights/route.ts
import { createInsightsHandler } from "@weber-development/derivative-insights";
import { fileStore } from "@weber-development/derivative-insights/node";

export const POST = createInsightsHandler({
  store: fileStore(".data/insights.ndjson"),
  allowedOrigins: ["https://app.example.com"],
});

The handler works in any runtime with the Fetch API. It answers 204 for valid and invalid events alike, rejects bodies over 8 KiB (maxBytes) and rejects other origins unless they are listed. For a database, implement InsightStore with append(events) and read(since).

Database

On serverless hosts without a persistent disk, keep events in Postgres or SQLite instead of a file. sqlStore needs no driver of its own; pass a function that runs one query:

import { neon } from "@neondatabase/serverless";
import { createInsightsHandler, sqlStore } from "@weber-development/derivative-insights";

const sql = neon(process.env.DATABASE_URL!);
const store = sqlStore((query, params) => sql.query(query, params));
await store.setup(); // once: creates the derivative_insights table

export const POST = createInsightsHandler({ store });

With pg, pass (q, p) => pool.query(q, p).then((r) => r.rows). For SQLite (better-sqlite3, Turso, Cloudflare D1) set { dialect: "sqlite" }. setupSql() returns the CREATE TABLE statements if you run migrations yourself. For the report, read the events in a small script: summarize(await store.read(since), feed) and renderReport(summary).

Report

npx derivative-insights report --events .data/insights.ndjson --feed public/changelog.json \
  --since 2026-09-01 --out insights.html

The report shows opens, reads and clicks per release, the most clicked links and a daily chart. --json summary.json also writes the summary as JSON. --csv releases.csv writes one row per release and releases-daily.csv with opens per day, for Excel or a spreadsheet. In code: summarize(events, feed), renderReport(summary, { title }), releasesCsv(summary) and dailyCsv(summary).

Dashboard route

Serve the dashboard from your own backend instead of generating a file. The handler needs a store, a way to decide who may look, and optionally the feed:

import {
  basicAuth,
  createDashboardHandler,
  sqlStore,
} from "@weber-development/derivative-insights";

export const GET = createDashboardHandler({
  store,
  feed: () => loadFeed(),
  authorize: basicAuth("team", process.env.INSIGHTS_PASSWORD!),
  title: "Acme changelog insights",
});

Open the route in a browser for the report (the last 30 days). ?days=7 narrows the period (1 to 365; defaultDays changes the default), ?format=json returns the summary, and ?format=csv or ?format=csv&table=daily downloads a spreadsheet. authorize is required on purpose, there is no open default: use basicAuth(user, password), bearerAuth(token) for scripts (curl -H "Authorization: Bearer ..."), or your own session check, for example (request) => isAdmin(request). Both helpers compare in constant time. Responses are private, no-store and noindex, and the page carries a Content-Security-Policy that forbids scripts and external requests, so numbers cannot leak through a third-party asset.

Privacy

No cookie is set, no visitor ID is created and the handler stores no IP address. Your server and hosting provider may still log IP addresses on their own. Whether you need consent depends on your jurisdiction and setup; Derivative does not decide that for you.