DerivativeLive demo.
Everything on this page runs the real @sweberdev/derivative build in your browser: the widget in the made-up app below, and the parsers in the playground further down.
Nothing you paste is sent anywhere. The widget remembers what you have seen in this browser's local storage only.
Widget
What's new, in your appClick the button.
Muster Ledger is a made-up bookkeeping app. The button in its header is <derivative-widget>, fed by the changelog.json built below. The badge counts releases you have not seen yet; opening the panel marks them as read.
Your app goes here. The widget is one element and about 6 kB gzipped, with no requests other than the feed itself.
Forgets what you have seen, like a first visit.
Build
From changelog to feedOne command.
derivative build reads the CHANGELOG.md that Changesets already writes, adds the highlights from the config and writes a static changelog.json next to your app. Hashes, thank-you notes and dependency updates are left out.
CHANGELOG.md
# @muster/ledger
## 3.2.0
### Minor Changes
- 8c1f2ab: Dark mode for the whole app. It follows your system setting, or pick it under **Settings → Appearance**.
- [#214](https://git.example/muster/ledger/pull/214) [`4be91d0`](https://git.example/muster/ledger/commit/4be91d0) Thanks [@mira](https://git.example/mira)! - Export the journal as `CSV` for your accountant
### Patch Changes
- 1d7e3c9: Swiss franc amounts are rounded to 5 centimes again on QR invoices.
- Updated dependencies [8c1f2ab]
- @muster/ui@3.2.0
## 3.1.0
### Minor Changes
- 77a01e5: Recurring invoices: send the same invoice every month or quarter.
### Patch Changes
- c40d2b8: The receipt scanner reads dates written as `05.10.26`.
## 3.0.0
### Major Changes
- 0f3e9aa: Sign-in now requires a second factor for every account.
Set it up under **Account → Security** before 1 November.
### Minor Changes
- e19b4c2: Invite your fiduciary with read-only access.
derivative.config.json
{
"title": "Muster Ledger changelog",
"link": "/changelog",
"highlights": {
"3.2.0": {
"title": "Dark mode is here",
"summary": "Muster Ledger now follows your system theme. Easier on the eyes for late-night bookkeeping."
}
},
"out": { "json": "changelog.json" }
}
Build step
npx derivative build
derivative: 3 releases, 7 entries
wrote public/changelog.jsonpublic/changelog.json
{
"version": 1,
"releases": [
{
"id": "3.2.0",
"entries": [
{
"type": "feature",
"text": "Dark mode for the whole app. It follows your system setting, or pick it under **Settings → Appearance**."
},
{
"type": "feature",
"text": "Export the journal as `CSV` for your accountant",
"link": "https://git.example/muster/ledger/pull/214"
},
{
"type": "fix",
"text": "Swiss franc amounts are rounded to 5 centimes again on QR invoices."
}
],
"version": "3.2.0",
"title": "Dark mode is here",
"summary": "Muster Ledger now follows your system theme. Easier on the eyes for late-night bookkeeping.",
"date": "2026-10-01"
},
{
"id": "3.1.0",
"entries": [
{
"type": "feature",
"text": "Recurring invoices: send the same invoice every month or quarter."
},
{
"type": "fix",
"text": "The receipt scanner reads dates written as `05.10.26`."
}
],
"version": "3.1.0",
"date": "2026-09-12"
},
{
"id": "3.0.0",
"entries": [
{
"type": "breaking",
"text": "Sign-in now requires a second factor for every account.",
"details": "Set it up under **Account → Security** before 1 November."
},
{
"type": "feature",
"text": "Invite your fiduciary with read-only access."
}
],
"version": "3.0.0",
"date": "2026-08-20"
}
],
"title": "Muster Ledger changelog",
"link": "/changelog"
}Embed
<derivative-widget src="/changelog.json"></derivative-widget>
<script type="module">
import "@sweberdev/derivative/widget"
</script>Playground
Try your own changelogPaste and watch.
Pick a format or paste your own. The same parsers as the CLI turn it into a feed, shown as JSON and in the inline mode of the widget.
Widget, inline mode
Loading the parsers
Free 2.0
Release communication, not just a changelogDerivative, free.
Derivative 2.0 turns the MIT widget from a list of changes into a way to talk to your readers: a richer feed, a modal and banner for the releases that matter, audiences, translations and hints in your product.
Feed format 2 with media, links and importance
Mark a release as major and give it a title, a summary, an image and a call to action. The build writes it into changelog.json, the Atom feed and the HTML page.
derivative.config.json, then npx derivative build
{
"highlights": {
"2.4.0": {
"title": "Dark mode is here",
"summary": "Switch it on under **Settings → Appearance**.",
"importance": "major",
"media": [{ "type": "image", "url": "/changelog/dark-mode.png", "alt": "The dashboard in dark mode" }],
"links": [{ "label": "Read the guide", "url": "https://acme.ch/docs/dark-mode" }]
}
}
}public/changelog.json (real output, trimmed)
{
"version": 2,
"releases": [
{
"id": "2.4.0",
"entries": [ ... 3 entries ... ],
"version": "2.4.0",
"title": "Dark mode is here",
"summary": "Switch it on under **Settings → Appearance**.",
"importance": "major",
"media": [
{ "type": "image", "url": "/changelog/dark-mode.png", "alt": "The dashboard in dark mode" }
],
"links": [
{ "label": "Read the guide", "url": "https://acme.ch/docs/dark-mode" }
]
},
...
]
}Highlight as toast, banner or modal
One attribute announces the newest unread release with a title, once per reader. Major releases win over newer minor ones, and the modal shows the image and links. This replaces announce from 1.x.
Widget markup
<derivative-widget src="/changelog.json" highlight="modal"></derivative-widget>
<script type="module">
import "@sweberdev/derivative/widget";
</script>Audiences, translations and hints
Show entries only to the readers they matter to, serve titles and entry texts in the reader's language, and let the widget mark the page element an entry is about with data-derivative-hint. Set audience="pro" and hints on the widget.
Node script using parseFeed and localizeRelease
import { parseFeed, localizeRelease } from "@sweberdev/derivative";
const feed = parseFeed({
version: 2,
releases: [{
id: "2.4.0", version: "2.4.0", title: "Dark mode is here",
translations: {
de: { title: "Dunkelmodus ist da", entries: { "ACME-12": "Dunkelmodus für das Dashboard" } }
},
entries: [
{ id: "ACME-12", type: "feature", text: "Dark mode for the dashboard", target: "#theme-switch" },
{ type: "fix", text: "Rounding of Swiss francs", audience: ["pro"] }
]
}]
});
const de = localizeRelease(feed.releases[0], "de");
console.log(de.title, de.entries.map((e) => e.text));Output (real)
{
"title": "Dunkelmodus ist da",
"entries": [
"Dunkelmodus für das Dashboard",
"Rounding of Swiss francs"
]
}
(the entry without a translation falls back to the original text)Old widgets keep working
Format 2 is a superset of format 1, and 1.x feeds are still read. If pages with an old widget cache your feed, keep writing the old format for a while.
Write a format 1 feed
npx derivative build --feed-format 1public/changelog.json (real output, trimmed)
derivative: 2 releases, 4 entries
wrote public/changelog-v1.json
{
"version": 1,
"releases": [
{
"id": "2.4.0",
"entries": [ ... 3 entries ... ],
"version": "2.4.0",
"title": "Dark mode is here",
"summary": "Switch it on under **Settings → Appearance**.",
"image": "/changelog/dark-mode.png"
},
...
]
}Linear, Jira and Notion as sources (beta)
Read what shipped straight from a tracker, read-only, with an API token that you keep in the environment. The readers are tested against fixtures of the documented API responses, not against live accounts yet.
derivative.config.json for Linear
{ "source": "linear", "linear": { "team": "ENG" } }Upgrading from 1.x? Rename announce to highlight and use Node.js 22 or newer. The migration guide lists every change.
Read the docsPro 2.1.0
Import releases, hear from readersDerivative Pro.
Pro 2.1.0 pulls release notes from Linear, Jira and Notion into your approval workflow, and lets readers react and comment under each release. Both run on your own backend and database.
Import from Linear, Jira and NotionBeta
Read cycles, versions and pages from the tracker your team already uses. Every release arrives as a draft with a link per entry, never straight in the feed.
Terminal
export LINEAR_API_KEY=... # never committed
npx derivative-segments import --source linear --team ENG --since 2026-01-01
npx derivative-segments import --source jira --url https://acme.atlassian.net --project WEB
npx derivative-segments import --source notion --database <id> --props published=LiveSafe to run againBeta
Imports read all pages and retry on rate limits and server errors. A draft already in review or approved is never overwritten, and labels map to entry types.
Terminal
npx derivative-segments import --source jira --url https://acme.atlassian.net --project WEB --map bug=fix,story=featureReactions and comments per release
Add a comment handler to your backend and one line to the page. Readers open the section under a release, and nothing loads before that.
app/api/comments/route.ts
import { createCommentsHandler, sqlCommentStore } from "@weber-development/derivative-insights";
const store = sqlCommentStore(query, { dialect: "postgres" }); // call store.setup() once
const handler = createCommentsHandler({ store, allow: yourRateLimiter });
export const GET = handler;
export const POST = handler;
// in the browser
import { addComments } from "@weber-development/derivative-insights";
addComments(document, { endpoint: "/api/comments" });Moderation you control
Comments are plain text and held back until you approve them. A protected handler lists, approves, rejects or deletes them.
Moderation handler
import { createModerationHandler, bearerAuth } from "@weber-development/derivative-insights";
const moderate = createModerationHandler({ store, authorize: bearerAuth(token) });
// GET ?status=pending lists
// POST {id, action: "approve" | "reject" | "delete"} decidesThe demo cannot show these: the import needs your own tracker account (it is Beta, tested against mock servers only) and comments need your own backend and database.
Read the docsNext step
Add it to your appFree and MIT-licensed.
Install @sweberdev/derivative, add derivative build to your build script and drop the element into your header. React apps can use @sweberdev/derivative-react.