Skip to content

Get started

Install the SDK

Add @chunktrace/sdk to a Node.js project from GitHub Packages.

Requirements#

  • Node.js 22 or newer. That is the version the SDK is tested on.
  • An ES module project ("type": "module" in package.json, or .mjs files). TypeScript types are included.
  • A GitHub account, to read from GitHub Packages.

Point npm at GitHub Packages#

@chunktrace/sdk and @chunktrace/core are published to GitHub Packages, not to npmjs.org. Add this to the .npmrc next to your package.json:

.npmrc
@chunktrace:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

The first line sends only the @chunktrace scope to GitHub. Everything else still comes from npm. The second line reads a token from your environment, so the token itself never lands in the file.

Create a token#

GitHub Packages asks for a token on every install, even for public packages.

  1. On GitHub, open Settings, then Developer settings, then Personal access tokens, then Tokens (classic).
  2. Generate a token with one scope: read:packages.
  3. Put it in your environment:
Terminal
export GITHUB_TOKEN=ghp_your_token_here

Install#

Terminal
npm install @chunktrace/sdk

The SDK re-exports everything in @chunktrace/core, so one import is enough:

JavaScript
import { createProfiler, httpSink, diagnose } from "@chunktrace/sdk";

In CI#

Set GITHUB_TOKEN as a secret in your CI and keep the same .npmrc. In GitHub Actions, the workflow's own token works if you give the job packages: read:

YAML
permissions:
  contents: read
  packages: read
steps:
  - uses: actions/checkout@v6
  - uses: actions/setup-node@v6
    with:
      node-version: 24
  - run: npm ci
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Troubleshooting#

What you see What it means
401 Unauthorized from npm.pkg.github.com GITHUB_TOKEN is not set in this shell, or the token has expired.
403 Forbidden The token is missing the read:packages scope.
404 Not Found for @chunktrace/sdk npm is asking npmjs.org. Check that .npmrc is next to package.json and has the @chunktrace:registry line.

Next#

Trace a query shows the five calls that record a trace.