neolite/effector-playbook
Overview
This skill documents concise rules and patterns for writing reliable Effector code and diagnosing Effector issues. It bundles practical guidance for events, stores, effects, sample flow control, models/factories, SSR/scopes, tests, debugging, and linting. Use it to implement, review, or migrate Effector logic with predictable, testable outcomes.
How this skill works
The skill groups rules into focused categories (core correctness, flow control, effects, modeling, React integration, Patronum, scopes/SSR, testing, debugging, linting). Each rule includes a short rationale and actionable guidance (what to change and why). It points to concrete tactics like using sample instead of guard/forward, forking scopes for SSR/tests, and using attach to inject dependencies into effects.
When to use it
- Implementing or refactoring Effector models and flows
- Debugging race conditions, stale reads, or failing async effects
- Writing SSR-safe logic, scope-isolated tests, or migrating from component state
- Enforcing architecture and anti-patterns during code reviews
- Designing new features where global stores, effects, or factories are involved
Best practices
- Prefer sample for wiring that must read current store values at clock time
- Keep store transformations pure: avoid side effects inside .map or derived stores
- Use attach to compose effects and inject store-derived dependencies explicitly
- Isolate instances with factories and fork/allSettled for SSR and deterministic tests
- Avoid imperative getState() and .watch for application logic—use events/effects instead
- Enforce naming conventions (prefix stores with $) and lint rules to prevent common mistakes
Example use cases
- Refactor component-local state into a normalized Effector model with factory instances
- Diagnose a race condition by replacing guard/forward wiring with sample and explicit payloads
- Create SSR handlers that fork a scope, run allSettled for initial loads, and serialize SIDs
- Write deterministic unit tests by mocking effects via fork handlers and asserting store snapshots
- Improve observability using inspect or Patronum debug operators without changing runtime behavior
FAQ
Use sample when you need the target to see store values at the exact moment of the clock event; it avoids hidden timing issues that guard/forward wiring can introduce.
How do I test effects without hitting real APIs?
Fork the domain and provide handlers to mock effects, or use attach to replace dependencies so tests exercise flow logic deterministically.
