configureStores: Global Configuration for All Stores

configureStores establishes global defaults that apply to every store created in your application. It must be called before any store is created — typically at the top of your app’s entry point or initialization module. Any options you do not set fall back to sensible environment-specific defaults.

Signature

function configureStores(config: Partial<StoresConfig>): void

`StoresConfig` fields

storage

SyncStorageInterface | AsyncStorageInterface

The storage backend used by all persisted stores. Defaults to localStorage in browser environments and MMKV in React Native. Supply a custom adapter to swap in any other key-value storage.

syncEngine

SyncEngine

The sync engine used for cross-client state synchronization. Defaults to a BroadcastChannel-based cross-tab engine in browsers and a no-op engine in all other environments. Replace this with a WebSocket or chrome.storage engine for multi-device sync.

storageKeyPrefix

string

default:"'stores:'"

A prefix prepended to every storage key generated by the default storage adapter. Should include a delimiter such as a colon, e.g. 'myapp:'. Only applies when using the built-in storage adapter — custom adapters manage their own key scheme.

logger

Logger

A custom logger for framework debug output. Defaults to a no-op logger in production builds. Provide { debug, error, info, warn } to route framework messages through your own logging infrastructure.

queryStoreDefaults

QueryStoreDefaults

Default configuration values applied to every query store. Individual stores can override any of these values in their own config.

Show QueryStoreDefaults fields

staleTime

number

default:"time.minutes(2)"

Duration in milliseconds that fetched data is considered fresh. After this window, the store may automatically refetch in the background while active subscribers exist.

cacheTime

number

default:"time.days(7)"

Maximum duration in milliseconds that a cache entry is retained before it becomes eligible for pruning.

maxRetries

number

default:"5"

Maximum number of retry attempts after a failed fetch.

abortInterruptedFetches

boolean

default:"true"

When true, an in-flight fetch is aborted when new parameters arrive or all subscribers unmount.

keepPreviousData

boolean

default:"false"

When true, getData() continues to return the previous cache entry while a refetch for new parameters is in progress.

disableAutoRefetching

boolean

default:"false"

When true, the store will not automatically trigger refetches when data becomes stale while components are mounted.

paramChangeThrottle

false | number | DebounceOptions

default:"false"

Delay before triggering a fetch when parameters change. Accepts a number (ms), false for no throttle, or a debounce options object.

retryDelay

number | ((retryCount: number, error: Error) => number)

Delay between retries in milliseconds. Accepts a fixed number or a function receiving the retry count and the error. Defaults to exponential backoff starting at 5 seconds, doubling each attempt, capped at 5 minutes.

debugMode

boolean

default:"false"

When true, all query stores emit debug log messages to the console.

suppressStaleTimeWarning

boolean

default:"false"

Suppresses development warnings when a staleTime shorter than minStaleTime is configured.

minStaleTime

number | false

default:"false"

Minimum stale time threshold below which a development warning is logged when auto-refetching query stores are configured. Set to false to disable all such warnings.

Example

import { configureStores, time } from '@storesjs/stores';

configureStores({
  storageKeyPrefix: 'myapp:',
  queryStoreDefaults: {
    staleTime: time.minutes(5),
    maxRetries: 3,
  },
  logger: {
    debug: console.debug,
    error: console.error,
    info: console.info,
    warn: console.warn,
  },
});

Calling configureStores after any store has been created throws an error in development:

[stores]: configureStores() called after first store creation. Call it earlier before creating any stores.

Always invoke configureStores at the top of your entry point, before any createBaseStore, createQueryStore, or other store creator call executes.

Store Creators

Utilities

Types

configureStores: Global Configuration for All Stores

Signature

`StoresConfig` fields

Example

Build docs developers (and LLMs) love

Store Creators

Utilities

Types

Documentation Index

​Signature

​StoresConfig fields

​Example

Build docs developers (and LLMs) love

Signature

`StoresConfig` fields

Example