Skip to main content
Version: Next

Interface: MnemonicProviderProps

Defined in: src/Mnemonic/provider.tsx:90

Props for the MnemonicProvider component.

Extends MnemonicProviderOptions with required children prop.

See​

Extends​

Properties​

bootstrap?​

readonly optional bootstrap?: MnemonicBootstrapSeed<Record<string, unknown>>

Defined in: src/Mnemonic/types.ts:212

Optional bootstrap snapshot used to seed the provider cache before the first hook subscribes.

Pass the object returned by recallMnemonic(...) when you synchronously read values before React renders, for example to apply a theme attribute before first paint and then ensure the first useMnemonicKey(...) read sees the same raw storage snapshot without re-reading storage.

This seed is consumed only during the provider's initial mount. Later prop changes are ignored so rerenders do not recreate the internal store.

Inherited from​

MnemonicProviderOptions.bootstrap

children​

readonly children: ReactNode

Defined in: src/Mnemonic/provider.tsx:94

React children to render within the provider.

enableDevTools?​

readonly optional enableDevTools?: boolean

Defined in: src/Mnemonic/types.ts:143

Enable DevTools debugging interface.

When enabled, registers this provider in the global window.__REACT_MNEMONIC_DEVTOOLS__ registry.

The registry stores providers as weak references and exposes:

  • resolve(namespace) to strengthen a provider reference and access inspection methods.
  • list() to enumerate provider availability.

Default​

false

Example​

// Enable in development only
enableDevTools: process.env.NODE_ENV === 'development'

// Then in browser console:
const provider = window.__REACT_MNEMONIC_DEVTOOLS__?.resolve('myApp')
provider?.dump()
provider?.get('user')
provider?.set('user', { name: 'Test' })

Inherited from​

MnemonicProviderOptions.enableDevTools

namespace​

readonly namespace: string

Defined in: src/Mnemonic/types.ts:92

Namespace prefix for all storage keys.

All keys stored by this provider will be prefixed with ${namespace}. to avoid collisions between different parts of your application or different applications sharing the same storage backend.

Example​

// With namespace="myApp", a key "user" becomes "myApp.user" in storage
namespace: "myApp"

Inherited from​

MnemonicProviderOptions.namespace

onStorageError?​

readonly optional onStorageError?: (event) => void

Defined in: src/Mnemonic/types.ts:280

Called when a mutation did not reach storage.

Without this, a dropped write produces only a console.error, which is invisible to the people using the application. This is the programmatic channel: it lets an app tell the user their changes are not being saved while they can still do something about it.

Fires for every classified failure — quota, blocked access, schema rejection, encode failure, and synchronous-contract violations — whether the mutation came from set(), reset(), remove(), or a flush() retry.

Parameters​

ParameterType
eventMnemonicStorageErrorEvent

Returns​

void

Remarks​

Not every event is queued for retry. The callback is strictly wider than Mnemonic.unpersistedKeys, and MnemonicStorageErrorEvent.reason says which kind you have:

  • "quota", "access", "contract" are storage-layer drops. The cache holds the new value, the key is queued, and flush() can retry it. For these the two channels agree exactly — this says a write was dropped, unpersistedKeys() says it is still outstanding.
  • "schema", "codec", "unknown" are rejected before storage is called. The cache is unchanged and nothing is queued, so these events have no matching unpersistedKeys() entry and flush() will not retry them. Do not promise the user a retry for these.

It reports drops, not throws. A write the backend rejects that turns out to leave storage holding the intended value already — a reset to the value on disk, for example — is not reported at all, matching the fact that it is not queued either.

It is not squelched. The matching console messages are logged once and then suppressed until the next success; this callback fires on every dropped mutation, so a caller can count failures or track them per key. Debounce in the handler if you are driving a notification from it.

Keep the handler cheap and side-effect-light. It runs synchronously inside the mutation, after the cache is updated and subscribers are notified. Writing to the store from inside it is not recommended; a nested failure is dropped rather than reported, to avoid unbounded recursion. Throwing is contained — the mutation still completes — and is reported once per store.

Example​

<MnemonicProvider
  namespace="app"
  onStorageError={(event) => {
    if (event.reason === "quota") {
      toast.error("Out of space — your changes are not being saved.");
    }
    telemetry.record("mnemonic_write_dropped", {
      key: event.key,
      reason: event.reason,
    });
  }}
>
  <App />
</MnemonicProvider>

See​

Inherited from​

MnemonicProviderOptions.onStorageError

schemaMode?​

readonly optional schemaMode?: SchemaMode

Defined in: src/Mnemonic/types.ts:157

Versioning and schema enforcement mode.

Controls whether stored values require a registered schema, and how missing schemas are handled. See SchemaMode for the behaviour of each mode.

Default​

"default"

See​

Inherited from​

MnemonicProviderOptions.schemaMode

schemaRegistry?​

readonly optional schemaRegistry?: SchemaRegistry

Defined in: src/Mnemonic/types.ts:179

Schema registry used for version lookup and migration resolution.

When provided, the library uses the registry to find the correct JSON Schema for each stored version, and to resolve migration paths when upgrading old data to the latest schema.

Required when schemaMode is "strict" or "autoschema". Optional (but recommended) in "default" mode.

Remarks​

In "default" and "strict" modes, the registry is treated as immutable after the provider initializes. Updates should be shipped as part of a new app version and applied by remounting the provider. "autoschema" remains mutable so inferred schemas can be registered at runtime.

See​

Inherited from​

MnemonicProviderOptions.schemaRegistry

ssr?​

readonly optional ssr?: MnemonicProviderSSRConfig

Defined in: src/Mnemonic/types.ts:198

Server-rendering and hydration defaults for descendant hooks.

Provider-level SSR settings establish the default hydration strategy for all useMnemonicKey(...) calls in this namespace. Individual hooks may still override the strategy when a specific key needs different behavior.

Example​

<MnemonicProvider
  namespace="app"
  ssr={{ hydration: "client-only" }}
>
  <App />
</MnemonicProvider>

Inherited from​

MnemonicProviderOptions.ssr

storage?​

readonly optional storage?: StorageLike

Defined in: src/Mnemonic/types.ts:116

Storage backend to use for persistence.

Defaults to window.localStorage in browser environments. You can provide a synchronous custom implementation (e.g., sessionStorage, an in-memory cache facade over IndexedDB, or a mock for testing).

Default​

window.localStorage

Example​

// Use sessionStorage instead of localStorage
storage: window.sessionStorage

// Use a custom storage implementation
storage: {
  getItem: (key) => myCustomStore.get(key),
  setItem: (key, value) => myCustomStore.set(key, value),
  removeItem: (key) => myCustomStore.delete(key)
}

Inherited from​

MnemonicProviderOptions.storage