The Registry is the central coordinator that manages all Atoms in an application. An Atom is a reactive unit of state. It holds a value and notifies the Registry when that value changes.
You can think of the registry as a container that:
- Stores the current value of every active Atom
- Knows which Atoms depend on which other Atoms
- Notifies the right components when values change
- Cleans up Atoms when they’re no longer needed
Let’s look at each of these responsibilities.
Centralizes Storage
The Registry maintains a map that stores a Node for each active Atom:
readonly nodes = new Map<Atom.Atom<any> | string, Node<any>>()Each Node wraps an Atom and holds:
- The current computed value
- The list of parent Atoms (dependencies)
- The list of child Atoms (dependents)
- Subscribers (React components listening for changes)
- Lifecycle state (is it initialized? is it stale?)
When you read an Atom’s value, the Registry either returns the cached value or computes it fresh.
Tracks Dependencies
Some Atoms read values from other Atoms. When this happens, the Registry automatically discovers these relationships.
When an Atom computes its value, the Registry watches which other Atoms it accesses. If Atom A reads the value of Atom B during computation, the Registry records that A depends on B. This creates a dependency graph that the Registry uses to propagate changes. When B’s value changes, the Registry recomputes A automatically.
The tracking happens automatically. You don’t need to manually declare dependencies. The Registry figures them out by observing what your Atoms actually read.
Orchestrates Updates
When an Atom’s value changes, the Registry must update all dependent Atoms and notify all subscribers. This happens through a process called invalidation.
First, the Registry marks all dependent Atoms as stale. Then, it walks through the dependency graph and recomputes each affected Atom. Finally, it notifies subscribers (your React components) so they can re-render with the new values.
This process is surgical. The Registry knows exactly which Atoms depend on the changed value, so it only updates what’s necessary. Components that don’t use the changed Atom remain untouched.
Manages Lifecycle
Atoms don’t live forever. The Registry manages when they’re created and when they’re cleaned up.
Creation happens lazily. The Registry only creates a Node when something actually needs that Atom’s value—either a component subscribes to it or another Atom reads from it.
Cleanup happens when an Atom is no longer needed. An Atom can be removed when:
- It has no subscribers (no React components watching it)
- It has no children (no other Atoms depending on it)
- It’s not marked as
keepAlive
This automatic garbage collection prevents memory leaks. Atoms that are no longer in use get cleaned up without any manual intervention.
To use Effect Atom in a Next.js app, we first need to create a Registry and make it available to the entire app. This way, components—no matter how deeply nested in the component tree—can read from and write to the same shared Registry.