writing-kea-logics

Writing kea logics

PostHog uses kea as the state container for the frontend. Almost all non-trivial business logic lives in a *Logic.ts / *Logic.tsx file, not in React. We may be on a kea pre-release ahead of the version the keajs.org docs cover — when in doubt, check pnpm-workspace.yaml for the pinned version.

This skill captures the PostHog-specific conventions on top of the upstream kea docs. When in doubt about a builder's signature, go upstream. When in doubt about whether to use it, read here.

Use this skill when

• Creating a new *Logic.ts / *Logic.tsx file
• Adding builders to an existing logic (actions, reducers, selectors, listeners, loaders, forms)
• Choosing between reducer vs selector vs cache vs loader for a piece of state
• Wiring a React component to a logic
• Reviewing a PR that introduces or modifies a kea logic
• Reviewing code that uses React hooks where a logic would be more idiomatic

Companion skills (do not duplicate)

• using-kea-disposables — setInterval, addEventListener, and any other resource that needs cleanup.

If your work overlaps it, read the companion skill first.

Core principles

1. Business logic lives in a logic, not in a component. CLAUDE.md is explicit: "If there is a kea logic file, write all business logic there, avoid React hooks at all costs." Hooks are for view concerns.

2. One concept, one source of truth. Pick exactly one of: action-driven reducer, derived selector, async loader. Don't mirror the same value into multiple places.

3. Prefer listeners over kea-subscriptions. Subscriptions install a redux subscription that re-runs on every dispatch and is measurably slower. Listen to the action that changed the value instead. See references/reacting-to-changes.md.

4. Generated types are the contract. Every logic has an inline generated MakeLogicType block above its kea() call. Import a logic type from the logic source file, never from a separate *LogicType.ts file.