Best Practices

This is the causl style guide — the rules and patterns we recommend you follow when building real applications on the engine. They are drawn from the same place the checker and the SPEC §16 race catalogue come from: lessons that hurt to learn the first time, now written down so you don't have to learn them again.

Unlike the specification, which is normative and exhaustive, this guide is opinionated. Most of the time the engine will happily let you do the wrong thing. The static checker catches a meaningful slice of the worst mistakes, but it cannot catch cluttered — only incorrect. The rest is on you.

Each rule is tagged with a priority so you can scan and triage:

Essential Rules we believe every causl application should follow. Breaking these will cause bugs, surprise re-renders, or wedged transactions. The checker enforces several of them. Strongly recommended Rules that consistently improve code clarity and reviewability. Skipping them is survivable but predictably regretted. Recommended Rules that lean on team taste. Adopt them as defaults; deviate when the situation genuinely calls for it.

In this guide

Code Organization

How to lay out a causl project on disk, how to split your graph into per-feature modules, where the seam between UI and graph belongs, what to name your inputs and derivations, and how to avoid growing a single god-graph that everyone is afraid to touch.

More pages, coming soon

Additional best-practices pages cover transaction patterns, structuring derivations, React integration, async resources and conflicts (@causl/sync), testing strategies, persistence, and migration from Jotai / MobX / Redux. They will land alongside the rest of the redux.js.org-style docs.

Why a style guide at all? The engine guarantees atomicity, glitch-freedom, and topological recompute by construction (SPEC §5.1, phases A–H). It does not guarantee that your graph is readable, your feature boundaries are honest, or that your team can onboard a new contributor in a week. Those are conventions — and conventions only work when they are written down.