Skip to content

reactive/data-client / .agents/skills/data-client-setup

data-client-setup

Verified

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.

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:

CheckProject Type
"next" in dependenciesNextJS
"expo" in dependenciesExpo
"vue" in dependenciesVue
"react-native" in dependencies (no expo)React Native
"react" in dependenciesPlain 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.jsonThen
@tanstack/react-query or react-query (React)After setup, migrate per 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:

DetectedSkills
Alwaysdata-client-schema, data-client-manager
React (NextJS, Expo, React Native, plain React)data-client-react, data-client-react-testing, data-client-performance
Vuedata-client-vue, data-client-vue-testing
RESTdata-client-rest
GraphQLNone beyond Always (data-client-schema covers @data-client/graphql)
Custom asyncNone 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:

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.

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

FrameworkCore 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):

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:

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:

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:

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):

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):

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:

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 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, 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, 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, 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 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:

import { DataProvider } from '@data-client/react';

✅ Correct for NextJS:

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 directory:

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: 197kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall