Documentation

createPersister

stable

Create a persister instance

Create a persister instance for saving and restoring query cache data. Supports various storage backends like localStorage, sessionStorage implementations.

PersistenceStorage

Storages

createPersister supports localStorage and sessionStorage implementations. Choose the right one for your use case.

Per-Query Control

Use the persist: false option on individual queries to exclude sensitive or temporary data from persistence while keeping other queries persisted.

Signature

function createPersister(
  type: 'local' | 'session',
  config?: PersisterConfig
): Persister | undefined

Parameters

type

'local' | 'session'Required

Storage type to use. 'local' for localStorage, 'session' for sessionStorage.

config

PersisterConfigDefault: {}

Optional configuration object with burstKey, prefix, and debounceTime.

config.burstKey

stringDefault: 'package version'

Version key to invalidate old cached data when breaking changes occur.

config.prefix

stringDefault: 'qortex'

Prefix for storage keys to avoid conflicts with other applications.

config.debounceTime

numberDefault: 100

Time in milliseconds to debounce save operations for performance.

Returns

Returns

Persister | undefined

Persister instance with save, load, sync, and clear methods, or undefined if storage is not available

Examples

Basic Usage

Create a localStorage persister

import { createPersister } from 'qortex-core/persister';
import { setDefaultConfig } from 'qortex-react';


// Create a localStorage persister
const persister = createPersister('local');


// Use with setDefaultConfig
setDefaultConfig({ persister });

Session Storage

Create a sessionStorage persister

import { createPersister } from 'qortex-core/persister';
import { setDefaultConfig } from 'qortex-react';


// Create a sessionStorage persister
const sessionPersister = createPersister('session');


// Use for session-based caching
setDefaultConfig({ persister: sessionPersister });

With Configuration

Create a persister with custom configuration

import { createPersister } from 'qortex-core/persister';
import { setDefaultConfig } from 'qortex-react';


// Create a persister with custom configuration
const persister = createPersister('local', {
  burstKey: 'v1.0.0',
  prefix: 'my_app_cache',
  debounceTime: 50
});


setDefaultConfig({ persister });

Selective Persistence

Exclude specific queries from persistence

import { createPersister } from 'qortex-core/persister';
import { setDefaultConfig, registerFetcher } from 'qortex-react';


// Enable persistence globally
const persister = createPersister('local', { burstKey: 'v1' });
setDefaultConfig({ persister });


// This query will be persisted (default)
registerFetcher('user-profile', {
  fetcher: () => fetch('/api/profile').then(r => r.json())
});


// This query will NOT be persisted (sensitive data)
registerFetcher('auth-token', {
  fetcher: () => fetch('/api/token').then(r => r.json()),
  persist: false // Exclude from persistence
});

Behavior

Storages

Supports various storage backends (localStorage, sessionStorage)

Configurable

Highly configurable with custom serialization and age limits

Async Operations

All operations are asynchronous for better performance

Error Handling

Built-in error handling for storage operations

Related Pages

PersisterConfigPersistersetDefaultConfig