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" });
| Option | Default | |
|---|---|---|
endpoint | required | Your route that receives events. |
sampleRate | 1 | Share of page views that send events, 0 to 1. |
respectDoNotTrack | true | Sends 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" });
| Option | Default | |
|---|---|---|
endpoint | required | The same route as for trackInsights. |
messages | by language | Replace question, up, down or thanks. |
storageKey | derivative:reactions | Where the browser remembers its own votes. |
respectDoNotTrack | true | Sends 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
websitefield catches simple bots. The library stores no IP address, so it cannot limit requests by itself: passallow(returnfalsefor a 429) andisSpamto plug in your own rate limit or filter. - Emojis. 👍 🎉 ❤️ 🤔 by default (
emojischanges the set); a browser's own choice is remembered inlocalStorageso a changed mind moves the count instead of adding one. - Stores.
memoryCommentStorefor tests,sqlCommentStore(query, { dialect })for Postgres or SQLite (two tables,commentsSetupSqlprints 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.