# npm
npm install effector
 
# pnpm
pnpm add effector
 
# yarn
yarn add effector

# React 绑定
npm install effector effector-react
 
# Vue 绑定
npm install effector effector-vue
 
# Solid 绑定
npm install effector effector-solid
 
# Next.js 集成
npm install effector @effector/next

// babel.config.js — 配置 Babel 插件（SSR 必需）
module.exports = {
  plugins: [
    'effector/babel-plugin', // 自动生成 store sid，确保 SSR 状态隔离
  ],
}

// app/model.ts — 业务逻辑层（与框架无关）
import { createStore, createEvent, createEffect, sample } from 'effector'
 
// 1. 定义 Event — "发生了什么"
export const todoAdded = createEvent<string>()
export const todoToggled = createEvent<number>()
export const todoFetchRequested = createEvent()
 
// 2. 定义 Effect — 处理副作用
export const fetchTodosFx = createEffect(async () => {
  const response = await fetch('https://jsonplaceholder.typicode.com/todos?_limit=10')
  if (!response.ok) throw new Error('网络请求失败')
  return response.json() as Promise<Array<{ id: number; title: string; completed: boolean }>>
})
 
// 3. 定义 Store — 存储状态
export const $todos = createStore<Array<{ id: number; title: string; completed: boolean }>>([])
  .on(todoAdded, (todos, title) => [
    ...todos,
    { id: Date.now(), title, completed: false },
  ])
  .on(todoToggled, (todos, id) =>
    todos.map(todo =>
      todo.id === id ? { ...todo, completed: !todo.completed } : todo
    )
  )
  .on(fetchTodosFx.done, (_, { result }) => result)
 
export const $isLoading = fetchTodosFx.pending
 
// 4. 使用 sample 连接逻辑
sample({
  clock: todoFetchRequested,
  target: fetchTodosFx,
})
 
// 派生 Store — 自动随源 Store 更新
export const $completedCount = $todos.map(todos =>
  todos.filter(t => t.completed).length
)

// main.tsx — 应用入口
import React from 'react'
import ReactDOM from 'react-dom/client'
import { Provider } from 'effector-react'
import { todoFetchRequested } from './app/model'
import { TodoList } from './components/TodoList'
 
// SSR 场景下使用 fork() 创建隔离 Scope
// const scope = fork()
 
ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <TodoList />
  </React.StrictMode>
)
 
// 触发初始数据加载
todoFetchRequested()

// counter.ts — 完整可用的计数器示例
import { createStore, createEvent, combine } from 'effector'
 
// Event：用户意图
const incremented = createEvent()
const decremented = createEvent()
const reset = createEvent()
 
// Store：应用状态
const $count = createStore(0)
  .on(incremented, (state) => state + 1)
  .on(decremented, (state) => state - 1)
  .reset(reset)
 
// 派生 Store
const $doubled = $count.map((n) => n * 2)
const $isPositive = $count.map((n) => n > 0)
 
// 组合 Store
const $summary = combine(
  { count: $count, doubled: $doubled, isPositive: $isPositive },
)
 
// 订阅变化（适用于任何 JS 环境）
$summary.watch((state) => {
  console.log('当前状态:', state)
  // { count: 0, doubled: 0, isPositive: false }
})
 
// 触发事件
incremented() // count → 1
incremented() // count → 2
decremented() // count → 1
reset()       // count → 0

// Counter.tsx — React 组件绑定
import { useUnit } from 'effector-react'
import { $count, $doubled, incremented, decremented, reset } from './counter'
 
export function Counter() {
  // useUnit 同时绑定 store 和 event
  const count = useUnit($count)
  const doubled = useUnit($doubled)
  const [onIncrement, onDecrement, onReset] = useUnit([
    incremented,
    decremented,
    reset,
  ])
 
  return (
    <div>
      <h2>计数器: {count}</h2>
      <p>双倍值: {doubled}</p>
      <button onClick={onDecrement}>减少</button>
      <button onClick={onIncrement}>增加</button>
      <button onClick={onReset}>重置</button>
    </div>
  )
}

import { createEvent } from 'effector'
 
// 创建无载荷事件
const formSubmitted = createEvent()
 
