Getting started

Installation

Install the SDK from npm, or load the standalone script with a script tag.

npm

Shell

npm install @kymoscope/sdk react react-dom

react and react-dom 19 are peer dependencies of the ESM build. The package ships these files:

File	Use it for
`dist/kymoscope-sdk.js`	ESM entry (@kymoscope/sdk): the engine, chart kinds, settings types and helpers. react and react-dom are peer dependencies.
`dist/react.js`	ESM entry @kymoscope/sdk/react: KymoscopeProvider, useEngine, useEngineState, <Chart>.
`dist/kymoscope-embed.js`	The standalone script: React bundled, global Kymoscope.createEngine.
`dist/assets/*`	Web workers, and DuckDB-WASM (bundled, never fetched from a CDN). Serve them next to the JavaScript file.
`dist/types/`	TypeScript declarations.
`dist/styles/charts.css`	Chart styles and colour variables. Load it once, with either build.

Script tag from a CDN

Every npm release is also on jsDelivr. Pin the exact version, so a new release never changes your page without notice:

HTML

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@kymoscope/sdk@0.1.0/dist/styles/charts.css" />
<script src="https://cdn.jsdelivr.net/npm/@kymoscope/sdk@0.1.0/dist/kymoscope-embed.js"></script>

The script loads its workers, DuckDB-WASM and the other files in assets/ from the same CDN folder; nothing else needs serving.

Script tag, self-hosted

Copy dist/ from the npm package into your static files, keeping its layout (see Serving the workers):

Shell

npm install @kymoscope/sdk
cp -r node_modules/@kymoscope/sdk/dist public/vendor/kymoscope

Then load /vendor/kymoscope/kymoscope-embed.js and /vendor/kymoscope/styles/charts.css. Copy the folder again after each upgrade: worker file names change with every release.

Requirements

Evergreen browsers with WebCrypto, Web Workers and ES2023. WebGL2 is used when available; charts fall back to Canvas 2D.
License verification uses WebCrypto Ed25519 (Chrome 113+, Firefox 129+, Safari 17+). Older browsers and pages served over plain http:// cannot verify keys and show the attribution badge.
ESM hosts: React 19 (the charts render with it, even if your own UI does not use React).

ESM or script tag

Choose	When
ESM	You bundle your front end. You get types, tree-shaking and, in React apps, the bindings from @kymoscope/sdk/react.
Standalone script	Anything else: Vue, Angular, Svelte, server-rendered pages, or no build step at all. The script carries its own React, so your page needs none.

Both builds load their workers relative to their own file. With the script tag, keep assets/ in the same folder as kymoscope-embed.js. Bundlers (Vite, webpack 5) pick up the ESM build’s new URL(…, import.meta.url) worker references automatically.

Folder layout

public/
  vendor/kymoscope/
    kymoscope-embed.js
    assets/
      offscreenLineWorker-*.js
      parseDataset.worker-*.js
      duckdb-*.js, duckdb-*.wasm.gz   (files too large for memory)
    styles/
      charts.css