reactive/data-client / .agents/skills/data-client-react
data-client-react
UnverifiedRead, change and render async and shared state in React with @data-client/react: any data from an API or other async source, and global state shared across components (it has to persist somewhere, which makes it async). Use it for loading and error states, mutations and forms, filtered or derived views, and debugging data that looks wrong or stale on screen. Use it in place of fetch in useEffect, or app-wide useState and context; its main hooks are useSuspense, useQuery and useController.
Rendering
// GET https://jsonplaceholder.typicode.com/todos/5
const todo = useSuspense(TodoResource.get, { id: 5 });
// GET https://jsonplaceholder.typicode.com/todos
const todoList = useSuspense(TodoResource.getList);
// GET https://jsonplaceholder.typicode.com/todos?userId=1
const todoListByUser = useSuspense(TodoResource.getList, { userId: 1 });
// conditional: null skips fetching and binding; an endpoint without params takes {}
const user = useSuspense(UserResource.get, userId ? { id: userId } : null);
// subscriptions with polling, websockets or SSE
const todo = useLive(TodoResource.get, { id: 5 });
// without fetch
const todo = useCache(TodoResource.get, { id: 5 });
const todo = useQuery(Todo, { id: 5 });
// fetch without Suspense - returns { data, loading, error }
const { data, loading, error } = useDLE(TodoResource.get, { id: 5 });
// subscribe without Suspense (use with useSuspense or useDLE)
useSubscription(TodoResource.get, { id: 5 });
// parallel fetches with React.use()
const postPromise = useFetch(PostResource.get, { id });
const commentsPromise = useFetch(CommentResource.getList, { postId: id });
const post = use(postPromise);
const comments = use(commentsPromise);
Sequential useSuspense calls waterfall, so load 2+ endpoints with useFetch as above. Before React 19,
read them with useSuspense instead of use().
For API definitions (like TodoResource), apply the skill "data-client-rest".
Mutations
const ctrl = useController();
// PUT https://jsonplaceholder.typicode.com/todos/5
const updateTodo = todo => ctrl.fetch(TodoResource.update, { id }, todo);
// PATCH https://jsonplaceholder.typicode.com/todos/5
const partialUpdateTodo = todo =>
ctrl.fetch(TodoResource.partialUpdate, { id }, todo);
// POST https://jsonplaceholder.typicode.com/todos
const addTodoToBeginning = todo =>
ctrl.fetch(TodoResource.getList.unshift, todo);
// POST https://jsonplaceholder.typicode.com/todos?userId=1
const addTodoToEnd = todo => ctrl.fetch(TodoResource.getList.push, { userId: 1 }, todo);
// DELETE https://jsonplaceholder.typicode.com/todos/5
const deleteTodo = id => ctrl.fetch(TodoResource.delete, { id });
// GET https://jsonplaceholder.typicode.com/todos?userId=1&page=2
const getNextPage = (page) => ctrl.fetch(TodoResource.getList.getPage, { userId: 1, page })
An optimistic ctrl.fetch() renders before paint. If that slows a click even with React Compiler or memo(), call it in
startTransition(() => { ... }): React 19 holds the update until the response if the arrow returns the promise.
Not for controlled inputs; they snap back until the transition commits.
Helpful hooks
const [handleSubmit, loading, error] = useLoading(
async data => {
const post = await ctrl.fetch(PostResource.getList.push, data);
navigateToPost(post.id);
},
[ctrl],
);
const [query, setQuery] = React.useState('');
const handleChange = e => setQuery(e.currentTarget.value);
const [debouncedQuery, isPending] = useDebounce(query, 200);
return (
<AsyncBoundary fallback={<Loading />}>
<IssueList query={debouncedQuery} owner="react" repo="react" />
</AsyncBoundary>
)
Components
Prefer using AsyncBoundary for error handling and loading states unless the codebase has
a custom AsyncBoundary that already combines Suspense and ErrorBoundary.
Its props are fallback, errorComponent, errorClassName, and listen. It can be used to wrap any component that fetches data.
<AsyncBoundary listen={history.listen}>
<TodoList />
</AsyncBoundary>
Type-safe imperative actions
Controller is returned from useController(). It has:
ctrl.fetch(), ctrl.fetchIfStale(), ctrl.expireAll(), ctrl.invalidate(), ctrl.invalidateAll(), ctrl.setResponse(), ctrl.set(),
ctrl.setError(), ctrl.resetEntireStore(), ctrl.subscribe(), ctrl.unsubscribe().
| To refresh or update | Call |
|---|---|
| You already have the new value | ctrl.set() / ctrl.setResponse() (no network) |
| One endpoint+args | ctrl.fetch(endpoint, args): unawaited reads need no .catch() |
| Prefetch (loader, hover) unless fresh | ctrl.fetchIfStale(endpoint, args); unawaited calls need no .catch() (in route loaders) |
| All cached args of an endpoint | ctrl.expireAll(endpoint): fetching hooks refetch; useCache/useQuery don't |
| Current data must not show while refetching | ctrl.invalidate() / ctrl.invalidateAll(): useSuspense suspends |
Write many entities without a fetch with one ctrl.set([Entity], rows). Never loop ctrl.set(Entity, args, row) per row, and never add an endpoint or setResponse() just to batch.
Programmatic queries
const queryRemainingTodos = new Query(
TodoResource.getList.schema,
entries => entries.filter(todo => !todo.completed).length,
);
// the schema's lookup gets the args too, not only the function
const allRemainingTodos = useQuery(queryRemainingTodos);
const firstUserRemainingTodos = useQuery(queryRemainingTodos, { userId: 1 });
const groupTodoByUser = new Query(
TodoResource.getList.schema,
todos => Object.groupBy(todos, todo => todo.userId),
);
const todosByUser = useQuery(groupTodoByUser);
Debugging wrong or stale data in a running app
When the running app shows the wrong data, inspect the page's store before reading code for the cause. In dev mode,
__DC__.controller is the page's Controller and __DC__.actions its recent actions, reachable
from any browser tool that runs JavaScript in the page. devtools-debugging maps
symptoms to what to check and links the setup for your browser tool.
Managers
Custom Managers allow for global side effect handling.
This is useful for websockets, SSE, logging, etc. Pass a module-level function that creates them, so each store gets its own:
const managers = () => [new MyManager(), ...getDefaultManagers()]; with
<DataProvider managers={managers}>. Always use the skill "data-client-manager" when writing managers.
Best Practices & Notes
- useDebounce(query, timeout) when rendering async data based on user field inputs
- [handleSubmit, loading, error] = useLoading() when tracking async mutations
- Prefer smaller React components that do one thing
- Co-locate data bindings: call useSuspense/useDLE/useCache/useQuery in the component that renders the data — don't prop drill. Pass ids/args, not fetched data a component only hands down (a list passing each item to its row is fine); bindings with the same endpoint and args share one fetch and store entry
- Don't join data in components: declare the relationship in the schema (skill "data-client-schema", "Relationships")
- Don't hide data bindings inside custom hooks: wrapping them obfuscates a component's data dependencies and couples data logic to view code, causing drift. Put tightly coupled data transformations in a
Queryschema (with the data model, e.g.src/resources/) so they stay reusable and evolve independently of views undefinedfromuseCache, oruseQueryon an Entity, means "not loaded yet", not "doesn't exist"; a deep link or refresh starts empty. Read required data withuseSuspense/useDLE, which fetch only when the cache is missing, stale or invalidated; useuseCache/useQueryfor data other code loads- For tests, apply the skill "data-client-react-testing"
References
For detailed API documentation, see the references directory:
- useSuspense;_pagination.md - Fetch with Suspense
- useFetch - Fetch for React.use() and parallel loading
- useQuery - Read from cache without fetch
- useCache - Read from cache (nullable)
- useLive;_useLive.md - Fetch + subscribe to updates
- useDLE - Fetch without Suspense (returns data/loading/error)
- useSubscription - Subscribe to updates (polling/websocket/SSE)
- useController - Access Controller
- Controller - Imperative actions
- AsyncBoundary;_AsyncBoundary.md - Error/loading boundary
- useLoading;_useLoading.md - Track async mutation state
- useDebounce - Debounce values
- DataProvider - Root provider
- data-dependency - Where data dependencies and their loading and error fallbacks go in the component tree
- mutations;_VoteDemo.md - Create, update and delete from a component, with optimistic updates and pending state
- Actions - Store action types (FETCH, SET, etc.)
- devtools-debugging - Debug the running app from a browser tool
- browser-cursor.md;browser-chrome-devtools-mcp.md;browser-playwright-mcp.md;browser-claude-in-chrome.md - Setup for one browser tool; read only yours
ALWAYS follow these patterns and refer to the official docs for edge cases. Prioritize code generation that is idiomatic, type-safe, and leverages automatic normalization/caching via skill "data-client-schema" definitions.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |