Shared state with createContextState
createContextState<State>() creates a typed store and the hooks to use it. A Provider owns the state. Components read slices with selectors, and each one rerenders only when its selected value changes. Updates take a partial object or an Immer draft function, and each update returns a function that undoes it.
Use it for state that several components of one feature share: a form, an editor, a page's filters, the app shell (user, language, permissions). Keep state that one component owns in useState. Keep server cache concerns (refetching, retries, cache invalidation) in a data-fetching library; write its results into a store only when components edit them.
The patterns below come from production React and Next.js apps. The example apps run the profile editor from this guide.
1. Quick start
'use client' // only needed in Next.js App Router
import { createContextState } from '@khanglvm/react'
const counter = createContextState<{ count: number }>()
function Count() {
const count = counter.useContextStateValue(state => state.count)
return <p>Count: {count}</p>
}
function AddOne() {
const setState = counter.useSetContextState()
return <button onClick={() => setState(draft => { draft.count += 1 })}>Add one</button>
}
export default function App() {
return (
<counter.Provider initialState={{ count: 0 }}>
<Count />
<AddOne />
</counter.Provider>
)
}Clicking the button rerenders Count. AddOne does not subscribe, so the store never rerenders it.
2. Create a store module
Give each store its own file. Call the factory at module level, never inside a component, and rename the hooks after the feature so call sites read clearly.
// profile/profile-store.ts
'use client'
import { createContextState } from '@khanglvm/react'
export type ProfileState = {
profile: { id: string; name: string }
draftName: string
status: 'idle' | 'saving' | 'saved' | 'failed'
}
export const {
Provider: ProfileProvider,
useContextState: useProfileState, // [value, setState, getSnapshot]
useContextStateValue: useProfileValue, // value only
useSetContextState: useSetProfile, // setState only, no subscription
useStateSnapshotGetter: useProfileSnapshot, // read without subscribing
withContextProvider: withProfileProvider,
} = createContextState<ProfileState>('profile')The optional argument ('profile') is an instance ID. In the browser it keeps the same React context when a module is evaluated twice, for example after a hot reload or when two bundles load the same file. Use a distinct ID for each store, or leave it out.
Keep types and plain helpers in a separate file if server components need them. In Next.js, everything exported from a 'use client' file is a client reference, so a server component cannot call a helper function from it.
3. Read with selectors
A selector picks what a component needs:
const name = useProfileValue(state => state.profile.name)
const isSaving = useProfileValue(state => state.status === 'saving')
const count = useProfileValue(state => state.items.filter(item => item.done).length)A selector can return a new object or array. The store compares the result with the previous one by value (deepEqual) and keeps the previous reference when they match, so this does not rerender on every change:
const { name, status } = useProfileValue(state => ({
name: state.profile.name,
status: state.status,
}))Without a selector, the hook returns the whole state, and the component rerenders on any change.
Rules for selectors:
- Keep them pure: the same state gives the same result, with no
Date.now(), random values or side effects. In development builds (process.env.NODE_ENV === 'development'),useContextStateValueruns each selector twice and throws if the results differ. Vite, webpack and Next.js set that value indevand replace it in production builds, so the check runs while you develop and is skipped in production builds. Node and test runners readNODE_ENVfrom the environment. - Treat the result as read-only. Change state through the setter.
- Prefer small results. Comparing a large selected tree on every update costs time, and cyclic data is not supported.
4. Update state
setState accepts a partial object or a draft function.
const setState = useSetProfile()
// Partial object: replaces the listed top-level fields.
setState({ status: 'saving' })
// Draft function: change nested data in place; Immer produces the next state.
setState(draft => {
draft.profile.name = 'Khang Le'
draft.status = 'saved'
})A partial object replaces each listed top-level field as a whole; it does not merge into nested objects. To change profile.name and keep profile.id, use a draft.
Values passed in a partial object are deep-copied with deepClone. Keep state to plain data: objects, arrays, primitives, Date, Map, Set. An Error, a Promise or a WeakMap makes the copy throw Unsupported type, and a class instance becomes a plain object. Store String(error) rather than the error. Functions are kept by reference.
The state is frozen from the moment the Provider mounts: initialState is deep-frozen in place, and every later state comes frozen from Immer. An object you put in the store, through initialState or a draft (an API response, a default constant), is frozen in place too, so other code that still holds it can no longer mutate it. Copy it first if something else changes it later. Like Immer, the freeze does not reach class instances, the keys and values inside a Map or Set (the collection itself is frozen), or the children of an object that was already frozen with Object.freeze. Edit those through the setter too.
The state changes immediately, so the snapshot getter (section 5) sees it on the next line. Subscribers are notified once per microtask, so several setState calls in one handler cause one rerender pass.
useSetProfile() does not subscribe the component to changes. Use it for buttons and handlers that write without reading. To read and write in one component, useProfileState(selector) returns [value, setState, getSnapshot]:
const [draftName, setState] = useProfileState(state => state.draftName)
<input value={draftName} onChange={e => setState({ draftName: e.target.value })} />5. Read the latest state in handlers
A value from render can be stale in an async handler. useProfileSnapshot() returns a getter that reads the current state when called, without subscribing:
const getSnapshot = useProfileSnapshot()
async function save() {
const { profile, draftName } = getSnapshot()
// or with a selector: getSnapshot(state => state.draftName)
await api.saveName(profile.id, draftName)
}Use it to guard duplicate requests too:
async function loadMore() {
if (getSnapshot(state => state.isLoading)) return
// ...
}The snapshot is the store's current object, not a copy, so reading it costs nothing and its references stay stable between reads. Because the state is frozen (section 4), changing it throws a TypeError instead of silently skipping the subscribers. To get an editable copy, use deepClone(getSnapshot()) or structuredClone, then write changes back with setState.
6. Seed the store with data
initialState is read once, when the Provider mounts. Later changes to the prop do not reset the store, so edits in progress survive parent rerenders.
React (client-side data): mount the Provider when the data is ready.
function ProfilePage() {
const [profile, setProfile] = useState<Profile | null>(null)
useEffect(() => { getProfile().then(setProfile) }, [])
if (!profile) return <Spinner />
return (
<ProfileProvider initialState={{ profile, draftName: profile.name, status: 'idle' }}>
<ProfileCard />
</ProfileProvider>
)
}Next.js App Router: fetch in a server component and pass serializable data to the Provider.
// app/profile/page.tsx (server component)
import { ProfileProvider } from '@/profile/profile-store'
import { profileStateFrom } from '@/profile/profile' // plain module, not 'use client'
export default async function Page() {
const profile = await getProfile()
return (
<ProfileProvider initialState={profileStateFrom(profile)}>
<ProfileCard />
</ProfileProvider>
)
}Give the Provider a complete initial state. initialState is typed as Partial<State>, but selectors read fields that must exist.
To start over with fresh data, remount the Provider, for example with key={profile.id}.
7. Optimistic updates with revert
Every setState returns a function that undoes that update. Show the change immediately, then undo it if the request fails:
async function save() {
const { profile, draftName } = getSnapshot()
const revert = setState(draft => {
draft.profile.name = draftName
draft.status = 'saving'
})
try {
await api.saveName(profile.id, draftName)
setState({ status: 'saved' })
} catch {
revert() // profile.name and status return to their values before this update
setState({ status: 'failed' })
}
}The revert applies Immer's inverse patches for that one update to the current state:
- Fields changed only by other updates keep their new values.
- A field changed by this update and then changed again is set back to the value before this update, overwriting the later change.
- Revert functions are independent. There is no history stack or redo.
If two saves can overlap on the same field, queue them or disable the button while one is pending.
Pass false to skip recording patches when you never revert. The returned function then does nothing:
const setState = useSetProfile(false)
const [value, setFast] = useProfileState(selector, false)8. Load data into the store
Stores can hold fetched data next to the UI state that edits it. Keep loading flags in the store too:
async function loadNotifications(page: number) {
if (getSnapshot(state => state.isLoading)) return // already loading
setState({ isLoading: true })
try {
const result = await api.notifications(page)
setState(draft => {
draft.items.push(...result.items)
draft.page = page
draft.isLoading = false
})
} catch (error) {
setState({ isLoading: false, error: String(error) })
}
}If you already use React Query, SWR or Apollo, let it own server data and caching, and use a store for the editable copy or the UI state around it.
9. Wrap the store in feature hooks
Export hooks that describe the feature instead of exposing selectors everywhere. Components then depend on intent, and you can change the state shape in one place.
export function useUnreadCount() {
return useNotificationValue(state => state.items.filter(item => !item.read).length)
}
export function useNotificationActions() {
const setState = useSetNotifications(false)
return useMemo(() => ({
markRead(id: string) {
setState(draft => {
const item = draft.items.find(entry => entry.id === id)
if (item) item.read = true
})
},
clear() {
setState({ items: [] })
},
}), [setState])
}The setter is stable for the life of the Provider, so useMemo keeps the actions object stable too.
10. Scope, nesting and several stores
Each Provider owns separate state. Where you place it decides who shares it:
- App-wide state (user, language, permissions): one Provider in the root layout.
- A page or flow: a Provider in that route's layout, so the state survives navigation between its child routes.
- Per instance: a Provider inside a repeated component, so each card or dialog has its own state.
Providers of different stores nest freely. A component reads each store through its own hooks:
<AppShellProvider initialState={shell}>
<ChatProvider initialState={{ messages: [] }}>
<JobEditorProvider initialState={job}>
<Page />
</JobEditorProvider>
</ChatProvider>
</AppShellProvider>When a handler in an inner feature needs a value from an outer store, read it with the outer store's snapshot getter instead of subscribing.
A component outside its matching Provider gets an empty fallback store: selectors read {} and setters do nothing. The package raises no missing-Provider error, but a selector that reads a nested field, such as state => state.profile.name, throws a TypeError. Development builds log a one-time warning per store. If an update seems to vanish, check that the component sits under the Provider created by the same factory call.
11. Wrap a component with its Provider
withContextProvider returns a component that renders its own Provider, with initial state derived from props:
type ProfileCardProps = { profile: Profile }
export const ProfileCard = withProfileProvider<ProfileCardProps>(
function ProfileCardView() {
const name = useProfileValue(state => state.profile.name)
return <h2>{name}</h2>
},
{
initialState: props => ({ profile: props.profile, draftName: props.profile.name, status: 'idle' }),
},
)
// <ProfileCard profile={profile} />, each instance with its own storeThe type parameter describes the component's props, not the store.
An optional bindPropToState(draft, props) copies props into the store when a prop value changes after mount. Props are compared key by key with Object.is, so a parent rerender with the same values does nothing. When a value does change, the callback overwrites the fields it writes, including local edits to them. Inline functions, JSX children and inline objects or arrays are new values on every render, so they count as changes: memoize them with useCallback/useMemo, or keep them out of the wrapped component's props.
StateSynchronizer exposes the same mechanism as a component that you render under an existing Provider. It compares its data prop the same way: an inline object of primitive values is fine, while a Date, Map, Set or class instance compares by reference.
<StateSynchronizer data={{ name }} updateStateOnDataChanged={(draft, data) => { draft.draftName = data.name }} />Both are experimental. Prefer seeding with initialState and writing from event handlers.
12. Compute derived data once per batch
When many updates in a row invalidate an expensive derived value, register a post-flush callback. It runs once per microtask batch, after all updates and before subscribers are notified, and it receives an Immer draft:
function HierarchyRegistrar() {
const setPostFlush = useSetBuilderPostFlush()
useEffect(() => {
setPostFlush(draft => {
if (!draft.hierarchyStale) return
draft.hierarchy = buildHierarchy(draft.blocks)
draft.hierarchyStale = false
})
}, [setPostFlush])
return null
}
// Updates only mark the value stale:
setState(draft => {
draft.blocks.push(block)
draft.hierarchyStale = true
})Render the registrar once inside the Provider. Each Provider holds one callback; registering again replaces it, and there is no unregister function. Changes made by the callback are not part of any revert.
13. Server rendering and Next.js
- The package entry for this utility already carries
'use client'. Add'use client'to your files that callcreateContextState(server components import their Provider from them) and to every component that calls the hooks. - Server components can render the Provider and pass
initialState, as in section 6. The data must be serializable. - Each Provider creates its own store during server rendering. Two requests never share state, even with the same instance ID.
- Pass the same initial values on the server and on the client so hydration matches.
- Selected snapshots are cached per hook, so finished server renders release them without effect cleanup.
See the Next.js guide for where each piece of the package runs.
14. How it works and what to watch for
The Provider keeps the state in a ref and a set of subscribers. Hooks subscribe through useSyncExternalStore. On a change, every subscriber of that Provider runs its selector; a component rerenders only if its selected value differs by deepEqual from the previous one. This is selector-level filtering, not field-level dependency tracking, so many subscribers with heavy selectors still cost work on each update.
Checklist:
- Call
createContextStateat module level. - Provide every field in
initialState. - Keep selectors pure and their results small.
- Use drafts for nested updates; partial objects replace top-level fields.
- Use the snapshot getter, not render values, inside async code.
- Treat snapshots and selected values as read-only; they are frozen. Copy before editing.
- Remount the Provider (
key) to reset it; changinginitialStatedoes nothing after mount. - Check Provider placement when updates seem to do nothing.
15. API reference
createContextState<State>(instanceId?) returns:
| Export | Signature | Notes |
|---|---|---|
Provider | <Provider initialState?={Partial<State>}> | Reads initialState once on mount |
useContextState | (selector?, enableRevert = true) => [value, setState, getSnapshot] | Subscribes |
useContextStateValue | (selector?) => value | Subscribes; dev purity check |
useSetContextState | (enableRevert = true) => setState | No subscription |
useStateSnapshotGetter | () => getSnapshot | No subscription |
useSetPostFlush | () => (callback: (draft) => void) => void | One callback per Provider |
withContextProvider | (Component, { initialState?, bindPropToState? }) | Wraps in a Provider; forwards refs |
StateSynchronizer | <StateSynchronizer data updateStateOnDataChanged /> | Experimental |
withStateProvider | Same as withContextProvider | Deprecated name |
setState(partialOrDraftFn) => revert:revert()undoes that update; withenableRevert = falseit does nothing.getSnapshot(selector?): returns the current state, or the selector's result.
createStateManager<State>(instanceId?) wraps the same store and adds older names: useState, useStateValue, useSetState, useSnapshot, withProvider. Use createContextState in new code.
Type helpers: TContextState and TStateManager are the return types of the two factories.
Install
Install the package from npm. It needs React 18 or 19.
Typed translations
Each dictionary entry holds every language side by side, so TypeScript reports a missing language and autocompletes every key. Components read text through a hook that follows your app's current language. When the language changes, every component that uses the hook rerenders in the new language: no page reload and no dictionary download, because the dictionaries are ordinary TypeScript modules in your bundle.