Skip to main content
Introducing packages.sweber.dev
Documentation menuGetting started

Getting started

Build a feed and add the widget in five minutes.

  1. Install the package:

    pnpm add @sweberdev/derivative
    

    With npm: npm i @sweberdev/derivative.

  2. Set it up in one step:

    npx derivative init
    

    init looks at the project, writes derivative.config.json (source and output files) and puts derivative build in front of your build script, so the feed is rebuilt with every deploy. It never overwrites an existing config; pass --no-scripts to leave package.json alone. To do the same by hand, read on.

    Build the feed. With a CHANGELOG.md in the project root (for example from Changesets):

    npx derivative build
    

    Without a changelog file, Derivative reads your git history instead. It needs version tags (v1.2.0) and conventional commits (feat:, fix:):

    npx derivative build --source git
    

    Both write public/changelog.json. Add the build to your build script so the feed is always current:

    { "scripts": { "build": "derivative build && vite build" } }
    
  3. Add the widget where the button should appear, for example in your header:

    <derivative-widget src="/changelog.json" lang="de"></derivative-widget>
    <script type="module">
      import "@sweberdev/derivative/widget";
    </script>
    

    In React, use the React component instead.

  4. Open the app. The button shows how many releases are new, and opening it marks them as seen.

Requirements

  • Node.js 22 or newer for the CLI
  • git on the PATH for --source git and for release dates of Changesets changelogs
  • Any current browser for the widget (custom elements and shadow DOM)