// 创建带载荷事件（TypeScript 自动推导类型）
const userLoggedIn = createEvent<{ name: string; role: 'admin' | 'user' }>()
 
// 监听事件
formSubmitted.watch(() => console.log('表单已提交'))
userLoggedIn.watch((user) => console.log(`${user.name} 已登录`))
 
// 触发事件
formSubmitted()
userLoggedIn({ name: 'Alice', role: 'admin' })
 
// Event 变换
const userNameExtracted = userLoggedIn.map((user) => user.name)
// userNameExtracted 是一个新 Event，载荷为 string 类型
 
// Event 前置处理
const formSubmittedWithTimestamp = formSubmitted.prepend(
  (data: { title: string }) => ({ ...data, timestamp: Date.now() })
)

import { createStore, createEvent, combine } from 'effector'
 
const nameChanged = createEvent<string>()
const ageChanged = createEvent<number>()
 
// 创建 Store，必须提供默认值（不能为 undefined）
const $name = createStore('匿名')
  .on(nameChanged, (_, newName) => newName)
 
const $age = createStore(0)
  .on(ageChanged, (_, newAge) => newAge)
 
// 派生 Store — 自动随源 Store 变化而重新计算
const $greeting = $name.map((name) => `你好, ${name}!`)
 
// 组合多个 Store
const $profile = combine({
  name: $name,
  age: $age,
  greeting: $greeting,
})
 
// 读取 Store 当前值（在非响应式上下文中）
console.log($name.getState()) // '匿名'
 
// 订阅 Store 变化
$profile.watch((profile) => {
  console.log('Profile updated:', profile)
})
 
// 触发更新
nameChanged('Alice') // $name → 'Alice', $greeting → '你好, Alice!'
ageChanged(25)       // $age → 25, $profile 自动更新

import { createEffect, createStore, sample } from 'effector'
 
// 创建异步 Effect
const fetchUserFx = createEffect(async (userId: string) => {
  const response = await fetch(`/api/users/${userId}`)
  if (!response.ok) throw new Error('用户不存在')
  return response.json() as Promise<{ id: string; name: string; email: string }>
})
 
// Effect 内置的状态 Store 和 Event
const $isLoading = fetchUserFx.pending        // Store<boolean> — 是否正在执行
const $error = createStore<string | null>(null)
  .on(fetchUserFx.fail, (_, { error }) => error.message)
  .on(fetchUserFx.done, () => null)
 
fetchUserFx.done.watch(({ params, result }) => {
  console.log(`用户 ${params} 获取成功:`, result)
})
 
fetchUserFx.fail.watch(({ params, error }) => {
  console.error(`用户 ${params} 获取失败:`, error)
})
 
fetchUserFx.finally.watch(({ status }) => {
  console.log(`执行结束, 状态: ${status}`) // 'done' | 'fail'
})
 
// Effect 可设置并发限制
const limitedFx = createEffect({
  handler: async (id: string) => { /* ... */ },
  limit: 3, // 最多同时执行 3 个
})

import { createDomain } from 'effector'
 
// 创建域
const authDomain = createDomain()
 
// 在域内创建单元
const $user = authDomain.createStore<{ name: string } | null>(null)
const login = authDomain.createEvent<{ email: string; password: string }>()
const logout = authDomain.createEvent()
const loginFx = authDomain.createEffect(
  async (credentials: { email: string; password: string }) => {
    const res = await fetch('/api/auth/login', {
      method: 'POST',
      body: JSON.stringify(credentials),
    })
    return res.json()
  }
)
 
// 域内逻辑连接
$user.on(loginFx.done, (_, { result }) => result)
  .on(logout, () => null)
 
// 域可以嵌套
const appDomain = createDomain()
const uiDomain = appDomain.createDomain()
 
// 域级别统一监听
authDomain.onCreateStore((store) => {
  // 对所有域内 Store 应用统一的日志/重置逻辑
  store.watch((value) => console.log('[auth] store updated:', value))
})

import { fork, serialize, allSettled, scopeBind } from 'effector'
 
