data-client-setup

# 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. 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` | | 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 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: ```bash 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. ```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) | ### 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, add the provider at the top-level component. ### NextJS (App Router) Edit `app/layout.tsx`: ```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`: ```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 { DataProvider } from '@data-client/react'; import { createRoot } from 'react-dom/client'; createRoot(document.getElementById('root')!).render( <DataProvider> <App /> </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'); ``` ## 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. ## Verification Checklist After setup, verify: - [ ] Core packages installed in `package.json` - [ ] Provider/Plugin wraps the app at root level - [ ] Correct import path used (especially `@data-client/react/nextjs` for NextJS) - [ ] No duplicate providers in component tree - [ ] Protocol-specific setup completed via its guide ## 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'; ``` ### Provider Not at Root The `DataProvider` must wrap all components that use data-client hooks. Place it at the topmost level possible. In Vue, call `app.use(DataClientPlugin)` on the root app before `app.mount()`. ## 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`