Nano Stores Persistent

By default, changes to persistent stores are synchronized across browser tabs. To disable this behavior for a specific store, set the listen option to false in the configuration object.

import { persistentAtom } from '@nanostores/persistent'

// Synchronization is disabled for this store
export const $draft = persistentAtom('draft', '', { listen: false })

For testing environments, use the provided test API to replace localStorage with a fake engine. This allows you to manipulate keys and inspect storage state without a real browser environment.

Available helpers:

• useTestStorageEngine(): Activates the fake engine.
• setTestStorageKey(key, value): Manually sets a value in the fake storage.
• cleanTestStorage(): Clears the fake storage.
• getTestStorage(): Returns the entire fake storage object.

import {
  useTestStorageEngine,
  setTestStorageKey,
  cleanTestStorage,
  getTestStorage
} from '@nanostores/persistent'

import { $settings } from './storage.js'

beforeAll(() => {
  useTestStorageEngine()
})

afterEach(() => {
  cleanTestStorage()
})

it('listens for changes', () => {
  setTestStorageKey('settings:locale', 'ru')
  expect($settings.get()).toEqual({ locale: 'ru' })
})

Install the @nanostores/persistent package along with the core nanostores library using npm.

npm install nanostores @nanostores/persistent

Nano Stores Persistent has built-in SSR support. On the server, stores use empty objects instead of localStorage. To ensure the client has the correct state, you can manually initialize stores with data during the server lifecycle.

if (isServer) {
  $locale.set(user.locale)
}

A specialized wrapper for storing boolean values in localStorage.

import { persistentBoolean } from '@nanostores/persistent'

export const $reduceMotion = persistentBoolean('reduce-motion')

Use persistentAtom to create a store that keeps a single primitive or object value under a single localStorage key. You can provide custom encode and decode functions to handle serialization (e.g., using JSON.stringify and JSON.parse).

If the key is missing in localStorage, the store will use the provided initial value.

import { persistentAtom } from '@nanostores/persistent'

export const $shoppingCart = persistentAtom<Product[]>('cart', [], {
  encode: JSON.stringify,
  decode: JSON.parse
})

// Updating the value
$shoppingCart.set([...$shoppingCart.get(), newProduct])

persistentJSON is a shortcut for persistentAtom that automatically handles JSON serialization and deserialization for objects, arrays, and primitives.

If you omit the initial value argument, the store type will include null to account for the empty state.

import { persistentJSON } from '@nanostores/persistent'

const $cart = persistentJSON<Product[]>('cart', [])
const $theme = persistentJSON<'dark' | 'light' | 'auto'>('theme', 'auto')

// If initial value is omitted, type becomes Product[] | null
const $comments = persistentJSON<Comment[]>('comments')

$cart.set([...$cart.get(), newProduct])
$theme.set('dark')

You can use the encode and decode options in persistentAtom to transform values before they are written to or read from storage. This is useful for custom serialization logic.

import { persistentAtom } from '@nanostores/persistent'

export const $draft = persistentAtom('draft', [], {
  encode(value) {
    return JSON.stringify(value)
  },
  decode(value) {
    try {
      return JSON.parse(value)
    } catch() {
      return value
    }
  }
})

persistentMap stores each key of an object in a separate localStorage key. This is more efficient for objects where you want to update individual properties without re-writing the entire object.

To update a specific key within the map, use the setKey method.

import { persistentMap } from '@nanostores/persistent'

export type SettingsValue = {
  sidebar: 'show' | 'hide'
  theme: 'dark' | 'light' | 'auto'
}

// Keys will be stored as 'settings:sidebar' and 'settings:theme'
export const $settings = persistentMap<SettingsValue>('settings:', {
  sidebar: 'show',
  theme: 'auto'
})

// Update a specific key
$settings.setKey('sidebar', 'hide')

For testing purposes, you can use useTestStorageEngine() to redirect all persistent stores to an in-memory test storage instead of localStorage. This prevents side effects in your test environment.

Related Test APIs:

• setTestStorageKey(key, newValue): Manually update the test storage and trigger events.
• getTestStorage(): Retrieve the current state of the test storage.
• cleanTestStorage(): Clear all keys from the test storage.

import { useTestStorageEngine, setTestStorageKey } from '@nanostores/persistent'

// Setup test environment
useTestStorageEngine()

// Simulate an external change
setTestStorageKey('my-key', 'new-value')