data-client-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Setup Reactive Data Client

配置Reactive Data Client

Detection Steps

检测步骤

Before installing, detect the project type and protocol by checking these files:

在安装前，通过检查以下文件来检测项目类型和协议：

1. Detect Package Manager

1. 检测包管理器

Check which lock file exists:

```
yarn.lock
```
→ use
```
yarn add
```
```
pnpm-lock.yaml
```
→ use
```
pnpm add
```

package-lock.json

bun.lockb

→ use

npm install

bun add

检查存在哪种锁文件：

```
yarn.lock
```
→ 使用
```
yarn add
```
```
pnpm-lock.yaml
```
→ 使用
```
pnpm add
```

package-lock.json

或

bun.lockb

→ 使用

npm install

或

bun add

2. Detect Project Type

2. 检测项目类型

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

检查

package.json

中的依赖项：

检查项	项目类型
依赖中包含 `"next"`	NextJS
依赖中包含 `"expo"`	Expo
依赖中包含 `"vue"`	Vue
依赖中包含 `"react-native"` （无expo）	React Native
依赖中包含 `"react"`	普通React

3. Detect Protocol Type

3. 检测协议类型

Scan the codebase to determine which data-fetching protocols are used:

扫描代码库以确定使用的是哪种数据获取协议：

REST Detection

REST协议检测

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(
```

查找以下模式：

带有REST风格URL的
```
fetch()
```
调用（如
```
/api/
```
、
```
/users/
```
等）
```
package.json
```
中的HTTP客户端库：
```
axios
```
、
```
ky
```
、
```
got
```
、
```
superagent
```
包含REST模式的文件：
```
api.ts
```
、
```
client.ts
```
、
```
services/*.ts
```
带有路径参数的URL模式：
```
/users/:id
```
、
```
/posts/:postId/comments
```
代码中的HTTP方法：
```
method: 'GET'
```
、
```
method: 'POST'
```
、
```
.get(
```
、
```
.post(
```

GraphQL Detection

GraphQL协议检测

Look for these patterns:

@apollo/client

graphql-request

urql

graphql-tag

package.json

```
.graphql
```
or
```
.gql
```
files in the project
`gql`` template literal tags
GraphQL query patterns:
```
query {
```
,
```
mutation {
```
,
```
subscription {
```
GraphQL endpoint URLs:
```
/graphql
```

查找以下模式：

package.json

中的

@apollo/client

、

graphql-request

、

urql

、

graphql-tag

项目中的
```
.graphql
```
或
```
.gql
```
文件
`gql``模板字面量标签
GraphQL查询模式：
```
query {
```
、
```
mutation {
```
、
```
subscription {
```
GraphQL端点URL：
```
/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

对于不匹配REST或GraphQL的异步操作：

返回Promise的自定义异步函数
第三方SDK客户端（Firebase、Supabase、AWS SDK等）
IndexedDB或其他本地异步存储

Installation

安装

Core Packages

核心包

Framework	Core Package
React (all)	`@data-client/react` + dev: `@data-client/test`
Vue	`@data-client/vue` (testing included)

框架	核心包
所有React框架	`@data-client/react` + 开发依赖: `@data-client/test`
Vue	`@data-client/vue` （已包含测试工具）

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

React（NextJS、Expo、React Native、普通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)

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.

编辑

app/layout.tsx

：

tsx

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

export default function RootLayout({ children }) {
  return (
    <html>
      <DataProvider>
        <body>
          {children}
        </body>
      </DataProvider>
    </html>
  );
}

重要提示：NextJS需使用

@data-client/react/nextjs

导入路径。

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

编辑

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

编辑入口文件（如

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

普通React（Vite、CRA等）

Edit entry file (e.g.,

index.tsx

main.tsx

, or

src/index.tsx

tsx

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

ReactDOM.createRoot(document.getElementById('root')!).render(
  <DataProvider>
    <App />
  </DataProvider>,
);

编辑入口文件（如

index.tsx

、

main.tsx

或

src/index.tsx

）：

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

编辑

main.ts

：

import { createApp } from 'vue';
import { DataClientPlugin } from '@data-client/vue';
import App from './App.vue';

const app = createApp(App);

app.use(DataClientPlugin, {
  // 可选配置项
  // managers: getDefaultManagers(),
  // initialState,
  // Controller,
  // gcPolicy,
});

app.mount('#app');

Protocol-Specific Setup

协议专属配置

After provider setup, apply the appropriate skill based on detected protocol:

提供者配置完成后，根据检测到的协议应用对应的技能：

REST APIs

REST API

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

应用技能**"data-client-rest-setup"**，该技能将：

安装
```
@data-client/rest
```
提供创建继承自
```
RestEndpoint
```
的自定义
```
BaseEndpoint
```
类的选项
配置通用行为：url前缀、身份验证、错误处理

GraphQL APIs

GraphQL API

Apply skill "data-client-graphql-setup" which will:

Install
```
@data-client/graphql
```
Create and configure
```
GQLEndpoint
```
instance
Set up authentication headers

应用技能**"data-client-graphql-setup"**，该技能将：

安装
```
@data-client/graphql
```
创建并配置
```
GQLEndpoint
```
实例
设置身份验证请求头

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

应用技能**"data-client-endpoint-setup"**，该技能将：

安装
```
@data-client/endpoint
```
提供使用
```
new Endpoint()
```
包装现有异步函数的选项
配置模式和缓存选项

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

配置完成后，验证以下内容：

核心包已安装至
```
package.json
```
提供者/插件已在根层级包裹应用
使用了正确的导入路径（尤其注意NextJS需使用
```
@data-client/react/nextjs
```
）
组件树中无重复的提供者
已通过对应技能完成协议专属配置

Common Issues

常见问题

NextJS: Wrong Import Path

NextJS：导入路径错误

❌ Wrong:

tsx

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

✅ Correct for NextJS:

tsx

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

❌ 错误写法：

tsx

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

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

DataProvider

必须包裹所有使用data-client钩子的组件。请将其放置在尽可能顶层的位置。

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"

核心配置和协议专属配置完成后：

使用
```
Entity
```
定义数据模式 - 查看技能"data-client-schema"
使用
```
useSuspense
```
、
```
useQuery
```
、
```
useController
```
等钩子 - 查看技能"data-client-react"或"data-client-vue"
定义REST资源 - 查看技能"data-client-rest"

References

参考资料

For detailed API documentation, see the references directory:

DataProvider - Root provider component
installation - Installation guide
getDefaultManagers - Default managers

如需详细的API文档，请查看参考资料目录：

DataProvider - 根提供者组件
installation - 安装指南
getDefaultManagers - 默认管理器