Beyond Selectors: Engineering Fine-Grained Reactivity with Proxy-Driven State

import { proxy } from 'valtio';

interface TaskBoardState {
  activeFilter: 'all' | 'active' | 'completed';
  tasks: Array<{ id: string; title: string; done: boolean }>;
  isLoading: boolean;
}

const boardState = proxy<TaskBoardState>({
  activeFilter: 'all',
  tasks: [],
  isLoading: false,
});

re required.

export function toggleTask(taskId: string) {
  const target = boardState.tasks.find(t => t.id === taskId);
  if (target) {
    target.done = !target.done;
  }
}

export function setFilter(newFilter: TaskBoardState['activeFilter']) {
  boardState.activeFilter = newFilter;
}

Step 3: Consume via Snapshot in Components Components read from useSnapshot, which automatically tracks dependencies and triggers granular re-renders.

import { useSnapshot } from 'valtio';
import { toggleTask, setFilter } from './boardStore';

export function TaskList() {
  const snap = useSnapshot(boardState);

  const visibleTasks = snap.tasks.filter(task => {
    if (snap.activeFilter === 'active') return !task.done;
    if (snap.activeFilter === 'completed') return task.done;
    return true;
  });

  return (
    <div>
      <select
        value={snap.activeFilter}
        onChange={e => setFilter(e.target.value as TaskBoardState['activeFilter'])}
      >
        <option value="all">All</option>
        <option value="active">Active</option>
        <option value="completed">Completed</option>
      </select>

      <ul>
        {visibleTasks.map(task => (
          <li key={task.id}>
            <label>
              <input
                type="checkbox"
                checked={task.done}
                onChange={() => toggleTask(task.id)}
              />
              {task.title}
            </label>
          </li>
        ))}
      </ul>
    </div>
  );
}

Why this works: The proxy engine intercepts snap.activeFilter and snap.tasks during render. When toggleTask or setFilter mutates the underlying proxy, the engine compares the new values against the snapshot. Only components that accessed the mutated properties re-render. Selector boilerplate, dependency arrays, and manual memoization become unnecessary. The architecture scales naturally because reactivity is bound to data access patterns, not explicit subscription topology.

Pitfall Guide

Proxy-based reactivity removes orchestration overhead, but it introduces new failure modes if developers treat it like a traditional store. Understanding these pitfalls prevents performance degradation and rendering inconsistencies.

1. Capturing Snapshots in Long-Running Closures

Explanation: useSnapshot returns a frozen object representing state at a specific render cycle. Storing this snapshot in setTimeout, setInterval, or background workers locks the reference to stale data. Fix: Use snapshots exclusively for rendering. Access the raw boardState proxy directly for mutations, async operations, or long-running callbacks. Snapshots are read-only views; proxies are the source of truth.

2. Mutating Proxies Outside Event Boundaries

Explanation: Triggering proxy mutations during render, inside useEffect cleanup functions, or in uncontrolled async flows can cause missed updates or inconsistent snapshot generation. Fix: Confine mutations to explicit triggers: user events, resolved promises, or scheduled callbacks. If you must mutate during an effect, wrap it in useLayoutEffect or batch it with React's startTransition to align with the rendering cycle.

3. Wrapping Immutable Configuration in Proxies

Explanation: Applying proxy() to static configuration, constants, or large read-only datasets adds unnecessary trap overhead. The engine will track accesses that never change, wasting CPU cycles and memory. Fix: Reserve proxies for frequently accessed or updated UI state. Use plain objects, Object.freeze(), or module-level constants for static data. Only wrap domains that require reactive observation.

4. Computing Derived Values Without Memoization

Explanation: Calculating derived state directly inside the render function without caching causes redundant computations on every parent update, leading to render thrashing. Fix: Use useMemo for synchronous derivations that depend on multiple snapshot properties. For expensive cross-property calculations, leverage Valtio's subscribeKey or external computed utilities to cache results and trigger updates only when source properties change.

5. Mixing Legacy Subscription Patterns with Proxy State

Explanation: Combining useEffect subscription loops, manual addEventListener state tracking, or third-party store integrations with proxy state creates conflicting update paths. This often results in tearing or double-renders. Fix: Rely exclusively on useSnapshot for state consumption. If you must integrate external systems, bridge them through a single mutation function that updates the proxy, rather than subscribing to both systems independently.

