smart-state

React's useState, grown up: persistent, shared across components and tabs, TTL expiry, versioned migrations, schema validation (Standard Schema), custom storage with a cookie adapter, debounced writes, SSR/Next.js-safe — with no provider, zero dependencies and ~2.1 kB min+gzip.

If you searched for "React useState with localStorage", "persist state Next.js", "share state between components without context" or "sync React state across tabs" — this is that package, in one call.

Installation

npm install smart-state
# or: pnpm add / bun add / yarn add

Requires React >= 18.

Quick start

import { useSmartState } from 'smart-state'

function Counter() {
  const [count, setCount] = useSmartState(0)
  return <button onClick={() => setCount(c => c + 1)}>{count}</button>
}

Drop-in useState semantics — lazy initializer included — plus a third element with reset() and clear().

Persistence (and everything around it)

const [theme, setTheme] = useSmartState<'light' | 'dark'>('light', {
  persist: true,
  storageKey: 'theme',
  syncTabs: true
})

One call gives you: restore on load, write on change, cross-tab sync, and — because keyed state lives in a shared store — every component using storageKey: 'theme' sees the same value instantly, with no Context provider.

// A session that expires on its own
useSmartState('', { persist: true, storageKey: 'token', ttl: 15 * 60 * 1000 })

// A draft that doesn't hammer storage on every keystroke
useSmartState('', { persist: true, storageKey: 'draft', writeDebounce: 300 })

// Non-JSON values
useSmartState(new Set<string>(), {
  persist: true,
  storageKey: 'tags',
  serializer: {
    read: (raw) => new Set(JSON.parse(raw)),
    write: (v) => JSON.stringify([...v])
  }
})

Pending debounced writes are flushed on pagehide, so closing the tab never loses the last value.

Trust nothing from storage: validation and migrations

Storage data is user-editable and survives your releases — treat it as untrusted input. Hand over any Standard Schema validator — Zod 4, Valibot, ArkType, or your own — and anything invalid falls back to the initial value (and reaches onError):

import { z } from 'zod'

const User = z.object({ name: z.string(), plan: z.enum(['free', 'pro']) })

const [user, setUser] = useSmartState(guest, {
  persist: true,
  storageKey: 'user',
  schema: User, // T is inferred from the schema output
  version: 2,
  migrate: (old, fromVersion) =>
    fromVersion === 1 ? upgradeV1(old) : undefined // undefined = discard
})

The schema runs on every read and cross-tab message, after migrate. Validation is synchronous by design: an async schema is rejected at runtime with a console.error and the initial value is used. No schema library? The lighter parse option — any (value: unknown) => T that throws — does the same job; when both are provided, schema wins and parse is ignored. version/migrate upgrade values persisted by previous releases instead of crashing on old shapes.

Defaults for new fields

Shipped a new field? Old stored objects don't have it. mergeDefaults: true shallow-merges the stored object over your defaults — { ...defaults, ...stored }, top level only — or pass (stored, defaults) => T for anything deeper. It applies only when both sides are plain objects and runs after parse/schema/migrate:

useSmartState({ theme: 'light', density: 'normal' }, {
  persist: true,
  storageKey: 'prefs',
  mergeDefaults: true // stored { theme: 'dark' } hydrates as { theme: 'dark', density: 'normal' }
})

Custom storage and the no-flash cookie recipe

storage accepts anything with getItem/setItem/removeItem and takes precedence over storageType. Adapters are synchronous by design — async storage is out of scope. The built-in cookieStorage() writes to document.cookie, which means the server can read the value too — that kills the theme flash in Next.js App Router:

'use client'
import { useSmartState, cookieStorage } from 'smart-state'

export const useTheme = () =>
  useSmartState<'light' | 'dark'>('light', {
    persist: true,
    storageKey: 'theme',
    storage: cookieStorage({ days: 365 })
  })

// app/layout.tsx — Server Component
import { cookies } from 'next/headers'

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const raw = (await cookies()).get('theme')?.value
  const theme = raw ? (JSON.parse(decodeURIComponent(raw)) as 'light' | 'dark') : 'light'
  return (
    <html lang="en" className={theme}>
      <body>{children}</body>
    </html>
  )
}

The server renders the right class in the first byte; the client hydrates from the same cookie — no flash, no suppressHydrationWarning gymnastics. Values are URI-encoded JSON, hence the decodeURIComponent + JSON.parse. cookieStorage is SSR-safe on its own: without a document, reads return null and writes no-op. Options: days (365), path (/), sameSite (lax), secure (true when sameSite: 'none').

Cross-tab sync, two transports

syncTabs: true (or 'storage') uses the storage event: zero setup, localStorage only. syncTabs: 'broadcast' uses a BroadcastChannel named after the key, which also covers sessionStorage and custom storage backends:

