🌊 react-vibe-state

Reactive state management with automatic persistence and cross-tab synchronization. Use state almost like a plain JavaScript object - persistence and sync happen transparently in the background.

Features

• Zero-config persistence - state automatically saved to IndexedDB
• Cross-tab sync - changes instantly propagate between browser tabs via BroadcastChannel
• Reactive - powered by Valtio proxy, React components re-render on relevant changes only
• Type-safe - full TypeScript support with inferred types for state, selectors, and actions
• Modular - organize state with slices, each with own selectors and actions
• Conflict-free - CRDT-based sync via Yjs handles concurrent edits gracefully

Under the hood:

• Valtio - reactive proxy-based state
• Yjs - CRDT for conflict-free merging
• valtio-y - two-way binding between Valtio proxy and Yjs doc
• y-indexeddb - IndexedDB persistence provider
• y-webrtc - BroadcastChannel sync (WebRTC disabled)

Installation

npm install react-vibe-state

Peer dependency: React 18 or 19

Quick Start

import { createState } from 'react-vibe-state';

// Create state (singleton, typically in a separate file)
const appState = createState({
  name: 'app',
  initial: { count: 0 },
  selectors: {
    isPositive() { return this.count > 0; },
    doubled() { return this.count * 2; },
  },
  actions: {
    increment() { this.count++; },
    decrement() { this.count--; },
  },
});

// Use in React component
function Counter() {
  const { state, selectors, actions } = appState.useSnapshot();
  
  return (
    <div>
      <span>{state.count} (doubled: {selectors.doubled()})</span>
      <button onClick={actions.increment}>+</button>
      <button onClick={actions.decrement} disabled={!selectors.isPositive()}>-</button>
    </div>
  );
}

Open the app in multiple tabs - counter stays in sync automatically.

API Reference

createState(config)

Creates a reactive state instance. Instances are cached by name (safe for HMR).

const state = createState({
  name: 'my-state',
  initial: { /* ... */ },
  selectors: { /* ... */ },
  actions: { /* ... */ },
  slices: { /* key: slice, ... */ },
  // ... options
});

Config Options

| Option | Type | Default | Description | | ------------------------------ | ---------------------------- | -------------- | -------------------------------------------------------- | | persistAndSync | boolean | true | Enable browser storage persistence and cross-tab sync | | storage | "indexed-db" | "indexed-db" | Storage backend | | name | string | required | Unique identifier (letters, numbers, _, -) | | generation | string \| null | null | Version identifier; changing it purges old data | | initial | T \| () => T | required | Initial state object or factory function | | selectors | object | {} | Methods for derived values (this = readonly state) | | actions | object | {} | Methods for mutations (this = mutable state) | | slices | { [key]: Slice } | {} | Object of slices created with createSlice() | | readyTimeout | number | 5000 | Max ms to wait for storage initialization | | validate | (state) => boolean | null | Validation function for state structure | | onReady | () => void | null | Called when initialization completes | | onError | (error) => void | null | Called on initialization failure | | onUpdateValidationFail | (state, origin, sliceKey?) => void | null | Called when storage or remote update fails validation |

Returned State Instance

Properties:

| Property | Type | Description | | ----------- | --------------------------- | ------------------------------------------------------------ | | state | object | Mutable proxy - read/write directly or via selectors/actions | | selectors | object | Bound selector methods (this = readonly state) | | actions | object | Bound action methods (this = mutable state) | | ready | Promise<void> | Resolves when persistence is loaded | | isReady | boolean | Whether initialization completed | | storage | "indexed-db" \| undefined | Used storage type or undefined if disabled |

Methods:

| Method | Description | | ----------------------- | ------------------------------------------------------------ | | useSnapshot() | React hook returning { state, selectors, actions } | | useSnapshot(sliceKey) | React hook scoped to a specific slice { state, selectors, actions } | | reset() | Reset entire state to initial values | | reset(sliceKey) | Reset specific slice to initial values |

createSlice(config)

Creates a modular slice of state with its own selectors and actions.

const todosSlice = createSlice({
  initial: { items: [], filter: 'all' },
  selectors: {
    filtered() {
      return this.filter === 'all' 
        ? this.items 
        : this.items.filter(t => t.status === this.filter);
    },
  },
  actions: {
    add(text: string) {
      this.items.push({ id: Date.now(), text, status: 'active' });
    },
  },
});

// Use in createState
const appState = createState({
  name: 'app',
  initial: {},
  slices: { todos: todosSlice },
});

// Access slice
appState.state.todos.items;
appState.actions.todos.add('Buy milk');
appState.selectors.todos.filtered();

Slice Config Options

