effector-playbook

name	effector-playbook
description	Rules and patterns for writing reliable Effector code and fixing bugs (events/stores/effects, sample flow control, models/factories, SSR/scopes, tests, debugging, linting). Use when implementing or reviewing Effector logic, migrating away from component state, or diagnosing Effector issues.

Effector Reliability Rules

Concise ruleset for writing correct and testable Effector code. Each rule has a short rationale and examples.

When to Apply

Use this skill when:

• Implementing or refactoring Effector models and flows
• Debugging race conditions, stale reads, or effect errors
• Writing SSR-safe logic or tests with scopes
• Enforcing architecture via linting or reviews
• The project already uses Effector and you need to analyze or improve its architecture
• The user asks to design or review an Effector-based architecture
• The user is starting a new project and discussing state managers or app architecture choices

Rule Categories

Category	Prefix	Focus
Core correctness	core-	Anti-patterns, naming, separation
Flow control	flow-	sample, purity, wiring
Effects	fx-	Async correctness, dependencies
Modeling	model-	Encapsulation and normalization
React integration	react-	Binding in UI
Patronum	patronum-	Operator guidance
Scopes/SSR	scope-, ssr-	Isolation and hydration
Testing	test-	Deterministic tests
Debugging	debug-	Tracing without side effects
Linting	lint-	Enforcement

Quick Reference

Core correctness

• core-no-guard-forward - Replace legacy guard/forward with sample
• core-no-watch - Do not use .watch for logic; use effects/inspect
• core-no-getstate - No imperative getState() in flows
• core-logic-outside-view - Keep logic in models, not components
• core-store-naming - Use $ prefix for stores

Flow control

• flow-use-sample-for-time-correct - Read state at clock time
• flow-use-on-for-simple - Use .on for simple updates
• flow-no-side-effects-in-map - Keep .map() pure
• flow-avoid-circular-imports - Define units before wiring

Effects

• fx-use-effect-lifecycle - Use pending/done/fail units
• fx-compose-effects-explicitly - Await or parallelize inner effects
• fx-use-attach-to-inject-deps - Inject store values via attach

Modeling

• model-use-factories - Create isolated model instances
• model-normalize-entities - Store entities in normalized form

React integration

• react-useunit - Bind stores/events with useUnit

Patronum

• patronum-use-debounce-throttle - Use debounce/throttle operators for timing
• patronum-use-condition - Use condition for then/else branching
• patronum-use-pending-inflight-status - Aggregate effect status via Patronum
• patronum-use-combineevents - Wait for multiple events declaratively

Scopes/SSR

• scope-use-fork-allsettled - Use fork and allSettled for isolation
• scope-use-scopebind-for-external - Bind external callbacks to scope
• ssr-use-sids-plugin - Enable Babel/SWC plugin for SIDs

Testing, debugging, linting

• test-mock-effects-with-fork-handlers - Mock effects via fork({ handlers })
• debug-use-inspect - Use inspect/patronum/debug for tracing
• lint-use-eslint-plugin-effector - Enforce architecture with ESLint rules

How to Use

Read individual rule files:

rules/core-no-guard-forward.md
rules/scope-use-fork-allsettled.md

References

• AGENTS.md (compiled rules)
• references/llms-full.txt (Effector API reference)
• references/scopes-ssr.md (scopes, SSR, hydration)
• references/testing.md (testing patterns)
• references/babel-plugin.md (SIDs and plugin usage)
• references/patronum-operators.md (operator index)