Skip to content

Behavior and limitations

This page describes behavior that affects architecture and update semantics.

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.

<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.

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 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.

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.

  • 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.

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.