Shared state
A native-backed key/value store that every runtime reads and writes through the same path handles.
@react-native-runtimes/state is a small Zustand-like API on top of a C++
singleton. Every runtime that calls into it sees the same value, the same
revision, and receives notifications when any value changes.
This is the right tool for any state that:
- changes often
- is too large to pass as props
- needs to be visible to more than one runtime
- needs to survive runtime teardown (with persistence enabled)
Path-based addressing
Each store gives you typed path handles:
import { createSharedStore } from '@react-native-runtimes/state';
const chatStore = createSharedStore<{ conversations: Record<string, Message[]> }>({
name: 'chat',
initialState: { conversations: {} },
});
const messages = chatStore.path<Message[]>(['conversations', 'release-room']);A path is a key into the native store — either a dot string or an array of segments. Two handles to the same path share state and notifications.
Read and write
function Conversation() {
const list = messages.use(value => value ?? []);
return <MessageList messages={list} />;
}
await messages.set(nextList, true);
await messages.update(current => [...(current ?? []), newMessage]);The hook subscribes; the setter writes through the native store, which fans out the change to every runtime that has a handle to that path or any parent path.
Hierarchical notifications
Subscribers fire for related paths, not only exact matches:
- A subscriber on
conversationsis notified whenconversations.release-roomchanges. - A subscriber on
conversations.release-roomis notified whenconversationsis replaced.
That makes broad subscriptions ("anything under conversations changed") cheap to express.
One writer per path is the rule
Writes are last-writer-wins — there is no compare-and-swap. update(...)
reads the runtime's local mirror of the value, so two runtimes writing the
same path concurrently can still clobber each other. Design so each path has
a single writing runtime; other runtimes read and subscribe.
When to reach for it instead of props
| Symptom | Use shared state |
|---|---|
| The threaded prop payload is large | Yes — keep an id in props, read the rest from the store |
| The data changes often | Yes — props re-serialize on every change |
| The data needs to be visible to a sibling runtime | Yes |
| The data is a one-shot config (id, count, mode) | No — props are fine |
See Shared state overview for the full API including persistence, predeclared subtrees, and revisions.