@legendapp/state

legend-state

weekly downloads42K

versionv2.1.15

licenseMIT

categorystate

reactreact-nativestatehooksproxy

Overview

@legendapp/state is a modern state management library built for JavaScript applications, with first-class React support. It uses proxy-based observables to provide fine-grained reactivity where components re-render only when their specific data changes, not when unrelated parts of the state tree update. This approach eliminates the need for selectors, memoization boilerplate, or manual dependency tracking.

The library was created to solve performance bottlenecks in complex React applications while drastically reducing code verbosity. Unlike traditional state managers that require actions, reducers, or context providers, Legend-State lets you directly mutate observable objects with automatic tracking. At just 4kb gzipped, it includes batteries-included features like local persistence (LocalStorage, IndexedDB, MMKV) and remote synchronization (REST APIs, Firebase, TanStack Query) without additional plugins.

Developers building data-intensive applications, offline-first mobile apps, or real-time collaborative tools adopt Legend-State for its sync engine capabilities. The library handles optimistic updates, conflict resolution, differential syncing, and automatic retries out of the box. It's particularly popular in React Native projects where bundle size and render performance are critical. The TypeScript-first design provides complete type inference across nested observable structures.

Version 2.1.15 represents a mature implementation with stable APIs for both simple local state and complex distributed systems. The library works seamlessly with React Server Components and the new React Compiler, making it future-proof for modern React architectures.

Quick Start

typescript

import { observable } from '@legendapp/state';
import { observer, useSelector } from '@legendapp/state/react';
import { ObservablePersistLocalStorage } from '@legendapp/state/persist-plugins/local-storage';
import { syncedFetch } from '@legendapp/state/sync-plugins/fetch';

// Create observable with automatic persistence and API sync
const todos$ = observable(
  syncedFetch({
    get: 'https://jsonplaceholder.typicode.com/todos',
    set: async ({ value }) => {
      await fetch('https://jsonplaceholder.typicode.com/todos', {
        method: 'POST',
        body: JSON.stringify(value),
        headers: { 'Content-Type': 'application/json' }
      });
    },
    persist: {
      plugin: ObservablePersistLocalStorage,
      name: 'todos'
    }
  })
);

// Observer component re-renders only when its specific todo changes
const TodoItem = observer(({ id }) => {
  const todo = todos$[id];
  
  return (
    <div>
      <input
        type="checkbox"
        checked={todo.completed.get()}
        onChange={(e) => todo.completed.set(e.target.checked)}
      />
      <input
        value={todo.title.get()}
        onChange={(e) => todo.title.set(e.target.value)}
      />
    </div>

  );
});

// Hook-based approach with selector for computed values
function TodoStats() {
  const completed = useSelector(() => 
    Object.values(todos$.get()).filter(t => t.completed).length
  );
  
  return <span>Completed: {completed}</span>;
}

// Direct mutations sync automatically to localStorage and API
function addTodo(title) {
  const newId = Date.now();
  todos$[newId].set({
    id: newId,
    title,
    completed: false
  });
}

Use Cases

Offline-first mobile applications: Use the built-in persistence and sync plugins to create React Native apps that work without connectivity. Changes are queued locally in MMKV storage, then automatically synced to your backend when connection restores, with conflict resolution and retry logic included.

Real-time collaborative editing: Build document editors or collaborative whiteboards where multiple users' changes need to sync. The observable system tracks granular changes (which specific fields changed), enabling efficient delta updates instead of full document replacement.

Complex form state with auto-save: Manage deeply nested form data with computed validations that only recalculate affected fields. Persist drafts to localStorage automatically and sync final submissions to REST APIs, all with a few configuration lines instead of custom debouncing and error handling.

Dashboard applications with live data: Create admin panels or analytics dashboards that fetch from multiple endpoints. Observables can integrate with TanStack Query for server state while maintaining local UI state, with automatic re-fetching and optimistic updates when users edit data.

Shopping carts with persistence: Implement cart state that survives page refreshes and syncs across devices. The library handles serialization, storage in IndexedDB, and merging cart data when users log in, without writing custom synchronization code.

Pros & Cons

Pros

