Getting Started with Causl

Causl is a state-management engine for the tangled middle of an application — the part where one input feeds three derivations, one of those derivations is read by a fetch handler, the fetch handler writes back two more inputs, and any of them can change in the same user gesture. It is built around a single idea: every mutation is a transaction, and every read is a pure function of the graph at one point in time. Glitch-freedom is not a scheduling trick — it is a theorem about the public API surface.

If you have used Redux, Jotai, MobX, or a spreadsheet engine, a lot of causl will feel familiar. The differences show up at the boundaries: transactions are the only mutation entry point; derivations are recomputed in topological order in one pass per commit; subscribers fire exactly once per commit that actually changed their projection; and the engine ships a static checker and a bounded model checker that catch the race conditions the type system cannot express. The five pages in this section walk you from "what is this" to "your first running app" in the order most readers want them.

If you are impatient, skip to the 5-Minute Quick Start — it installs the engine, writes a graph in fifteen lines, and runs it. If you are evaluating, start with Why Causl, which is honest about where causl is the wrong tool. If you are building something real, work through the pages top to bottom; they introduce one concept at a time, and each one builds on the previous.

The whole section assumes TypeScript, Node 20+, and a recent package manager (npm 10+, pnpm 9+, or yarn 4+). The engine itself has zero runtime dependencies; the React bindings depend only on react. Every code example on every page is typechecked against the current published API surface and lifted from the same fixture set the integration tests run, so copy-paste should compile.

A note on the eight commitments. Throughout the documentation you will see references to causl's "eight commitments" — atomic transactions, transactions-as-only-mutation, glitch-free reads, explicit observability, bounded retention, typed dispatch, exported IR, and reproducible builds. Each one shows up as a concrete API constraint, and the home page spells them out in plain English.

In this section

• Introduction

  What problem causl solves, the shape of its public API, and the mental model — graph, inputs, derivations, commits, subscribers — that everything else builds on. Start here if the name is new to you.

  ~600 words · 4 min read
• Why Causl

  Motivation. Where causl is the right tool (tangled dependency graphs, audit trails, glitch-free reads across many derivations) and where it is not (event streams, ad-hoc local component state, very small UIs). Comparisons against Redux, Jotai, MobX, and signal libraries.

  ~900 words · 6 min read
• Installation

  Installing @causl/core and the optional packages — @causl/react, @causl/sync, @causl/persistence, @causl/checker. TypeScript configuration, ESM notes, and the version compatibility matrix.

  ~500 words · 3 min read
• 5-Minute Quick Start

  The impatient developer's path. npm install, fifteen lines of code, run it, see the output. If you only read one page in this section, read this one.

  ~700 words · 5 min read
• Your First App

  A longer worked example with React: a small dashboard with two inputs, three derivations, and a subscriber. Builds step-by-step, explains each new concept as it appears, and ends with a working app you can extend.

  ~1500 words · 12 min read
• Core Concepts

  The vocabulary you need before reading the rest of the documentation: Behavior, GraphTime, Commit, derivation, intent, explanation, retention cap. One short section per term, with a working code example for each.

  ~1200 words · 9 min read

Where to go next

Once you have walked through this section, the Tutorial picks up with a complete application from scratch, and the Usage Guide covers patterns you will reach for in production: structured commit intents, statechart composition with @causl/sync, persistence adapters, devtools, and the static checker. The API reference is generated from the source and is the right page to keep open in another tab while you work.