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"inpackage.json, or.mjsfiles). 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:
@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.
- On GitHub, open Settings, then Developer settings, then Personal access tokens, then Tokens (classic).
- Generate a token with one scope:
read:packages. - Put it in your environment:
export GITHUB_TOKEN=ghp_your_token_hereInstall#
npm install @chunktrace/sdkThe SDK re-exports everything in @chunktrace/core, so one import is enough:
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:
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.