+Extreme performance through fine-grained reactivity—components only re-render when their exact data dependencies change, not the entire subtree
+Built-in persistence and remote sync eliminate thousands of lines of boilerplate for offline-first apps, with conflict resolution and retry logic included
+Tiny bundle size at 4kb with zero dependencies, yet includes features that require multiple libraries in other ecosystems
+Direct mutation syntax with full TypeScript inference—no need to learn action creators, reducers, or selector patterns
+Works with React Compiler and Server Components, making it compatible with cutting-edge React features without refactoring

Cons

−Smaller ecosystem compared to Redux or Zustand—fewer community plugins, third-party integrations, and Stack Overflow answers available
−Proxy-based implementation may have debugging challenges in certain environments, and not all developer tools fully support observable inspection
−Learning curve for developers accustomed to immutable update patterns—the direct mutation approach feels unfamiliar coming from Redux or Immer
−Documentation assumes intermediate React knowledge, with fewer beginner-friendly tutorials compared to more established libraries
−Less opinionated architecture can lead to inconsistent patterns across large teams without established conventions

Alternatives

jotaiv2.17.1

👻 Primitive and flexible state management for React

statereactstate

2.6M / week

reduxv5.0.1

Predictable state container for JavaScript apps

statereduxreducer

20.8M / week

@tanstack/react-queryv5.90.21

Hooks for managing, caching and syncing asynchronous and remote data in React

data-fetching

16.7M / week

valtiov2.3.0

🧙 Valtio makes proxy-state simple for React and Vanilla

statereactstate

1.1M / week

zustandv5.0.11

🐻 Bear necessities for state management in React

statereactstate

20.2M / week

Install

bash

npm install @legendapp/state

bash

pnpm add @legendapp/state

bash

bun add @legendapp/state

Overview

Quick Start

typescript

import { observable } from '@legendapp/state';
import { observer, useSelector } from '@legendapp/state/react';
import { ObservablePersistLocalStorage } from '@legendapp/state/persist-plugins/local-storage';
import { syncedFetch } from '@legendapp/state/sync-plugins/fetch';

// Create observable with automatic persistence and API sync
const todos$ = observable(
  syncedFetch({
    get: 'https://jsonplaceholder.typicode.com/todos',
    set: async ({ value }) => {
      await fetch('https://jsonplaceholder.typicode.com/todos', {
        method: 'POST',
        body: JSON.stringify(value),
        headers: { 'Content-Type': 'application/json' }
      });
    },
    persist: {
      plugin: ObservablePersistLocalStorage,
      name: 'todos'
    }
  })
);

// Observer component re-renders only when its specific todo changes
const TodoItem = observer(({ id }) => {
  const todo = todos$[id];
  
  return (
    <div>
      <input
        type="checkbox"
        checked={todo.completed.get()}
        onChange={(e) => todo.completed.set(e.target.checked)}
      />
      <input
        value={todo.title.get()}
        onChange={(e) => todo.title.set(e.target.value)}
      />
    </div>

  );
});

// Hook-based approach with selector for computed values
function TodoStats() {
  const completed = useSelector(() => 
    Object.values(todos$.get()).filter(t => t.completed).length
  );
  
  return <span>Completed: {completed}</span>;
}

// Direct mutations sync automatically to localStorage and API
function addTodo(title) {
  const newId = Date.now();
  todos$[newId].set({
    id: newId,
    title,
    completed: false
  });
}

Use Cases

Pros & Cons

Pros

+Extreme performance through fine-grained reactivity—components only re-render when their exact data dependencies change, not the entire subtree
+Built-in persistence and remote sync eliminate thousands of lines of boilerplate for offline-first apps, with conflict resolution and retry logic included
+Tiny bundle size at 4kb with zero dependencies, yet includes features that require multiple libraries in other ecosystems
+Direct mutation syntax with full TypeScript inference—no need to learn action creators, reducers, or selector patterns
+Works with React Compiler and Server Components, making it compatible with cutting-edge React features without refactoring

Cons

−Smaller ecosystem compared to Redux or Zustand—fewer community plugins, third-party integrations, and Stack Overflow answers available
−Proxy-based implementation may have debugging challenges in certain environments, and not all developer tools fully support observable inspection
−Learning curve for developers accustomed to immutable update patterns—the direct mutation approach feels unfamiliar coming from Redux or Immer
−Documentation assumes intermediate React knowledge, with fewer beginner-friendly tutorials compared to more established libraries
−Less opinionated architecture can lead to inconsistent patterns across large teams without established conventions