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:

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

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:

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 from the project root. 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 reports Kept .agents/skills/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 and run the command again, so this skill too follows the installed version.

If the command isn't found, or 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

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>
      <DataProvider>
        <body>
          {children}
        </body>
      </DataProvider>
    </html>
  );
}

Important: NextJS uses @data-client/react/nextjs import path.

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');

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

• DataProvider - React root provider component (Vue installs DataClientPlugin instead; see installation)
• DataClientPlugin - Plugin options (Vue)
• installation - Installation guide
• getDefaultManagers - Default managers
• REST setup - @data-client/rest setup and migration from axios, fetch, ky, superagent or got
• GraphQL setup - @data-client/graphql setup
• Custom endpoint setup - Wrapping other async functions with @data-client/endpoint
• TanStack Query migration - Replace useQuery, useMutation, query invalidation and QueryClient (React)