Skip to main content
Introducing packages.sweber.dev
Derivative overview

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.

Muster LedgerLoading the widget

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.json

public/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 1

public/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 docs

Pro 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=Live

Safe 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=feature

Reactions 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"} decides

The 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 docs

Next 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.