// 服务端：为每个请求创建独立 Scope
async function handleRequest(req: Request) {
  const scope = fork({
    values: {
      // 可设置 Store 的初始值（如从 cookie 读取用户信息）
    },
    handlers: {
      // 可覆盖 Effect 的处理器（用于测试或 mock）
    },
  })
 
  // 在 Scope 中执行所有操作
  await allSettled(fetchUserFx, { scope, params: 'user-123' })
 
  // 序列化 Scope 状态，发送到客户端
  const state = serialize(scope)
 
  return {
    html: renderApp(),
    initialState: state, // 注入到 HTML 中供客户端 hydrate
  }
}
 
// 客户端：hydrate 服务端状态
import { hydrate } from 'effector'
hydrate({
  values: window.__INITIAL_STATE__,
})

import { sample, createStore, createEvent, createEffect } from 'effector'
 
const $cart = createStore<Array<{ id: number; qty: number }>>([])
const $userId = createStore<string>('')
const checkoutClicked = createEvent()
const submitOrderFx = createEffect(
  async (data: { items: Array<{ id: number; qty: number }>; userId: string }) => {
    // 提交订单...
  }
)
 
// 从 clock 触发，从 source 读取数据，组合后发送给 target
sample({
  clock: checkoutClicked,           // 触发信号
  source: { cart: $cart, userId: $userId }, // 读取多个 Store
  fn: ({ cart, userId }) => ({      // 纯函数变换
    items: cart,
    userId,
  }),
  target: submitOrderFx,            // 目标 Effect
})
 
// 条件触发（guard 模式）
const $isAdmin = createStore(true)
 
sample({
  clock: checkoutClicked,
  source: $cart,
  filter: $isAdmin,  // 仅当 $isAdmin 为 true 时才触发
  target: submitOrderFx,
})

import { createStore, createEvent, sample, createEffect } from 'effector'
 
// Event 载荷类型自动推导
const searchQueryChanged = createEvent<string>()
 
// Store 类型自动推导
const $query = createStore('')
  .on(searchQueryChanged, (_, q) => q) // $query: Store<string>
 
// Effect 的 params 和 result 类型自动推导
const searchFx = createEffect(async (query: string) => {
  const res = await fetch(`/api/search?q=${query}`)
  return res.json() as Promise<Array<{ id: number; title: string }>>
})
// searchFx.done 类型为 { params: string; result: Array<...> }
// searchFx.fail 类型为 { params: string; error: Error }
 
// sample 的 fn 返回类型自动校验与推导
sample({
  clock: searchQueryChanged,
  target: searchFx, // 类型校验：clock 的载荷必须与 Effect 的 params 兼容
})

// 框架无关的业务逻辑
import { createStore, createEvent } from 'effector'
 
export const $count = createStore(0)
export const increment = createEvent()
$count.on(increment, (n) => n + 1)
 
// React 中使用
import { useUnit } from 'effector-react'
function ReactCounter() {
  const [count, onIncrement] = useUnit([$count, increment])
  return <button onClick={onIncrement}>{count}</button>
}
 
// Vue 中使用
import { useUnit } from 'effector-vue'
// Vue 组件中同样可以使用 $count 和 increment

const $firstName = createStore('John')
const $lastName = createStore('Doe')
 
// 自动追踪 $firstName 和 $lastName 的变化
const $fullName = combine($firstName, $lastName, (first, last) => `${first} ${last}`)
 
// $firstName 或 $lastName 变化时，$fullName 自动更新

import { fork, allSettled } from 'effector'
import { $user, loginFx, loginButtonClicked } from './model'
 
test('用户登录成功后更新用户信息', async () => {
  const scope = fork({
    handlers: {
      // Mock Effect，不发起真实请求
      [loginFx]: async (credentials) => ({
        id: '1',
        name: credentials.email.split('@')[0],
      }),
    },
  })
 
  await allSettled(loginButtonClicked, {
    scope,
    params: { email: '[email protected]', password: '123' },
  })
 
  expect(scope.getState($user)).toEqual({ id: '1', name: 'alice' })
})

import { createStore, createEvent, createEffect, sample, combine } from 'effector'
 
// Event 类型推导
const userCreated = createEvent<{ id: string; name: string }>()
 
// Store 类型推导
const $users = createStore<Array<{ id: string; name: string }>>([])
  .on(userCreated, (users, user) => [...users, user])
 