useSmartState('draft', { persist: true, storageKey: 'draft', storageType: 'session', syncTabs: 'broadcast' })

The channel closes cleanly when the last subscriber unmounts, and where BroadcastChannel doesn't exist the option silently degrades to the storage-event path.

Fine-grained subscriptions

Re-render only on the slice you care about:

const itemCount = useSmartSelector<Cart, number>('cart', (cart) => cart?.items.length ?? 0)

And listen from anywhere, React or not:

const unsubscribe = subscribeSmartState<Cart>('cart', (cart) => analytics.track(cart))

Obsessively typed

• Impossible states don't compile: persist: true requires storageKey; ttl, syncTabs, serializer, version only exist alongside persist — using them without it is a type error, not a runtime surprise.
• Typed keys via declaration merging: augment the registry once and every keyed API becomes fully typed:

declare module 'smart-state' {
  interface SmartStateRegistry {
    theme: 'light' | 'dark'
    cart: Cart
  }
}

getSmartState('theme') // 'light' | 'dark' | undefined — no generics needed
setSmartState('theme', 'blue') // ❌ compile error

• Built with the strictest TypeScript settings (strict, exactOptionalPropertyTypes, noUncheckedIndexedAccess, verbatimModuleSyntax) and shipped with type-level tests.

Next.js / SSR

Safe by design: the server renders the initial value; the client hydrates from storage right after mount — no hydration mismatch warnings, no typeof window guards in your code. Works in the App Router and Pages Router alike.

Outside React

import { getSmartState, setSmartState } from 'smart-state'

setSmartState('theme', 'dark') // every subscribed component re-renders

Handy in event handlers, analytics glue or non-React islands.

Sharing state across frameworks

smart-state writes the exact same storage envelope ({"__vss":1,…}, TTL and version included) as its siblings vue-smart-state and nuxt-smart-state: a React island and a Vue app on the same origin read each other's persisted state out of the box. The format is a hard invariant, locked by byte-level fixture tests.

How it compares

Sizes are the tree-shaken import, min+gzip, measured with esbuild.

| | smart-state | zustand + persist | use-local-storage-state | hand-rolled hook | | --- | :-: | :-: | :-: | :-: | | Bundle size | ~2.1 kB, zero deps | ~1.3 kB | ~0.7 kB | 0 kB — you maintain it | | TTL / expiry | ✅ | ❌ | ❌ | you write it | | Versioned migrations | ✅ | ✅ | ❌ | you write it | | Validation (Standard Schema / parse) | ✅ | ❌ (bring your own) | ❌ | you write it | | Debounced writes + flush on page hide | ✅ | ❌ | ❌ | you write it | | Shared state, no provider | ✅ | ✅ (store API) | ✅ | you write it | | Cross-tab sync | ✅ storage + broadcast | third-party middleware | ✅ storage event | you write it | | Custom storage | ✅ sync | ✅ sync + async | ❌ | you write it | | Cookie/SSR no-flash recipe | ✅ built-in cookieStorage | possible via custom storage | ❌ | you write it |

To be fair: zustand's persist middleware is excellent — it has custom and async storage, partialize, and versioned migrate. If you need async adapters or partial persistence of a large store, use it. smart-state trades those for a drop-in useState API with TTL, schema validation, debounce and a cookie recipe included in one call.

Built on useSyncExternalStore: concurrent-mode correct, tearing-safe, and re-renders only the components that use the key.

Options

| Option | Type | Default | Description | | --------------- | ---------------------------------------- | -------------- | ------------------------------------------------------------------ | | persist | boolean | false | Persist to web storage (requires storageKey). | | storageKey | string | — | Storage key; also the sharing key across components. | | storageType | 'local' \| 'session' | 'local' | Which storage to use. | | storage | StorageLike | — | Custom sync storage backend; wins over storageType. | | syncTabs | boolean \| 'storage' \| 'broadcast' | false | Sync across tabs via the storage event or a BroadcastChannel. | | ttl | number | — | Milliseconds a persisted value stays fresh. | | writeDebounce | number | — | Debounce storage writes; flushed on pagehide. | | serializer | { read(raw): T; write(value): string } | JSON | Custom (de)serialization. | | onError | (error, context) => void | console.warn | Called on read/write/sync failures. | | parse | (value: unknown) => T | — | Validate untrusted data from storage/sync (throw to reject). | | schema | StandardSchemaV1<unknown, T> | — | Standard Schema validator (sync only); wins over parse. | | mergeDefaults | boolean \| (stored, defaults) => T | false | Merge stored plain objects over the defaults (true = shallow). | | version | number | — | Schema version of the persisted value. | | migrate | (value, fromVersion) => T | undefined | — | Upgrade older persisted values; undefined discards them. |

Development

bun install && bun run test   # or npm / pnpm / yarn
bun run typecheck && bun run build && bun run size

License

MIT © Luigi Davide Micca