Effect

jotai-effect is a utility package for reactive side effects in Jotai.

Install

npm install jotai-effect

observe

observe mounts an effect to watch state changes on a Jotai store. It’s useful for running global side effects or logic at the store level.

If you don’t have access to the store object and are not using the default store, use atomEffect or withAtomEffect instead.

Signature

type Cleanup = () => void

type Effect = (
  get: Getter & { peek: Getter }
  set: Setter & { recurse: Setter }
) => Cleanup | void

type Unobserve = () => void

function observe(effect: Effect, store?: Store): Unobserve

effect: A function for observing and reacting to atom state changes.

store: A Jotai store to mount the effect on. Defaults to the global store if not provided.

returns: A stable function that removes the effect from the store and cleans up any internal references.

Usage

import { observe } from 'jotai-effect'

const unobserve = observe((get, set) => {
  set(logAtom, `someAtom changed: ${get(someAtom)}`)
})

unobserve()

This allows you to run Jotai state-dependent logic outside React’s lifecycle, ideal for application-wide effects.

Usage With React

Pass the store to both observe and the Provider to ensure the effect is mounted to the correct store.

const store = createStore()
const unobserve = observe((get, set) => {
  set(logAtom, `someAtom changed: ${get(someAtom)}`)
}, store)

<Provider store={store}>...</Provider>

Open in StackBlitz

atomEffect

atomEffect creates an atom for declaring side effects that react to state changes when mounted.

Signature

function atomEffect(effect: Effect): Atom<void>

effect: A function for observing and reacting to atom state changes.

Usage

import { atomEffect } from 'jotai-effect'

const logEffect = atomEffect((get, set) => {
  set(logAtom, get(someAtom)) // Runs on mount or when someAtom changes
  return () => {
    set(logAtom, 'unmounting') // Cleanup on unmount
  }
})

// activates the atomEffect while Component is mounted
function Component() {
  useAtom(logEffect)
}

withAtomEffect

withAtomEffect binds an effect to a clone of the target atom. The effect is active while the cloned atom is mounted.

Signature

function withAtomEffect<T>(targetAtom: Atom<T>, effect: Effect): Atom<T>

targetAtom: The atom to which the effect is bound.

effect: A function for observing and reacting to atom state changes.

Returns: An atom that is equivalent to the target atom but having a bound effect.

Usage

import { withAtomEffect } from 'jotai-effect'

const valuesAtom = withAtomEffect(atom(null), (get, set) => {
  set(valuesAtom, get(countAtom))
  return () => {
    // cleanup
  }
})

Dependency Management

Aside from mount events, the effect runs when any of its dependencies change value.

Sync: All atoms accessed with get inside the effect are added to the atom’s dependencies.
Example
```
atomEffect((get, set) => {
  // updates whenever `anAtom` changes value
  get(anAtom)
})
```

Async: Asynchronous get calls do not add dependencies.

Example

atomEffect((get, set) => {
  setTimeout(() => {
    // does not add `anAtom` as a dependency
    get(anAtom)
  })
})

Cleanup: get calls in cleanup do not add dependencies.

Example

atomEffect((get, set) => {
  return () => {
    // does not add `anAtom` as a dependency
    get(anAtom)
  }
})

Dependency Map Recalculation: Dependencies are recalculated on every run.

Example

atomEffect((get, set) => {
  if (get(isEnabledAtom)) {
    // `isEnabledAtom` and `anAtom` are dependencies
    const aValue = get(anAtom)
  } else {
    // `isEnabledAtom` and `anotherAtom` are dependencies
    const anotherValue = get(anotherAtom)
  }
})

Effect Behavior

Executes Synchronously: effect runs synchronous in the current task after synchronous evaluations complete.

Example

const logCounts = atomEffect((get, set) => {
  set(logAtom, `count is ${get(countAtom)}`)
})
const actionAtom = atom(null, (get, set) => {
  get(logAtom) // 'count is 0'
  set(countAtom, (value) => value + 1) // effect runs synchronously
  get(logAtom) // 'count is 1'
})
store.sub(logCounts, () => {})
store.set(actionAtom)

Batched Updates: Multiple synchronous updates are batched as a single atomic transaction.

Example

const tensAtom = atom(0)
const onesAtom = atom(0)
const updateTensAndOnes = atom(null, (get, set) => {
  set(tensAtom, (value) => value + 1)
  set(onesAtom, (value) => value + 1)
})
const combos = atom([])
const effectAtom = atomEffect((get, set) => {
  const value = get(tensAtom) * 10 + get(onesAtom)
  set(combos, (arr) => [...arr, value])
})
store.sub(effectAtom, () => {})
store.set(updateTensAndOnes)
store.get(combos) // [00, 11]

Resistant to Infinite Loops: atomEffect avoids rerunning when it updates a value that it is watching.

Example

atomEffect((get, set) => {
  get(countAtom)
  set(countAtom, (value) => value + 1) // Will not loop
})

Cleanup Function: The cleanup function is invoked on unmount or before re-evaluation.

Example

atomEffect((get, set) => {
  const intervalId = setInterval(() => set(clockAtom, Date.now()))
  return () => clearInterval(intervalId)
})

Idempotency: atomEffect runs once per state change, regardless of how many times it is referenced.

Example

let i = 0
const effectAtom = atomEffect(() => {
  get(countAtom)
  i++
})
store.sub(effectAtom, () => {})
store.sub(effectAtom, () => {})
store.set(countAtom, (value) => value + 1)
console.log(i) // 1

Conditionally Running Effects: atomEffect only runs when mounted.

Example

atom((get) => {
  if (get(isEnabledAtom)) {
    get(effectAtom)
  }
})

Supports Peek: Use get.peek to read atom data without subscribing.

Example

const countAtom = atom(0)
atomEffect((get, set) => {
  const count = get.peek(countAtom) // Will not add `countAtom` as a dependency
})

Supports Recursion: Recursion is supported with set.recurse but not in cleanup.

Example

atomEffect((get, set) => {
  const count = get(countAtom)
  if (count % 10 === 0) {
    return
  }
  set.recurse(countAtom, (value) => value + 1)
})