// Effect 类型推导 — params 和 result 自动推导
const fetchUserFx = createEffect(
  async (params: { id: string; includeDetails?: boolean }) => {
    const res = await fetch(`/api/users/${params.id}`)
    return res.json() as Promise<{ id: string; name: string; email: string }>
  }
)
// fetchUserFx.done: Event<{ params: { id: string; includeDetails?: boolean }; result: { id: string; name: string; email: string } }>
// fetchUserFx.fail: Event<{ params: ...; error: Error }>
 
// sample 类型推导 — fn 的返回类型必须与 target 的输入类型匹配
sample({
  clock: userCreated,
  fn: (user) => user.id,           // fn 返回 string
  target: fetchUserFx,             // ❌ 类型错误！fetchUserFx 需要 { id: string; includeDetails?: boolean }
})
 
// 正确写法
sample({
  clock: userCreated,
  fn: (user) => ({ id: user.id }), // fn 返回 { id: string }，匹配 Effect 的 params
  target: fetchUserFx,
})
 
// combine 类型推导
const $userCount = $users.map((users) => users.length) // Store<number>
const $summary = combine({ users: $users, count: $userCount })
// $summary: Store<{ users: Array<...>; count: number }>

pnpm add -D eslint-plugin-effector

{
  "plugins": ["effector"],
  "rules": {
    "effector/no-watch": "warn",
    "effector/no-getState": "warn",
    "effector/enforce-effect-handler-types": "error"
  }
}

// model.test.ts — Effector 单元测试
import { fork, allSettled } from 'effector'
import {
  $todos,
  $isLoading,
  todoAdded,
  todoToggled,
  fetchTodosFx,
  todoFetchRequested,
} from './model'
 
describe('Todo Model', () => {
  test('todoAdded 应添加新待办', async () => {
    const scope = fork()
 
    await allSettled(todoAdded, { scope, params: '学习 Effector' })
 
    const todos = scope.getState($todos)
    expect(todos).toHaveLength(1)
    expect(todos[0].title).toBe('学习 Effector')
    expect(todos[0].completed).toBe(false)
  })
 
  test('todoToggled 应切换完成状态', async () => {
    const scope = fork({
      values: [
        [$todos, [{ id: 1, title: '测试', completed: false }]],
      ],
    })
 
    await allSettled(todoToggled, { scope, params: 1 })
 
    expect(scope.getState($todos)[0].completed).toBe(true)
  })
 
  test('fetchTodosFx 成功后应更新列表', async () => {
    const mockTodos = [{ id: 1, title: 'Mock Todo', completed: false }]
    const scope = fork({
      handlers: {
        [fetchTodosFx]: async () => mockTodos,
      },
    })
 
    await allSettled(todoFetchRequested, { scope })
 
    expect(scope.getState($todos)).toEqual(mockTodos)
    expect(scope.getState($isLoading)).toBe(false)
  })
})

// babel.config.js
module.exports = {
  plugins: [
    [
      'effector/babel-plugin',
      {
        // 自动生成 sid（SSR 必需）
        addSIDs: true,
        // 开发环境启用 HMR 支持
        hotReload: process.env.NODE_ENV === 'development',
        // 强制在 Scope 内执行（防止 SSR 中的全局状态污染）
        forceScope: process.env.NODE_ENV === 'production',
        // 转换旧版 Domain 方法（迁移辅助）
        transformLegacyDomainMethods: true,
      },
    ],
  ],
}

// store.ts — 生产环境配置
import { createStore, createEvent, createEffect } from 'effector'
 
// 1. 使用 Babel/SWC 插件自动生成 sid
// 2. 生产环境启用 forceScope 防止全局状态泄露
// 3. 配合 effector-storage 做状态持久化
import { persist } from 'effector-storage/local'
 
const $theme = createStore<'light' | 'dark'>('light')
persist({ store: $theme, key: 'app-theme' })
 
// 4. 使用 patronum 提供的生产级工具
import { debounce, throttle } from 'patronum'
 
const searchInput = createEvent<string>()
const $searchQuery = createStore('')
  .on(searchInput, (_, q) => q)
 
// 防抖处理搜索输入
debounce({ source: searchInput, timeout: 300, target: $searchQuery })

