Installation

Inside this workspace

insomni lives in a pnpm workspace driven by the Vite+ toolchain (vp). The packages are wired together with the workspace:* protocol, so a sibling package always resolves to the local source. Add what you need to a package’s dependencies:

{
  "dependencies": {
    "insomni": "workspace:*",
    "insomni-plot": "workspace:*",
  },
}

Then install from the repo root with the Vite+ CLI:

vp install

All scripts go through vp (it wraps Vite, Rolldown, Vitest, tsdown, Oxlint, and Oxfmt) — do not invoke pnpm / npm / vitest / oxlint directly.

Requirements

insomni renders through WebGPU, so it needs:

• A WebGPU-capable environment — a recent Chromium-based browser, or any runtime exposing navigator.gpu.
• A GPUDevice acquired at startup (see below).
• An HTMLCanvasElement to present to.

Acquiring a GPUDevice — initGPU()

insomni ships an initGPU() helper that handles adapter/device acquisition with retry. It returns a GPUHandle ({ adapter, device, root, features, destroy() }), which is what the renderer factory consumes:

import { initGPU, createRenderer } from "insomni";

const gpu = await initGPU();
const renderer = createRenderer(gpu, canvas);

initGPU(options?) throws if navigator.gpu is missing or no adapter is found after the retry budget. Every option is optional:

Option	Type	Default	Notes
powerPreference	"low-power" | "high-performance"	adapter default	Forwarded to requestAdapter (a standard GPURequestAdapterOptions field).
forceFallbackAdapter	boolean	false	Forwarded to requestAdapter.
maxAdapterAttempts	number	3	How many times to retry requestAdapter before throwing.
retryDelayMs	number	100	Delay between adapter attempts.
requiredFeatures	readonly GPUFeatureName[]	[]	Enabled only if the adapter exposes them — unsupported entries are silently dropped. Check handle.features.has(...) at runtime.
requiredLimits	Record<string, number | "adapter-max">	—	Each entry is clamped to the adapter’s max; unsupported keys are dropped. Pass "adapter-max" to opt into the adapter ceiling.

The returned GPUHandle:

Field	Type	Notes
adapter	GPUAdapter	The granted adapter.
device	GPUDevice	The logical device.
root	TgpuRoot	The cached TypeGPU root used for typed buffers/pipelines.
features	ReadonlySet<GPUFeatureName>	The subset of requiredFeatures the adapter granted.
destroy()	() => void	Destroys the device; idempotent.

getLastGPUHandle() returns the most recently created handle (or null) — a convenience for tooling that needs the device without threading it through.

Note

You can hand a GPUHandle straight to the renderer factory. Internally the renderer needs the device and the TypeGPU root, both of which the handle carries.

Subpath exports

insomni ships several entry points beyond the main barrel. Keep these in mind when importing — the bulk of the API is on the bare insomni import; the subpaths carve out heavier or specialized surfaces:

Import	Purpose
insomni	The main barrel — renderer, layers, groups, primitives, math, color, interactions, system-font text.
insomni/internal	Renderer plumbing for first-party sibling packages.
insomni/text-ttf	TTF/MSDF text — pulls in insomni-msdf-text (opentype.js + the MSDF generator). The core bundle stays free of font binaries.
insomni/particles	GPU particle / layout system.
insomni/reactivity	Reactive primitives.
insomni/spatial	Spatial-index helpers.
insomni/viewport	Viewport / camera helpers.

The default text path uses system fonts via Canvas (zero font bytes); only reach for insomni/text-ttf when you need true MSDF, kerning, or cross-platform glyph consistency.

Next

• Quick start — render your first frame.
• Core concepts — the mental model.