tomevault-io Setup Reactive Data Client
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→ useyarn addpnpm-lock.yaml→ usepnpm addpackage-lock.jsonorbun.lockb→ usenpm installorbun 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,superagentinpackage.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-taginpackage.json.graphqlor.gqlfiles 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
BaseEndpointclass extendingRestEndpoint - Configure common behaviors: urlPrefix, authentication, error handling
GraphQL APIs
Apply skill "data-client-graphql-setup" which will:
- Install
@data-client/graphql - Create and configure
GQLEndpointinstance - 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/nextjsfor 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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.