Data Fetching Architecture
Use for client APIs, SWR hooks, cache invalidation, async errors, useEffect migration, home first paint and persistent caches.
mkdir -p ~/.claude/skills/data-fetching-architecture && curl -fsSL 'https://raw.githubusercontent.com/lobehub/lobehub/canary/.agents/skills/data-fetching-architecture/SKILL.md' -o ~/.claude/skills/data-fetching-architecture/SKILL.md
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Data Fetching Architecture when an AI agent needs a reusable SKILL.md workflow for this job: Use for client APIs, SWR hooks, cache invalidation, async errors, useEffect migration, home first paint and persistent caches.
When not to use it
Skip Data Fetching Architecture when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/data-fetching-architecture && curl -fsSL 'https://raw.githubusercontent.com/lobehub/lobehub/canary/.agents/skills/data-fetching-architecture/SKILL.md' -o ~/.claude/skills/data-fetching-architecture/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/data-fetching-architecture/SKILL.md. For a shared project, commit the folder at .claude/skills/data-fetching-architecture/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Data Fetching Architecture skill for this task: Use Data Fetching Architecture when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
69/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 73/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 72/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# LobeHub Data Fetching Architecture
```text Component → Store useFetchXxx hook → replica slice → Service → lambdaClient ← sync flags + store data (selectors) ← response ```
New server data the UI paints goes through `local-replica` (`@/libs/replica`), not a new SWR key. `src/libs/swr/keys.ts` is frozen: `src/libs/swr/keys.frozen.test.ts` fails on any added key, and its legacy list only shrinks.
## Layer boundaries
- Services in `src/services/` own API calls: `.query()` for reads, `.mutate()` for writes. Export a service instance per domain; components and stores do not call `lambdaClient` directly. - Server lists and details go through `@/libs/replica`: the store's `useFetchXxx` returns `slice.useSync(params)` (flags only) and the engine writes the store. See the Replica section of [zustand](../zustand/SKILL.md). - `useClientDataSWR` + `onSuccess` syncing into the store is the legacy layout. Keep it only inside an existing hook whose key is already in `src/libs/swr/keys.ts`; do not add keys or new SWR-backed store hooks for server data. - Components call these hooks and read store data through selectors. Do not fetch in `useEffect` or duplicate server data in component `useState`. - Use `useFetchXxx` for read hooks and `refreshXxx` for cache invalidation. - For list/detail types, maps, reducers, and shared type sources, use [Zustand data structures](../zustand/references/data-structures.md). For store layout and action classes, use [zustand](../zustand/SKILL.md).
## Home First Paint and Persistent Caches
When changing home/sidebar first paint or persisted display data, read [`references/home-first-paint.md`](./references/home-first-paint.md). It covers avoiding flicker, reusing persistence, and the user `displaySnapshot.ts` boundary.
## Cache keys and refresh
Do not add SWR keys. A resource that needs a new key gets a replica instead (`defineReplica` / `definePagedReplica` in the store's `projection.ts`). The replica params replace the key, so include every parameter that changes the response: entity or parent id, filters, sort, and pagination. Refresh with `slice.fetch(params, { fresh: true })` or `revalidate()` from `useSync`; read and refresh must use the same params. Disable a sync whose required id is absent with `useSync(params, { enabled: false })`.
For example, inside an action class:
```typescript useFetchAgentLabels = (isLogin: boolean | undefined): ReplicaSyncResult => this.#labels.useSync(LIST_PARAMS, { enabled: isLogin === true });
refreshAgentLabels = async () => { await this.#labels.revalidate(); }; ```
Read the current [label action](../../../src/store/home/slices/label/action.ts) for store wiring. These links locate implementation; they do not make every existing call site a template to copy unchanged.
Legacy SWR hooks keep their existing key from `src/libs/swr/keys.ts` and import `useClientDataSWR` and `mutate` from `@/libs/swr`. When you migrate one to a replica, delete its key and its entry in `keys.frozen.test.ts`.
Hooks that share a known parent id can run together. If one request needs a value returned by another, keep it disabled until that value exists.
For lists cached separately under multiple parents, see [parent-keyed lists](references/walkthrough.md). Ordinary flat lists need no extra layer.
## Mutations
- Call the service, then refresh affected list/detail keys and any related domain whose response changed. Await refresh when subsequent UI behavior depends on it. - Keep pending flags in store state and clear them in `finally`. Use per-id state for row updates/deletes so unrelated rows remain usable; create can use a separate flag because no persistent id exists yet. - For optimistic writes on replica data, use `slice.optimistic` / `entity.optimistic`; a rejected call rolls back on its own, deletes included. - For optimistic create/update on legacy stores, use the store's reducer/dispatch convention and restore or revalidate affected state if the service fails. Do not leave a temporary row or a successful-looking edit after rejection. Delete only after server success there: a hand-written reducer has no rollback base. - Let failures reach the caller's error UI; a `finally` block clears pending state but does not by itself recover an optimistic write.
## Render loading, errors, and settled data
Success-only flags such as `isInit`, missing map entries, and `data ?? []` cannot distinguish an initial request failure from loading or empty results.
Use `AsyncBoundary` for standard loading/error/empty/data surfaces; use `AsyncError` for custom layouts and inline failures. `undefined` data means no successful result, whereas `[]` is a settled empty result.
Replica `useSync` returns no `data`. Feed `AsyncBoundary` its `error` and a settled signal from the store entry (`data={isListInit || undefined}`, where the selector is `entry !== undefined`); see `src/features/Pages/PageLayout/Body/index.tsx`. Legacy SWR hooks pass the original SWR `data` instead.
```tsx const BenchmarkList = () => { const { error, revalidate } = benchmarkActions.useFetchBenchmarks(); const isListInit = useEvalStore(benchmarkSelectors.isBenchmarkListInit); const benchmarks = useEvalStore(benchmarkSelectors.benchmarkList);
return ( <AsyncBoundary data={isListInit || undefined} empty={<EmptyState />} error={error} isEmpty={benchmarks.length === 0} isLoading={!isListInit && !error} onRetry={() => { void revalidate(); }} > <BenchmarkCards items={benchmarks} /> </AsyncBoundary> ); }; ```
The example's `EmptyState` and `BenchmarkCards` stand for the surface's existing renderers. Follow these distinctions when adapting it:
- Show first-load errors before empty / `NotFound` / zero-value defaults. Do not put an error branch after `if (!map[id]) return <Skeleton />`; failure may never fill the map. - Preserve settled content during background revalidation failures, including a successfully loaded empty list. A retry in flight should show pending feedback. - In a fetched + static list, use the fetched slice's request state before combining rows. Static rows must not hide a failed request. - For infinite scroll, keep a per-bucket `loadMoreError` and show an inline Retry row. Suspend observer-triggered retries while that error is unresolved. - A closed modal or absent id disables a request; it is not evidence of a missing record.
## Migrating an existing fetch
Move the API call into its service and the request into a replica-backed store hook. Reuse the existing action organization unless it needs to change for the task. Replace the component's effect/local fetch state with that hook and selectors, then connect `error`, retry, and pending feedback. Refresh the same replica params after writes.
Check initial failure, retry, settled-empty results, background failure, and switching ids against the surface being changed. For stale data, compare read/refresh params (or legacy keys) and the store bucket they update; for stuck loading, inspect rejected requests as well as success callbacks. Do not add a second fetch or another loading flag to mask the cause.
Intended uses
- Use Data Fetching Architecture when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.