# React Synapse
> A React state management library using Preact Signals with fine-grained reactivity. Use it when you need global state without providers, minimal re-renders, or immutable updates via draft mutations. Works with React 18+.
- Skill: `diegosouzapw/react-synapse` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/react-synapse`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/react-synapse/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: ISC
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/diegosouzapw/react-synapse
---
## Overview
React-synapse provides fine-grained reactive state management for React using Preact Signals. It offers a global singleton store pattern that requires no providers, supports draft mutations via Mutative, and minimizes re-renders by tracking only accessed values.
## When to use
- Building React applications needing global state without Context/Providers
- Fine-grained reactivity where components re-render only when accessed values change
- Complex nested state updates requiring immutable patterns with mutable syntax
- Sharing state between components without prop drilling
## Core API patterns
### String key access: `[value, setter]`
Use when you need both the value and a setter function for updates.
```jsx
import { createSignalStore } from 'react-synapse';
const { useStore } = createSignalStore({ count: 0, user: null });
function Counter() {
const [count, setCount] = useStore('count');
return (
);
}
```
### Selector for derived state: `value`
Use when you only need to read values, especially computed/derived values.
```jsx
function CartSummary() {
const total = useStore(s => s.items.reduce((sum, item) => sum + item.price, 0));
const itemCount = useStore(s => s.items.length);
return
{itemCount} items - ${total}
;
}
```
### Draft mutations for updates
Use draft mutations for nested object/array updates. Mutative handles immutability internally.
```jsx
function UserProfile() {
const [user, setUser] = useStore('user');
const updateName = (name) => {
setUser(draft => {
draft.profile.name = name;
});
};
const addTodo = (text) => {
setUser(draft => {
draft.todos.push({ id: Date.now(), text, completed: false });
});
};
return (
updateName(e.target.value)}
/>
);
}
```
## Rules
### ✅ DO
- **Use string keys for local component state**
```jsx
const [count, setCount] = useStore('count');
```
- **Use selector functions for read-only/derived values**
```jsx
const total = useStore(s => s.price * s.qty);
```
- **Use draft mutations for nested updates**
```jsx
setUser(draft => { draft.name = 'Jane'; });
```
- **Create store at module level (not in components)**
```javascript
// store.js - create once at module level
export const { useStore } = createSignalStore({ ... });
```
- **Clear store between tests**
```javascript
import { globalStore } from 'react-synapse';
beforeEach(() => globalStore.clearStore());
```
### ❌ DON'T
- **Don't use React Context or Providers** - not needed with react-synapse
- **Don't destructure the store object** - loses reactivity
```jsx
const [store] = useStore('store');
const { user } = store; // ❌ Loses reactivity
```
- **Don't call useStore without arguments** - throws error
```jsx
const state = useStore(); // ❌ Error
```
- **Don't mutate state directly** - always use setters
```jsx
const [user, setUser] = useStore('user');
user.name = 'Jane'; // ❌ Direct mutation
```
- **Don't create stores inside components** - creates new store on each render
## Examples
### Example 1: Todo List with Filter
```jsx
// store.js
import { createSignalStore } from 'react-synapse';
export const { useStore } = createSignalStore({
todos: [],
filter: 'all' // 'all' | 'active' | 'completed'
});
// TodoList.jsx
import { useStore } from './store';
function TodoList() {
const [todos, setTodos] = useStore('todos');
const [filter, setFilter] = useStore('filter');
const addTodo = (text) => {
setTodos(draft => {
draft.push({ id: Date.now(), text, completed: false });
});
};
const toggleTodo = (id) => {
setTodos(draft => {
const todo = draft.find(t => t.id === id);
if (todo) todo.completed = !todo.completed;
});
};
const filtered = todos.filter(t => {
if (filter === 'active') return !t.completed;
if (filter === 'completed') return t.completed;
return true;
});
return (