Installation

Causl is published as a family of small packages under the @causl/* scope. You install only the pieces your application uses: the core engine alone is enough for a Node script or a non-React UI, and every other package — React bindings, async resource lifecycles, persistence, static checking, statecharts — is additive. This page covers install commands for all three major package managers, peer dependency requirements, TypeScript setup, and the per-package bundle budget. The default engine everywhere here is the pure-TypeScript @causl/core; the wasm engine and causl-client are an Enterprise feature.

Supported environments

Causl ships ESM-only modules targeting modern runtimes. The minimum supported versions are:

Node.js 22.0+ for server-side, SSR, and tooling use.
Any browser with ES2022 support — Chromium 102+, Firefox 102+, Safari 16+.
TypeScript 5.4+. The packages ship hand-written .d.ts declarations alongside the JavaScript.
React 18.3+ or React 19 for @causl/react (peer dependency).

Older Node and browser versions are not tested. There is no CommonJS build; if you need to require @causl/core from a CJS module, use the dynamic import() form or a small wrapper.

Engine

Everything on this page installs and runs on the default pure-TypeScript engine in @causl/core — it is the unconditional floor, optimized for development, debugging, and bundle size, and it is all most applications ever need. No wasm toolchain, no extra artefacts.

@causl/core

@causl/core is the semantic kernel — the dependency graph, the transactional commit, the deterministic recompute pipeline. Every other package depends on it. Start here; install nothing else until you need it.

# npm
npm install @causl/core

# pnpm
pnpm add @causl/core

# yarn
yarn add @causl/core

That gives you the canonical primitives:

import { createCausl } from '@causl/core';

const graph = createCausl();
const count = graph.input('count', 0);
const doubled = graph.derived('doubled', g => g(count) * 2);

graph.commit('set-count', tx => {
  tx.set(count, 5);
});

console.log(graph.read(doubled));  // 10

@causl/core has zero runtime dependencies. The only declared peer dependency is fast-check, and it is marked optional — it is pulled in only by the @causl/core/testing subpath that exposes property-test helpers. You will never need to install it for production use.

@causl/react

@causl/react wires a causl graph into React's render lifecycle through useSyncExternalStore. The headline hook is useCauslNode, with useCauslShallow, useCauslFamily, useCauslSuspense, and a <Hydrate> SSR boundary alongside it.

# npm
npm install @causl/core @causl/react react

# pnpm
pnpm add @causl/core @causl/react react

# yarn
yarn add @causl/core @causl/react react

React is a peer dependency at ^18.3.0 || ^19.0.0; install it alongside if it is not already in your dependency graph. @causl/react also pulls @causl/sync transitively so you can use useCauslSuspense against async resources without installing the sync package by hand.

import { createCausl } from '@causl/core';
import { useCauslNode } from '@causl/react';

const graph = createCausl();
const count = graph.input('count', 0);
const doubled = graph.derived('doubled', g => g(count) * 2);

export function Counter() {
  const value = useCauslNode(graph, doubled);
  return <output>{value}</output>;
}

@causl/sync

@causl/sync is the async resource lifecycle: fetchers, mutations, suspendable reads, and the race-row guarantees (S-1 stale-write, S-2 stale-read) that keep concurrent network calls from corrupting derived state. Install it when you have data that lives outside the graph — HTTP, IndexedDB, WebSocket, etc.

# npm
npm install @causl/core @causl/sync

# pnpm
pnpm add @causl/core @causl/sync

# yarn
yarn add @causl/core @causl/sync

@causl/sync declares @causl/core as a runtime dependency, so package managers will resolve a matching version automatically. If you also use @causl/react, it already brings @causl/sync in transitively.

@causl/persistence

@causl/persistence ships the storage adapters (localStorage, sessionStorage, IndexedDB, custom StorageAdapter) that pair with graph.dehydrate() / graph.hydrate() in core. The protocol ships in core; the concrete adapters live here so cores stays small.

# npm
npm install @causl/core @causl/persistence

# pnpm
pnpm add @causl/core @causl/persistence

# yarn
yarn add @causl/core @causl/persistence

@causl/checker

@causl/checker is the static analyser: a CLI plus library entry point that walks your causl graph definitions and surfaces race rows (R-1 through R-8), cycle hazards, missing capability scopes, and unreachable derivations. It is a build-time tool — install it as a dev dependency.

# npm
npm install --save-dev @causl/checker

# pnpm
pnpm add -D @causl/checker

# yarn
yarn add --dev @causl/checker

The checker ships precompiled native binaries (@causl/checker-darwin-arm64, -linux-x64, -win32-x64, etc.) selected by the optional-deps mechanism — you do not install platform binaries directly. Run it with npx causl-check or wire it into a lint:graph npm script.

@causl/formula

@causl/formula brings spreadsheet formula patterns on top of the core — formulas, ranges, and cycles expressed as causl derivations. Install it when your application has spreadsheet-like cells with formula references or range dependencies that you want expressed declaratively rather than re-encoded as ad-hoc derivations.

# npm
npm install @causl/core @causl/formula

# pnpm
pnpm add @causl/core @causl/formula

# yarn
yarn add @causl/core @causl/formula

@causl/devtools

@causl/devtools is the optional Historian and Editor surface — time-travel, live derived inspection, batched replaceMany edits during development. It pairs with the browser extension and is a dev-only dependency.

# npm
npm install --save-dev @causl/devtools

# pnpm
pnpm add -D @causl/devtools

# yarn
yarn add --dev @causl/devtools

The wiring itself is in @causl/core behind a one-line opt-in: createCausl({ devtools: true }) dead-code-eliminates in production builds. You only install @causl/devtools if you want the standalone REPL utilities outside the browser extension.

TypeScript setup

All @causl/* packages ship .d.ts files. The minimum tsconfig.json for an application consuming causl looks like this:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "jsx": "react-jsx",
    "lib": ["ES2022", "DOM", "DOM.Iterable"]
  }
}

Module resolution. Causl is ESM-only and uses package exports subpaths (@causl/core/testing, and the @causl/core/wasm Enterprise entry, etc.). You need "moduleResolution": "Bundler" (or "NodeNext") so TypeScript reads the exports map. Older "moduleResolution": "Node" will silently miss the subpath types.

Strict mode. Causl's branded types (NodeId<T>, GraphTime) only catch the errors they are designed to catch under strict: true. A non-strict tsconfig erases the brand and a node from graph A passed to graph B will fail at runtime instead of at tsc. The team treats strict: true as a precondition; do not try to use causl without it.

JSX. If you use @causl/react, set "jsx": "react-jsx" (or "react-jsxdev" in dev). The classic "react" setting still works but is no longer recommended.

Bundle sizes

Causl publishes a size-limit CI gate on every published surface so the bundle budget is enforceable, not aspirational. The ceilings, per SPEC §14.2 and §17.6, are:

Bundle	Ceiling (Brotli)	Notes
`@causl/core` (full import)	20 KB	Working target ~18 KB. Includes source-mapped error chains, devtools opt-in wiring (DCE'd in production), runtime IR validation in `hydrate()`, branded `NodeId<T>` / `GraphTime`, and the `dehydrate()` / `hydrate()` SSR pair.
`@causl/core` (`createCausl`-only)	15 KB	The minimum import surface. Adopters who only register inputs and read derivations sit near this floor.
`@causl/react`	8 KB	Absorbs the four §8.2 extension hooks plus the dev-mode "Update did not commit" warnings (DCE'd in production).
`@causl/devtools-bridge` (absent-extension path)	5 KB	The bridge logic that the `devtools: true` opt-in in core now imports. The present-extension path is larger.
wasm engine artefacts Enterprise	see Enterprise docs	The `@causl/core/wasm` entry stub, the lazily-fetched per-host wasm tiers, and their Brotli ceilings are an Enterprise concern. Adopters on the default pure-TS engine pay zero bytes for any of it.

The CI gate size — bundle-size gate fails any PR that crosses these ceilings. The team holds the line on the budget: every kilobyte over 4.5 KB shipped to @causl/core required written team consensus per SPEC §14.2.

Next steps

With the packages installed, the natural next step is the Tutorial — a walkthrough that builds a small graph, wires it into a React component, and adds an async fetch with @causl/sync. From there:

Usage Guide — task-oriented recipes for commits, subscriptions, persistence, SSR, and time travel.
API Reference — the typedoc-generated reference for every @causl/* package.
Best Practices — race rows, capability scoping, and the H1 reference-identity hazard adopters trip on first.
FAQ — when causl is the right tool, and where it is not.