playbooks

home / skills / forge-town / skills / check-refine-trpc

check-refine-trpc skill

/skills/check-refine-trpc

This skill identifies components that directly use trpc or react-query hooks and guides replacing them with refine hooks for consistent data access.

npx playbooks add skill forge-town/skills --skill check-refine-trpc

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
2.3 KB
---
name: check-refine-trpc
description: 检查组件是否直接使用 trpc，组件必须使用 refine。
---

# 组件级强制规则：禁止直接使用 trpc

- 目的：在代码库中识别前端组件/页面中**直接导入或调用 `trpc` 客户端** 或 `@tanstack/react-query` 的 hook 的情况。
- 规则：组件层必须使用 `refine` 的 hooks（例如 `useList`、`useOne`、`useCreate`、`useUpdate`）或通过已实现的 `DataProvider` 封装后再在组件中使用。**禁止在组件或页面中直接使用 `trpc` 客户端或其 hooks。**

## 检测方法

- 静态扫描组件/页面文件，查找直接导入或使用以下模式（任意匹配即为违规）：
  - 导入 `trpc` 客户端（如 `import { trpc } from` / `import trpcClient from`）
  - 直接使用 `trpc.*.useQuery` / `trpc.*.useMutation` 或 `useQuery`/`useMutation` 来自 `@tanstack/react-query` 并用于组件渲染
  - 直接在组件中调用 `trpcClient` 的方法（如 `trpcClient.query(...)`）

## 示例（禁止 / 允许）

- 禁止：在组件中直接使用 trpc hook

- 禁止示例：见 [bad-example.ts](references/bad-example.ts)
- 允许示例：见 [good-example.ts](references/good-example.ts)

## 核查清单（强制）

- 目标：定位并列出需要从 `trpc`/`react-query` 迁移到 `refine` 的组件使用点，提供最小可执行修复建议。
- 违规判断（任一成立即违规）：
  - 文件包含 `import .*\btrpc\b` / `import trpcClient` 等直接导入
  - 使用 `trpc\.[A-Za-z0-9_]+\.(useQuery|useMutation)`
  - 在组件中直接使用 `useQuery(` 或 `useMutation(` 来自 `@tanstack/react-query`
  - 在组件中直接调用 `trpcClient.*` RPC 方法
- 推荐自动化检测正则（示例）：
  - 导入检测：`import\s+.*\btrpc\b|import\s+trpcClient`
  - hook 检测：`trpc\.[a-zA-Z0-9_]+\.(useQuery|useMutation)`
  - react-query 检测：`from\s+['\"]@tanstack/react-query['\"]|\buseQuery\s*\(`

## 修复建议

- 优先：用 `refine` 的 `useList`/`useOne`/`useCreate`/`useUpdate` 替换组件内数据调用。
- 可选：在 `DataProvider` 中封装 trpc 调用并在组件中通过 `resource` + `refine` hooks 使用。
- 复杂查询：在 `DataProvider` 增加 `custom`，并通过 refine 的自定义 hook 使用，保持行为等价（分页/筛选映射）。

Overview

This skill scans frontend component and page files to detect direct usage of the trpc client or @tanstack/react-query hooks. It enforces a rule that components must use refine hooks (e.g., useList, useOne, useCreate, useUpdate) or a wrapped DataProvider instead of calling trpc directly. The goal is to locate violations and provide minimal, actionable remediation suggestions.

How this skill works

The checker performs static analysis of source files and applies pattern matching against common import and usage signatures. It flags files that import trpc or trpcClient, call trpc.<resource>.useQuery/useMutation, call trpcClient.* RPC methods, or use useQuery/useMutation from @tanstack/react-query inside components. For each finding it reports the file, matched snippet, and a concise fix recommendation.

When to use it

  • Before pull request review to prevent direct trpc usage in components
  • During a CI pipeline step to enforce component-level data access rules
  • When migrating a codebase to use refine and a centralized DataProvider
  • To generate a prioritized list of components needing refactor
  • When auditing third-party or vendor components for data access patterns

Best practices

  • Replace component trpc calls with refine hooks (useList/useOne/useCreate/useUpdate) wherever possible
  • Wrap trpc RPCs inside a DataProvider and expose resources for refine hooks
  • For complex RPCs, add custom operations to DataProvider and map pagination/filter params
  • Treat any import matching trpc or trpcClient as a violation candidate and inspect context
  • Provide automated suggested patches that map basic queries/mutations to refine equivalents

Example use cases

  • CI job that fails if any component imports trpc or uses useQuery/useMutation directly
  • Developer runs a local scan to list files to refactor when adopting refine
  • Automatic report for a migration sprint showing component-level remediation tasks
  • Code health dashboard showing counts of direct trpc usages and suggested fixes

FAQ

What exactly counts as a violation?

Any component or page file that imports trpc or trpcClient, uses trpc.<x>.useQuery/useMutation, calls trpcClient.* RPCs, or uses useQuery/useMutation from @tanstack/react-query for rendering is considered a violation.

How should I fix flagged code?

Prefer replacing the component call with refine hooks (useList/useOne/useCreate/useUpdate). If direct mapping is complex, wrap the trpc calls in your DataProvider and expose them via resource/custom operations for refine usage.