Behavior and limitations
This page describes behavior that affects architecture and update semantics.
One store
Section titled “One store”The store lives at project scope. Every component using this package instance shares it. <Root> initializes the store only once; later <Root> renders do not reset it or create isolated stores.
This is suitable for a typical single-client app. It is not suitable when you need multiple independent stores, per-window isolation, or a store per request.
Initialization
Section titled “Initialization”<Root initial={...}> seeds the store once. Keep the initial object shape consistent with the paths your components read and write.
The optional second argument to useNativeState is scheduled as a write. The implementation does not check whether that path already has a value. For predictable initialization, seed the state in <Root> and omit that argument.
Nested updates and snapshots
Section titled “Nested updates and snapshots”Updating a nested path shallow-copies the root object, then writes into the existing nested parent. That means the parent object or array keeps its identity.
React’s useSyncExternalStore compares snapshots. A component selecting a primitive leaf usually observes a changed snapshot when that leaf changes. A component selecting the parent object may receive a notification but still see the same object reference, so React can skip rendering it.
When a parent-object snapshot must change, replace the parent with a fresh object or array. Otherwise, subscribe to the specific leaf the component needs.
Function selectors
Section titled “Function selectors”Function selectors are subscribed to all store updates. They should return a primitive or stable reference if you want unchanged values to compare equal. Creating a new object or array during each selector call creates a new snapshot.
Server-side rendering
Section titled “Server-side rendering”The store is module-level and is not isolated by request. A long-lived server process can reuse the same module instance across requests, so request-specific or user-specific state must not be stored in this shared store during server rendering. The package does not provide an SSR-safe per-request store factory.
Other limits
Section titled “Other limits”- React 18.2 or React 19 is required (
useSyncExternalStore). - No middleware, persistence, devtools, or built-in state serialization.
- Nested writes require existing parent objects or arrays.
- Setter callbacks are values, not updater functions.
- The package currently has no shipped TypeScript declaration files.
License
Section titled “License”The package is source-available, not OSI-approved open source. Read the repository’s LICENSE before using it, especially before redistributing or modifying the library.