reactive/data-client / .agents/skills/data-client-setup
data-client-setup
VerifiedInstall and set up @data-client/react or @data-client/vue in a project. Detects project type (NextJS, Expo, React Native, Vue, plain React) and protocol (REST, GraphQL, custom), then follows the bundled protocol-specific setup guide.
SKILL.md
View on GitHub---
name: data-client-setup
description: Install and set up @data-client/react or @data-client/vue in a project. Detects project type (NextJS, Expo, React Native, Vue, plain React) and protocol (REST, GraphQL, custom), then follows the bundled protocol-specific setup guide.
disable-model-invocation: true
---
# Setup Reactive Data Client
Before installing anything, tell the user which packages and skills you'll add. A request to add or set up Data Client
is the go-ahead; otherwise wait for theirs.
## Detection Steps
Before installing, detect the project type and protocol by checking these files:
### 1. Detect Package Manager
Check which lock file exists:
- `yarn.lock` → use `yarn add`
- `pnpm-lock.yaml` → use `pnpm add`
- `package-lock.json` or `bun.lockb` → use `npm install` or `bun add`
### 2. Detect Project Type
Check `package.json` dependencies:
| Check | Project Type |
|-------|--------------|
| `"next"` in dependencies | **NextJS** |
| `"expo"` in dependencies | **Expo** |
| `"vue"` in dependencies | **Vue** |
| `"react-native"` in dependencies (no expo) | **React Native** |
| `"react"` in dependencies | **Plain React** |
### 3. Detect Protocol Type
Scan the codebase to determine which data-fetching protocols are used:
#### REST Detection
Look for these patterns:
- `fetch()` calls with REST-style URLs (`/api/`, `/users/`, etc.)
- HTTP client libraries: `axios`, `ky`, `got`, `superagent` in `package.json`
- Files with REST patterns: `api.ts`, `client.ts`, `services/*.ts`
- URL patterns with path parameters: `/users/:id`, `/posts/:postId/comments`
- HTTP methods in code: `method: 'GET'`, `method: 'POST'`, `.get(`, `.post(`
#### GraphQL Detection
Look for these patterns:
- `@apollo/client`, `graphql-request`, `urql`, `graphql-tag` in `package.json`
- `.graphql` or `.gql` files in the project
- `gql\`` template literal tags
- GraphQL query patterns: `query {`, `mutation {`, `subscription {`
- GraphQL endpoint URLs: `/graphql`
#### Custom Protocol Detection
For async operations that don't match REST or GraphQL:
- Custom async functions returning Promises
- Third-party SDK clients (Firebase, Supabase, AWS SDK, etc.)
- IndexedDB or other local async storage
### 4. Detect a Data-Fetching Library
| Check `package.json` | Then |
|----------------------|------|
| `@tanstack/react-query` or `react-query` (React) | After setup, migrate per [Replacing TanStack Query](#replacing-tanstack-query) |
### 5. Install the Skills This Project Needs
Protocol setup guides are bundled in this skill, but defining and using data afterwards is covered by other Data Client skills. Install the ones that match what you detected, skipping any already installed:
| Detected | Skills |
|----------|--------|
| Always | `data-client-schema`, `data-client-manager` |
| React (NextJS, Expo, React Native, plain React) | `data-client-react`, `data-client-react-testing`, `data-client-performance` |
| Vue | `data-client-vue`, `data-client-vue-testing` |
| REST | `data-client-rest` |
| GraphQL | None beyond Always (`data-client-schema` covers `@data-client/graphql`) |
| Custom async | None beyond Always (`data-client-schema` covers `@data-client/endpoint`) |
In Claude Code, Cursor and Codex, install nothing now: each skill ships inside the `@data-client/*` package it covers, at that package's version. After installing the packages below, link their skills by running this in the app's folder (in a workspace monorepo, run it in each app: it links them at the workspace root, and in the app only those it installs at another version). It links them into `.agents/skills` and makes sure `.claude/skills` sees them too, whichever of the two folders the project already has:
```bash
npx --no data-client-skills # pnpm exec data-client-skills, yarn data-client-skills
```
If it says to start the agent in a folder, tell the user: agents started at the repository root load nested skills only once they touch its files.
If it reports `Kept` for `data-client-setup`, that's the copy the skills CLI installed to start this setup.
Remove it with `npx skills remove data-client-setup -y`, run in the folder holding the reported `.agents`, and run the command again, so this skill too follows the
installed version.
If the command isn't found, or links nothing and reports that a package ships no skills, the installed packages predate 0.19: install
the skills with the skills CLI as described below for other agents, and leave the last sentence (the `data-client-skills` command) out of the `AGENTS.md` lines.
Then add these lines to the project's `AGENTS.md` (create it if missing), using the project's package manager in the command. They tell later agents that Data Client owns the app's server state, so they reach for it and its skills instead of hand-written fetching, and keep the skill links current. Claude Code reads `AGENTS.md` only when the project has no `CLAUDE.md`, so if a `CLAUDE.md` exists, make sure it has an `@AGENTS.md` line. Commit `.agents/skills` and `.claude/skills` with the setup.
```md
This app manages server state (fetching, caching, mutations and real-time updates) with Reactive Data Client. Use it for all server data, and read the matching `data-client-*` skill before writing, changing or debugging code that loads or changes data. After adding, removing or upgrading `@data-client/*` packages, run `npx --no data-client-skills` and commit the skill links.
```
For other agents, use the installer that installed this skill. For OpenSkills and the skills CLI, add `-g` if this skill lives under your home directory rather than the project.
- **OpenSkills** (`AGENTS.md` lists skills in an `<available_skills>` block): `npx openskills install reactive/data-client/.agents/skills/<skill>`, once per skill.
- **Otherwise** use the skills CLI: `npx skills add reactive/data-client --skill <skill> --skill <skill> ...`
Skills linked during a session may not load until the next one (Claude Code only picks them up live from a `.claude/skills` folder that existed when the session started, and Cursor fixes its skill list when a chat starts). So for the rest of this session, whenever a task calls for one of them, here or after setup, read its `SKILL.md` directly (`.claude/skills/<skill>/SKILL.md` after linking) unless it's already available by name. The next session loads them on its own.
## Installation
### Core Packages
| Framework | Core Package |
|-----------|----------|
| React (all) | `@data-client/react` + dev: `@data-client/test` |
| Vue | `@data-client/vue` (testing included) |
Version floors: `vue` 3.4, and `typescript` 4.0 (4.5 with Vue). If the project is below one, tell the user before
upgrading it. On React Native and Expo (React 18 or later), `@data-client/test` renders with
`@testing-library/react-native`: add it as a dev dependency if the app doesn't have it.
### Install Command Examples
**React (NextJS, Expo, React Native, plain React):**
```bash
npm install @data-client/react && npm install -D @data-client/test
yarn add @data-client/react && yarn add -D @data-client/test
pnpm add @data-client/react && pnpm add -D @data-client/test
```
**Vue:**
```bash
npm install @data-client/vue
yarn add @data-client/vue
pnpm add @data-client/vue
```
## Provider Setup
After installing, put the provider at the root, outside every other provider and boundary, not where the replaced
library's provider was. React's `DataProvider` has a backup `<Suspense>`, so a Suspense boundary above it never catches.
### NextJS (App Router)
Edit `app/layout.tsx`:
```tsx
import { DataProvider } from '@data-client/react/nextjs';
export default function RootLayout({ children }) {
return (
<html>
<body>
<DataProvider>{children}</DataProvider>
</body>
</html>
);
}
```
**Important**: NextJS uses `@data-client/react/nextjs` import path.
Data Client supports only the App Router. If the app renders pages from `pages/` (`pages/_app`), tell the user:
moving to the App Router is a routing migration, so confirm with them before starting it.
### Expo
Edit `app/_layout.tsx`:
```tsx
import { Stack } from 'expo-router';
import { DataProvider } from '@data-client/react';
export default function RootLayout() {
return (
<DataProvider>
<Stack>
<Stack.Screen name="index" />
</Stack>
</DataProvider>
);
}
```
### React Native
Edit entry file (e.g., `index.tsx`):
```tsx
import { DataProvider } from '@data-client/react';
import { AppRegistry } from 'react-native';
const Root = () => (
<DataProvider>
<App />
</DataProvider>
);
AppRegistry.registerComponent('MyApp', () => Root);
```
### Plain React (Vite, CRA, etc.)
Edit entry file (e.g., `index.tsx`, `main.tsx`, or `src/index.tsx`):
```tsx
import { AsyncBoundary, DataProvider } from '@data-client/react';
import { createRoot } from 'react-dom/client';
createRoot(document.getElementById('root')!).render(
<DataProvider>
<AsyncBoundary fallback={<Spinner />}>
<App />
</AsyncBoundary>
</DataProvider>,
);
```
### Vue
Edit `main.ts`:
```ts
import { createApp } from 'vue';
import { DataClientPlugin } from '@data-client/vue';
import App from './App.vue';
const app = createApp(App);
app.use(DataClientPlugin, {
// optional overrides
// managers: getDefaultManagers,
// initialState,
// Controller,
// gcPolicy,
});
app.mount('#app');
```
## Error Reporting
If the app's data layer sends fetch errors to a tracker itself (TanStack Query's `QueryCache({ onError })`, a fetch
wrapper that calls Sentry), move that into an
[error reporting Manager](https://dataclient.io/docs/concepts/managers#error-reporting) in `managers`. A global
unhandled-rejection handler can't replace it: reads you don't await never reject unhandled, since their errors are
stored for the components that read them. For the same reason, don't add `.catch(() => {})` to those reads.
## Protocol-Specific Setup
After provider setup, follow the guide for each detected protocol. These guides are bundled copies of the standalone protocol setup skills, so they need nothing else installed.
### REST APIs
Follow [references/data-client-rest-setup.md](references/data-client-rest-setup.md), which will:
1. Install `@data-client/rest`
2. Offer to create a custom `BaseEndpoint` class extending `RestEndpoint`
3. Configure common behaviors: urlPrefix, authentication, error handling
### GraphQL APIs
Follow [references/data-client-graphql-setup.md](references/data-client-graphql-setup.md), which will:
1. Install `@data-client/graphql`
2. Create and configure `GQLEndpoint` instance
3. Set up authentication headers
### Custom Async Operations
Follow [references/data-client-endpoint-setup.md](references/data-client-endpoint-setup.md), which will:
1. Install `@data-client/endpoint`
2. Offer to wrap existing async functions with `new Endpoint()`
3. Configure schemas and caching options
### Multiple Protocols
If multiple protocols are detected, follow each protocol's guide. Each protocol package can be installed alongside others.
## Replacing TanStack Query
When a React app uses TanStack Query, a request to set up or migrate to Data Client includes replacing it: follow
[TanStack Query migration](references/tanstack-query-migration.md) from its "Steps" section. Its step 1 is
the protocol guide above, so the REST guide's "leave how the app loads and stores data alone" does not apply here. Look up each
TanStack Query API in its "API map" rather than working out a replacement, and finish with its "Check the migration"
list. Libraries built on TanStack Query, like `react-query-auth`, are replaced in the same pass.
When its checks pass, offer the optional performance pass (skill "data-client-performance") as a separate stage.
Data Client's own `useQuery` reads the store and never fetches, so it is not the replacement for TanStack Query's
`useQuery`: that is `useSuspense` (or `useDLE`).
The guide is React only. For a Vue app on `@tanstack/vue-query`, tell the user this skill has no Vue migration guide
yet, and finish setup without replacing it.
## Verification Checklist
After setup, verify:
- [ ] Core packages installed in `package.json`
- [ ] Provider/Plugin is at the root, outside every other provider and Suspense boundary
- [ ] Correct import path used (especially `@data-client/react/nextjs` for NextJS)
- [ ] No duplicate providers in component tree
- [ ] Protocol-specific setup completed via its guide
- [ ] Migrating from TanStack Query: the guide's "Check the migration" list passes
## Common Issues
### NextJS: Wrong Import Path
❌ Wrong:
```tsx
import { DataProvider } from '@data-client/react';
```
✅ Correct for NextJS:
```tsx
import { DataProvider } from '@data-client/react/nextjs';
```
## Next Steps
After core setup and protocol-specific setup (in this session, read each skill below from `.claude/skills/<skill>/SKILL.md`):
1. Define data schemas using `Entity` - see skill "data-client-schema"
2. Use hooks like `useSuspense`, `useQuery`, `useController` - see skill "data-client-react" or "data-client-vue"
3. Define REST resources - see skill "data-client-rest"
## References
Vue projects: read `<name>.vue.md` instead of `<name>.md` when it exists.
For detailed API documentation, see the [references](references/) directory:
- [DataProvider](references/DataProvider.md) - React root provider component (Vue installs `DataClientPlugin` instead; see installation)
- [DataClientPlugin](references/DataClientPlugin.md) - Plugin options (Vue)
- [installation](references/installation.md) - Installation guide
- [getDefaultManagers](references/getDefaultManagers.md) - Default managers
- [REST setup](references/data-client-rest-setup.md) - `@data-client/rest` setup and migration from axios, fetch, ky, superagent or got
- [GraphQL setup](references/data-client-graphql-setup.md) - `@data-client/graphql` setup
- [Custom endpoint setup](references/data-client-endpoint-setup.md) - Wrapping other async functions with `@data-client/endpoint`
- [TanStack Query migration](references/tanstack-query-migration.md) - Replace `useQuery`, `useMutation`, query invalidation and `QueryClient` (React)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |