# Valtio — Proxy-Based State Management for React

> Valtio makes React state management simple by wrapping plain JavaScript objects in a proxy, so components automatically re-render when the properties they read change — no reducers, actions, or boilerplate required.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

# Valtio — Proxy-Based State Management for React

## Quick Use
```bash
npm install valtio
```
```jsx
import { proxy, useSnapshot } from "valtio";
const state = proxy({ count: 0 });
function Counter() {
  const snap = useSnapshot(state);
  return <button onClick={() => ++state.count}>{snap.count}</button>;
}
```

## Introduction
React state management libraries often require boilerplate: action types, reducers, dispatchers, selectors. Valtio takes a different approach by leveraging JavaScript Proxy objects. You mutate state directly and Valtio tracks which properties each component reads, re-rendering only the affected components automatically.

## What Valtio Does
- Wraps plain JavaScript objects in a Proxy to track property access and mutations
- Re-renders only the React components that read the specific properties that changed
- Supports nested objects, arrays, Maps, and Sets with deep change tracking
- Provides snapshots that are immutable, enabling safe use with React concurrent features
- Works with vanilla JavaScript outside of React for framework-agnostic state management

## Architecture Overview
Valtio's proxy() function creates a deeply proxied version of your state object. Every property access through useSnapshot() is tracked, building a dependency graph between components and state paths. When you mutate the proxy directly (state.count++), Valtio detects the change, creates an immutable snapshot of the current state, and triggers re-renders only for components whose tracked properties were affected. The snapshot is created using structural sharing, so unchanged portions of the state tree are reused. This proxy-based reactivity model means there is no need for selectors, memoization, or manual subscription management.

## Self-Hosting & Configuration
- Install valtio from npm: npm install valtio
- Create a proxy state object in a module: export const state = proxy({ ... })
- Use useSnapshot(state) in React components to subscribe to changes
- Mutate the proxy directly from event handlers or side effects
- Use derive() for computed values that update automatically when dependencies change

## Key Features
- No boilerplate: mutate state directly instead of dispatching actions or writing reducers
- Automatic render optimization re-renders only components reading changed properties
- Immutable snapshots are safe for React concurrent mode and StrictMode
- Framework-agnostic core works with vanilla JS, React, and other UI libraries
- DevTools integration via valtio/utils for state inspection and time-travel debugging

## Comparison with Similar Tools
- **Zustand** — Minimal hook-based store; Valtio is even simpler with direct mutation instead of set functions
- **Redux Toolkit** — Feature-rich but requires slices, reducers, and selectors; Valtio eliminates all of that
- **Jotai** — Atomic state management; Valtio uses a single mutable proxy instead of individual atoms
- **MobX** — Also proxy-based but heavier with decorators and computed; Valtio is more minimal
- **Recoil** — Graph-based atoms by Meta; Valtio avoids the atom/selector model entirely

## FAQ
**Q: Is it safe to mutate state directly in React?**
A: Yes. Valtio intercepts mutations through the proxy and produces immutable snapshots for React to consume, so React never sees mutable state.

**Q: How does Valtio compare to Zustand in performance?**
A: Both are fast. Valtio can be more granular because it tracks property-level access, while Zustand re-renders based on selector equality checks.

**Q: Can I use Valtio with Next.js or server-side rendering?**
A: Yes. Valtio works with SSR. Use the snapshot for server rendering and hydrate the proxy on the client.

**Q: Does Valtio support TypeScript?**
A: Yes. Valtio is written in TypeScript and the proxy preserves your state types without additional type annotations.

## Sources
- https://github.com/pmndrs/valtio
- https://valtio.pmnd.rs/

---
Source: https://tokrepo.com/en/workflows/valtio-proxy-based-state-management-react-629ef06d
Author: Script Depot