Setup Reactive Data Client
Detection Steps
Before installing, detect the project type and protocol by checking these files:
- 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
- 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
- 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
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):
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, add the provider at the top-level component.
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 { DataProvider } from '@data-client/react'; import ReactDOM from 'react-dom/client';
ReactDOM.createRoot(document.getElementById('root')!).render( <DataProvider> <App /> </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, apply the appropriate skill based on detected protocol:
REST APIs
Apply skill "data-client-rest-setup" which will:
-
Install @data-client/rest
-
Offer to create a custom BaseEndpoint class extending RestEndpoint
-
Configure common behaviors: urlPrefix, authentication, error handling
GraphQL APIs
Apply skill "data-client-graphql-setup" which will:
-
Install @data-client/graphql
-
Create and configure GQLEndpoint instance
-
Set up authentication headers
Custom Async Operations
Apply skill "data-client-endpoint-setup" which will:
-
Install @data-client/endpoint
-
Offer to wrap existing async functions with new Endpoint()
-
Configure schemas and caching options
Multiple Protocols
If multiple protocols are detected, apply multiple setup skills. 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 appropriate skill
Common Issues
NextJS: Wrong Import Path
❌ Wrong:
import { DataProvider } from '@data-client/react';
✅ Correct for NextJS:
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.
Next Steps
After core setup and protocol-specific setup:
-
Define data schemas using Entity
-
see skill "data-client-schema"
-
Use hooks like useSuspense , useQuery , useController
-
see skill "data-client-react" or "data-client-vue"
-
Define REST resources - see skill "data-client-rest"
References
For detailed API documentation, see the references directory:
-
DataProvider - Root provider component
-
installation - Installation guide
-
getDefaultManagers - Default managers