import { debounce, throttle } from 'patronum'
 
// 防抖：用户停止输入 300ms 后才触发搜索
debounce({
  source: searchInput,
  timeout: 300,
  target: searchFx,
})
 
// 节流：滚动事件每 100ms 最多处理一次
throttle({
  source: scrollEvent,
  limit: 100,
  target: updateScrollPosition,
})

// 推荐：每个功能域独立目录，包含 model（逻辑）和 UI
// features/auth/
//   ├── model/
//   │   ├── index.ts       — 导出所有单元
//   │   ├── stores.ts      — Store 定义
//   │   ├── events.ts      — Event 定义
//   │   ├── effects.ts     — Effect 定义
//   │   └── connections.ts — sample/forward 连接逻辑
//   ├── ui/
//   │   ├── LoginForm.tsx
//   │   └── UserMenu.tsx
//   └── index.ts           — 统一导出
 
// features/auth/model/events.ts
import { createEvent } from 'effector'
 
export const loginButtonClicked = createEvent<{ email: string; password: string }>()
export const logoutClicked = createEvent()
 
// features/auth/model/effects.ts
import { createEffect } from 'effector'
 
export const loginFx = createEffect(
  async (credentials: { email: string; password: string }) => {
    const res = await fetch('/api/auth/login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(credentials),
    })
    if (!res.ok) throw new Error('登录失败')
    return res.json()
  }
)
 
// features/auth/model/connections.ts
import { sample } from 'effector'
import { loginButtonClicked } from './events'
import { loginFx } from './effects'
import { $user, $error } from './stores'
 
// 连接：点击登录 → 调用 Effect → 更新 Store
sample({ clock: loginButtonClicked, target: loginFx })
$user.on(loginFx.done, (_, { result }) => result)
$error.on(loginFx.fail, (_, { error }) => error.message)
      .on(loginFx.done, () => null)

import { createDomain } from 'effector'
 
const formDomain = createDomain()
 
// 域内所有 Store 可在测试前统一重置
const $email = formDomain.createStore('')
const $password = formDomain.createStore('')
const $error = formDomain.createStore<string | null>(null)
 
// 创建重置事件
const resetForm = createEvent()
 
// 通过 Domain 的 onCreateStore 统一注册重置逻辑
formDomain.onCreateStore((store) => {
  store.reset(resetForm)
})

import {
  delay,
  debounce,
  throttle,
  previous,
  condition,
  spread,
  pending,
  inFlight,
  time,
} from 'patronum'
 
// 防抖搜索
debounce({ source: searchInput, timeout: 300, target: searchFx })
 
// 节流滚动事件
throttle({ source: scrollEvent, limit: 100, target: updatePosition })
 
// 追踪 Store 的上一个值
const $previousCount = previous($count)
 
// 条件路由
condition({
  source: $formStatus,
  if: (status) => status === 'valid',
  then: submitFx,
  else: showValidationError,
})
 
// 跟踪 Effect 的并发执行数量
const $activeRequests = inFlight(fetchUserFx, fetchPostsFx)

// 服务端入口
import { fork, allSettled, serialize } from 'effector'
import { $user, fetchUserFx, userIdReceived } from './model'
 
export async function renderPage(req: Request) {
  // 每个请求创建独立 Scope
  const scope = fork()
 
  // 在 Scope 内执行所有操作
  await allSettled(userIdReceived, { scope, params: req.params.userId })
  await allSettled(fetchUserFx, { scope })
 
  // 序列化状态
  const initialState = serialize(scope)
 
  return { html: renderToString(<App />), initialState }
}
 
// ❌ 避免：在 SSR 中直接触发事件（会污染全局状态）
// userIdReceived('user-123') // 危险！所有请求共享同一状态
 
// ✅ 正确：始终通过 Scope 隔离
// await allSettled(userIdReceived, { scope, params: 'user-123' })

// ❌ 避免：在 Store 中存储函数、class 实例、DOM 引用
const $handler = createStore<() => void>(() => {}) // 无法序列化，SSR 会出错
 
// ✅ 推荐：只存储可序列化的纯数据
const $config = createStore({ apiUrl: '/api', timeout: 5000 })