# Client Data Fetching

Guides client API hooks, cache invalidation, async errors and persistent caches.

- Repository: https://github.com/lobehub/lobehub (83676 stars)
- Category: Engineering
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add lobehub/lobehub --skill data-fetching-architecture -g -a claude-code -y`
Codex: `npx skills add lobehub/lobehub --skill data-fetching-architecture -g -a codex -y`
Cursor: `npx skills add lobehub/lobehub --skill data-fetching-architecture -g -a cursor -y`
Gemini CLI: `npx skills add lobehub/lobehub --skill data-fetching-architecture -g -a gemini-cli -y`

## Description

Use for client APIs, SWR hooks, cache invalidation, async errors, useEffect migration, home first paint and persistent caches.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# LobeHub Data Fetching Architecture

```text
Component → Store useFetchXxx hook → Service → lambdaClient
          ← SWR request state + store data ← response
```

## 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.
- Store read hooks use `useClientDataSWR` and return its SWR response, including `error`
  and `mutate`. Sync successful results into the store through the wrapper's supported
  callback (`onSuccess`, or `onData` for the sync wrapper).
- Server lists and details that paint from a local copy go through `@/libs/replica`
  instead: 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).
- 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

Reuse the domain key factory in `src/libs/swr/keys.ts`; define a shared key if the
domain has none. Include every parameter that changes the response: entity or parent
id, filters, sort, and pagination. Read and refresh must construct the same key.

The rest: https://github.com/lobehub/lobehub/blob/HEAD/.agents/skills/data-fetching-architecture/SKILL.md