6. Deeply Nested Mutations Without Structural Awareness

Explanation: Mutating deeply nested properties triggers proxy traps at every level. While the engine handles this correctly, excessive nesting can degrade performance in high-frequency update scenarios. Fix: Flatten state structures where possible. Group related properties into shallow objects. If deep nesting is unavoidable, isolate frequently mutated branches into separate proxy instances to limit trap traversal depth.

7. Ignoring Batched Updates in High-Frequency Scenarios

Explanation: Rapid successive mutations (e.g., drag-and-drop, scroll tracking, WebSocket streams) can trigger multiple snapshot generations before React batches them, causing layout thrashing. Fix: Wrap high-frequency mutations in React.startTransition or requestAnimationFrame. This defers non-urgent updates, allowing React to batch snapshot generations and maintain 60fps rendering.

Production Bundle

Action Checklist

• Audit state domains: Identify which modules require reactive observation versus static configuration.
• Replace selector chains: Migrate useSelector or custom memoized selectors to direct useSnapshot property access.
• Isolate mutation boundaries: Ensure all proxy updates occur in event handlers, async callbacks, or explicit action functions.
• Flatten nested structures: Refactor deeply nested state objects into shallow, domain-specific proxies.
• Implement derived state caching: Wrap expensive calculations in useMemo or external computed utilities.
• Validate concurrent safety: Confirm all components use useSnapshot and avoid manual useEffect subscription loops.
• Profile trap overhead: Use React DevTools Profiler and proxy monitoring to identify unnecessary property accesses.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
High-frequency UI updates (drag, scroll, live charts)	Proxy-based (Valtio)	Automatic granular tracking eliminates manual memoization overhead	Low bundle, high render efficiency
Complex async workflows with side effects	Traditional store + middleware	Explicit action/reducer chains provide predictable side-effect orchestration	Higher bundle, moderate cognitive load
Static configuration or theme data	Plain objects / Context	No reactivity required; proxy traps add unnecessary overhead	Minimal bundle, zero trap cost
Cross-tab synchronization / WebSocket streams	Proxy with subscribeKey	Direct property observation aligns with real-time data ingestion	Low latency, efficient memory usage
Large-scale enterprise apps with strict audit trails	Traditional store with devtools	Explicit action logging and time-travel debugging require event history	Higher maintenance, strong traceability

Configuration Template

Production-ready store factory with TypeScript enforcement, snapshot derivation, and performance monitoring hooks.

import { proxy, subscribe } from 'valtio';
import { useSnapshot } from 'valtio/react';
import { useMemo } from 'react';

// Domain interface
export interface AnalyticsState {
  metrics: Record<string, number>;
  timeframe: '1h' | '24h' | '7d';
  isStreaming: boolean;
}

// Factory function for isolated proxy instances
export function createAnalyticsStore(initial: AnalyticsState) {
  const store = proxy<AnalyticsState>(initial);

  // Subscribe to specific key changes for external integrations
  const unsubscribe = subscribe(store, () => {
    if (process.env.NODE_ENV === 'development') {
      console.log('[Store Update]', store.timeframe, store.isStreaming);
    }
  });

  return { store, unsubscribe };
}

// Custom hook for memoized derived state
export function useAnalyticsDerived(store: ReturnType<typeof createAnalyticsStore>['store']) {
  const snap = useSnapshot(store);

  const aggregated = useMemo(() => {
    return Object.values(snap.metrics).reduce((sum, val) => sum + val, 0);
  }, [snap.metrics]);

  return { ...snap, aggregated };
}

Quick Start Guide

1. Install the library: Run npm install valtio or yarn add valtio. No peer dependencies required.
2. Initialize your first proxy: Wrap your initial state object with proxy() and export it as a module-level singleton or factory instance.
3. Consume in components: Import useSnapshot from valtio/react, pass your proxy, and read properties directly. Mutate the raw proxy in event handlers.
4. Add TypeScript interfaces: Define strict interfaces for your state domain to enforce type safety across mutations and snapshots.
5. Profile and iterate: Open React DevTools Profiler, trigger state changes, and verify that only components accessing mutated properties re-render. Adjust nesting or memoization as needed.