| Option | Type | Default | Description | | ------------------------------ | -------------------- | ----------- | ------------------------------------------------ | | initial | T \| () => T | required | Initial slice state object or factory function | | selectors | object | {} | Slice-scoped selectors (this = slice state) | | actions | object | {} | Slice-scoped actions (this = slice state) | | validate | (state) => boolean | undefined | Slice-specific validation | | onUpdateValidationFail | (state, origin) => void | undefined | Called when slice storage or remote validation fails |

useSnapshot(state) / useSnapshot(state, sliceKey)

Standalone hook alternative to state.useSnapshot().

import { useSnapshot } from 'react-vibe-state';

function Component() {
  const { state, selectors, actions } = useSnapshot(appState);
  // or scoped to slice:
  const { state, selectors, actions } = useSnapshot(appState, 'todos');
}

Note on actions: Actions are included in useSnapshot() for convenience, even though semantically they don't operate on the snapshot. Actions always mutate the actual state (not the snapshot), and these mutations trigger reactivity updates across all subscribers.

Validation & Recovery

const appState = createState({
  name: 'app',
  initial: { version: 1, data: [] },
  
  validate: (state) => {
    return typeof state.version === 'number' && Array.isArray(state.data);
  },
  
  onUpdateValidationFail: (invalidData, origin) => {
    if (origin === 'storage') {
      console.warn('Stored data invalid', JSON.stringify(invalidData));
    }
    else {
      // Storage / Remote data incompatible - probably has newer schema
      location.reload();
    }
  },
});

Validation behavior:

• Initial state - if invalid then throws error (fix your code)
• Storage/remote updates - if invalid then calls onUpdateValidationFail & throws error (always, when validate is set)

Generation (Schema Versioning)

Useful for session-scoped page state. When your state schema changes incompatibly, change the generation to purge old data:

const appState = createState({
  name: 'app',
  generation: 'v2', // Changed from 'v1' - old data will be deleted
  initial: { /* new schema */ },
});

SSR / Server Components

State works in SSR environments - persistence and sync are automatically disabled server-side. The ready promise resolves immediately.

TypeScript

Full type inference for state, selectors, and actions:

interface User {
  id: string;
  name: string;
  role: 'admin' | 'user';
}

interface UsersState {
  list: User[];
  selectedId: string | null;
}

const usersSlice = createSlice({
  initial: { list: [], selectedId: null } as UsersState,
  selectors: {
    selected() {
      return this.list.find(u => u.id === this.selectedId);
    },         // ^? User | undefined
    admins() {
      return this.list.filter(u => u.role === 'admin');
    },         // ^? User[]
  },
  actions: {
    add(user: User) {
      this.list.push(user);
    },
    select(id: string | null) {
      this.selectedId = id;
    },
  },
});

interface AppState {
  theme: 'dark' | 'light';
}

const appState = createState({
  name: 'app',
  initial: { theme: 'dark' } as AppState,
  slices: { users: usersSlice },
});

// All types are inferred
appState.state.theme;                   // 'dark' | 'light'
appState.state.users.list;              // User[]
appState.selectors.users.selected();    // User | undefined
appState.actions.users.add(user);       // add requires (user: User) => void

Limitations

When persistence is enabled (persistAndSync: true), state is synced via Yjs CRDT which has some constraints:

• No undefined values - use null instead, or omit/delete the property
• No functions or class instances - state must be JSON-serializable (primitives, objects, arrays)
• Truncating arrays - use array.splice(index) or assign a new array instead of array.length = N

// Good
const slice = createSlice({
  initial: {
    selectedId: null,        // use null instead of undefined
    items: [],
    count: 0,
  },
  actions: {
    clearItems() {
      this.items.splice(0);  // use splice to clear
      // or: this.items = [];
    },
  },
});

// Bad - will throw error
const slice = createSlice({
  initial: {
    selectedId: undefined,   // undefined not allowed
    callback: () => {},      // functions not serializable
  },
  actions: {
    clearItems() {
      this.items.length = 0; // don't truncate via length
    },
  },
});

Browser Support

Requires IndexedDB and BroadcastChannel support. Works in all modern browsers. For older browsers without indexedDB.databases() API, an error is thrown - you can conditionally disable persistence:

createState({
  persistAndSync: typeof indexedDB?.databases === 'function',
  // ...
});

Demo App

Note: Demo app is only available in the GitHub repository, not in the npm package.

The test-server/ directory contains a demo application showcasing all library features:

• Counter - basic counter state
• Todos - array management with filtering
• Messages - real-time message sync
• Users - complex slice with selectors

# Install dependencies
npm install

# Run demo app
npm run dev

Open the app in multiple browser tabs to see cross-tab synchronization in action.

License

ISC