React前端专家指南：函数式组件、自定义钩子、项目结构与最佳实践

react-frontend-expert by hieutrtr/ai1-skills

78 周安装量

8 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/hieutrtr/ai1-skills --skill react-frontend-expert

React TypeScript 前端架构

🇨🇳中文介绍

React 前端专家

使用时机

在以下情况时激活此技能：

创建或修改 React 组件（仅限函数式组件）
编写自定义钩子（useXxx）
构建带路由的页面
使用 TanStack Query 实现数据获取
处理带验证的表单
为 React/TypeScript 应用程序设置项目结构

不要在以下情况使用此技能：

编写组件或钩子测试（使用 react-testing-patterns）
E2E 浏览器测试（使用 e2e-testing）
API 契约设计（使用 api-design-patterns）
后端实现（使用 python-backend-expert）
部署或 CI/CD（使用 deployment-pipeline）

使用说明

项目结构

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

钩子规则与自定义钩子

只在最顶层调用钩子 — 绝不在循环、条件或嵌套函数内部调用
只在 React 函数组件或自定义钩子中调用钩子
自定义钩子必须以 use 开头

自定义钩子模式

export function useDebounce<T>(value: T, delayMs: number): T {
  const [debouncedValue, setDebouncedValue] = useState(value);

  useEffect(() => {
    const timer = setTimeout(() => setDebouncedValue(value), delayMs);
    return () => clearTimeout(timer);
  }, [value, delayMs]);

  return debouncedValue;
}

interface AuthContext {
  user: User | null;
  isAuthenticated: boolean;
  login: (credentials: LoginCredentials) => Promise<void>;
  logout: () => void;
}

const AuthContext = createContext<AuthContext | null>(null);

export function useAuth(): AuthContext {
  const context = useContext(AuthContext);
  if (!context) {
    throw new Error("useAuth must be used within AuthProvider");
  }
  return context;
}

interface PaginationState {
  cursor: string | null;
  hasMore: boolean;
  goToNext: (nextCursor: string) => void;
  reset: () => void;
}

export function usePagination(): PaginationState {
  const [cursor, setCursor] = useState<string | null>(null);
  const [hasMore, setHasMore] = useState(true);

  return {
    cursor,
    hasMore,
    goToNext: (nextCursor: string) => {
      setCursor(nextCursor);
    },
    reset: () => {
      setCursor(null);
      setHasMore(true);
    },
  };
}

何时提取自定义钩子：

逻辑在 2 个以上组件中复用
组件有复杂的状态管理（>3 个 useState 调用）
副作用需要封装（订阅、定时器）
数据获取逻辑可以共享

使用 TanStack Query 进行数据获取

查询选项工厂（推荐）

集中定义查询键和函数，防止键冲突：

// api/users.ts
import { queryOptions } from "@tanstack/react-query";

export const userQueries = {
  all: () =>
    queryOptions({
      queryKey: ["users"],
      queryFn: () => apiClient.get<UserListResponse>("/users"),
    }),

  detail: (userId: number) =>
    queryOptions({
      queryKey: ["users", userId],
      queryFn: () => apiClient.get<UserResponse>(`/users/${userId}`),
    }),

  search: (query: string) =>
    queryOptions({
      queryKey: ["users", "search", query],
      queryFn: () => apiClient.get<UserListResponse>(`/users?q=${query}`),
      enabled: query.length > 0,
    }),
};

在组件中使用查询

export function UserDetailPage({ userId }: { userId: number }) {
  const { data: user, isPending, isError, error } = useQuery(
    userQueries.detail(userId)
  );

  if (isPending) return <Spinner />;
  if (isError) return <ErrorMessage error={error} />;

  return <UserProfile user={user} />;
}

带有缓存失效的变更

export function useCreateUser() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (data: UserCreate) =>
      apiClient.post<UserResponse>("/users", data),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ["users"] });
    },
  });
}

TanStack Query 规则：

设置 staleTime > 0（默认值 0 过于激进）：staleTime: 5 * 60 * 1000（5 分钟）
变更后使用 invalidateQueries() — 绝不手动 refetch()
处理所有状态：isPending、isError、data
使用 queryOptions() 工厂 — 防止键拼写错误和重复
使用 enabled 防止查询在不完整的参数下运行

// 使用 `interface` 定义对象形状（组件属性、API 响应）
interface User {
  id: number;
  email: string;
  displayName: string;
  role: "admin" | "editor" | "member";
}

// 使用 `type` 定义联合类型、交叉类型和计算类型
type UserRole = User["role"];
type CreateOrUpdate = UserCreate | UserUpdate;

// 使用可辨识联合类型表示状态机
type AsyncState<T> =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: T }
  | { status: "error"; error: Error };

TypeScript 规则：

在 tsconfig.json 中启用 strict: true — 无例外
绝不使用 any — 对于真正未知的类型使用 unknown
对于字面量对象类型使用 as const
对于可扩展的类型优先使用 interface，其他情况使用 type
对于可复用的工具类型和钩子使用泛型
从 types/ 目录导出类型以供共享使用

import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";

const userSchema = z.object({
  email: z.string().email("Invalid email"),
  displayName: z.string().min(1, "Required").max(100),
  role: z.enum(["admin", "editor", "member"]),
});

type UserFormData = z.infer<typeof userSchema>;

export function UserForm({ onSubmit }: { onSubmit: (data: UserFormData) => void }) {
  const {
    register,
    handleSubmit,
    formState: { errors, isSubmitting },
  } = useForm<UserFormData>({
    resolver: zodResolver(userSchema),
  });

  return (
    <form onSubmit={handleSubmit(onSubmit)} noValidate>
      <label htmlFor="email">Email</label>
      <input id="email" type="email" {...register("email")} aria-invalid={!!errors.email} />
      {errors.email && <span role="alert">{errors.email.message}</span>}

      <label htmlFor="displayName">Name</label>
      <input id="displayName" {...register("displayName")} aria-invalid={!!errors.displayName} />
      {errors.displayName && <span role="alert">{errors.displayName.message}</span>}

      <button type="submit" disabled={isSubmitting}>Save</button>
    </form>
  );
}

每个组件必须满足 WCAG 2.1 AA 标准：

语义化 HTML 优先： 使用 <button>、<nav>、<main>、<article> — 而不是 <div onClick>
标签： 每个表单输入都有匹配 htmlFor/id 的 <label>
仅在需要时使用 ARIA： 为纯图标按钮使用 aria-label，为动态更新使用 aria-live，为错误信息使用 role="alert"
键盘导航： 所有交互元素都能通过 Tab 键访问，并能通过 Enter/Space 键激活
焦点管理： 路由变化时将焦点设置到主要内容，在模态框中捕获焦点
颜色对比度： 普通文本至少 4.5:1，大文本至少 3:1
替代文本： 所有 <img> 标签都有描述性的 alt 属性（装饰性图片使用 alt=""）

带搜索和分页的用户列表页面

export default function UserListPage() {
  const [search, setSearch] = useState("");
  const debouncedSearch = useDebounce(search, 300);
  const pagination = usePagination();

  const { data, isPending } = useQuery(
    userQueries.list({ q: debouncedSearch, cursor: pagination.cursor })
  );

  return (
    <main>
      <h1>Users</h1>
      <input
        type="search"
        value={search}
        onChange={(e) => { setSearch(e.target.value); pagination.reset(); }}
        placeholder="Search users..."
        aria-label="Search users"
      />
      {isPending ? <Spinner /> : (
        <>
          <UserTable users={data.items} />
          {data.hasMore && (
            <button onClick={() => pagination.goToNext(data.nextCursor)}>
              Load more
            </button>
          )}
        </>
      )}
    </main>
  );
}

钩子中的过时闭包： 当使用引用状态的回调时，对于频繁变化的值使用 useRef，或者在 useCallback/useEffect 的依赖数组中包含依赖项。
TanStack Query 键冲突： 按层次结构组织键：列表用 ["users"]，详情用 ["users", id]，过滤列表用 ["users", { q, page }]。使用 queryOptions() 工厂集中定义键。
无限重新渲染： 常见原因：缺少依赖数组、在渲染中创建新对象/数组（用 useMemo 包装）、在 useEffect 中没有适当条件的状态更新。
水合不匹配： 避免在初始渲染期间渲染依赖于仅浏览器 API（window、localStorage）的内容。使用 useEffect 或检查 typeof window !== "undefined"。
内存泄漏： 在 useEffect 清理函数中取消异步操作。TanStack Query 会自动处理查询的清理。

有关带注释的组件模板，请参阅 references/component-templates.md。有关 CRUD 查询模式，请参阅 references/tanstack-query-patterns.md。

🇺🇸English

React Frontend Expert

When to Use

Activate this skill when:

Creating or modifying React components (functional components only)
Writing custom hooks (useXxx)
Building pages with routing
Implementing data fetching with TanStack Query
Handling forms with validation
Setting up project structure for a React/TypeScript application

Do NOT use this skill for:

Writing component or hook tests (use react-testing-patterns)
E2E browser testing (use e2e-testing)
API contract design (use api-design-patterns)
Backend implementation (use python-backend-expert)
Deployment or CI/CD (use deployment-pipeline)

Instructions

Project Structure

src/
├── api/                  # API client functions and query options
│   ├── client.ts         # Axios/fetch instance with interceptors
│   ├── users.ts          # User API functions + query options
│   └── posts.ts
├── components/           # Shared, reusable UI components
│   ├── Button.tsx
│   ├── Modal.tsx
│   ├── Table/
│   │   ├── Table.tsx
│   │   └── TablePagination.tsx
│   └── Form/
│       ├── Input.tsx
│       └── Select.tsx
├── features/             # Domain-specific feature components
│   ├── users/
│   │   ├── UserList.tsx
│   │   └── UserProfile.tsx
│   └── posts/
│       └── PostEditor.tsx
├── hooks/                # Custom hooks
│   ├── useAuth.ts
│   ├── useDebounce.ts
│   └── usePagination.ts
├── layouts/              # Layout components
│   ├── MainLayout.tsx
│   └── AuthLayout.tsx
├── pages/                # Route-level page components
│   ├── HomePage.tsx
│   ├── LoginPage.tsx
│   └── users/
│       ├── UserListPage.tsx
│       └── UserDetailPage.tsx
├── types/                # Shared TypeScript types
│   ├── api.ts            # API response types
│   └── user.ts
├── App.tsx               # Root component with providers and router
└── main.tsx              # Entry point

Component Structure

Functional Components Only

interface UserCardProps {
  user: User;
  onEdit: (userId: number) => void;
  showEmail?: boolean;
}

export function UserCard({ user, onEdit, showEmail = false }: UserCardProps) {
  return (
    <article className="user-card">
      <h3>{user.displayName}</h3>
      {showEmail && <p>{user.email}</p>}
      <button type="button" onClick={() => onEdit(user.id)}>
        Edit
      </button>
    </article>
  );
}

Component rules:

Named exports for shared components: export function Button
Default exports for page components: export default function UserListPage
Props interface named {Component}Props
Destructure props in function signature
Keep components under 200 lines — extract sub-components or hooks when larger
Use children and composition over deep prop drilling
Never use React.FC — use plain function syntax

Component File Organization

For complex components, co-locate related files:

UserProfile/
├── UserProfile.tsx       # Main component
├── UserProfile.css       # Styles (or .module.css)
├── UserAvatar.tsx        # Sub-component
└── index.ts              # Re-export: export { UserProfile } from './UserProfile'

Hooks Rules and Custom Hooks

Rules of Hooks

Only call hooks at the top level — never inside loops, conditions, or nested functions
Only call hooks from React function components or custom hooks
Custom hooks must start with use

Custom Hook Patterns

useDebounce:

export function useDebounce<T>(value: T, delayMs: number): T {
  const [debouncedValue, setDebouncedValue] = useState(value);

  useEffect(() => {
    const timer = setTimeout(() => setDebouncedValue(value), delayMs);
    return () => clearTimeout(timer);
  }, [value, delayMs]);

  return debouncedValue;
}

useAuth:

interface AuthContext {
  user: User | null;
  isAuthenticated: boolean;
  login: (credentials: LoginCredentials) => Promise<void>;
  logout: () => void;
}

const AuthContext = createContext<AuthContext | null>(null);

export function useAuth(): AuthContext {
  const context = useContext(AuthContext);
  if (!context) {
    throw new Error("useAuth must be used within AuthProvider");
  }
  return context;
}

usePagination:

interface PaginationState {
  cursor: string | null;
  hasMore: boolean;
  goToNext: (nextCursor: string) => void;
  reset: () => void;
}

export function usePagination(): PaginationState {
  const [cursor, setCursor] = useState<string | null>(null);
  const [hasMore, setHasMore] = useState(true);

  return {
    cursor,
    hasMore,
    goToNext: (nextCursor: string) => {
      setCursor(nextCursor);
    },
    reset: () => {
      setCursor(null);
      setHasMore(true);
    },
  };
}

When to extract a custom hook:

Logic is reused across 2+ components
Component has complex state management (>3 useState calls)
Side effects need encapsulation (subscriptions, timers)
Data fetching logic can be shared

Data Fetching with TanStack Query

Query Options Factory (Recommended)

Centralize query key and function definitions to prevent key collisions:

// api/users.ts
import { queryOptions } from "@tanstack/react-query";

export const userQueries = {
  all: () =>
    queryOptions({
      queryKey: ["users"],
      queryFn: () => apiClient.get<UserListResponse>("/users"),
    }),

  detail: (userId: number) =>
    queryOptions({
      queryKey: ["users", userId],
      queryFn: () => apiClient.get<UserResponse>(`/users/${userId}`),
    }),

  search: (query: string) =>
    queryOptions({
      queryKey: ["users", "search", query],
      queryFn: () => apiClient.get<UserListResponse>(`/users?q=${query}`),
      enabled: query.length > 0,
    }),
};

Using Queries in Components

export function UserDetailPage({ userId }: { userId: number }) {
  const { data: user, isPending, isError, error } = useQuery(
    userQueries.detail(userId)
  );

  if (isPending) return <Spinner />;
  if (isError) return <ErrorMessage error={error} />;

  return <UserProfile user={user} />;
}

Mutations with Cache Invalidation

export function useCreateUser() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (data: UserCreate) =>
      apiClient.post<UserResponse>("/users", data),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ["users"] });
    },
  });
}

TanStack Query rules:

Set staleTime > 0 (default 0 is too aggressive): staleTime: 5 * 60 * 1000 (5 min)
Use invalidateQueries() after mutations — never manual refetch()
Handle all states: isPending, isError, data
Use queryOptions() factory — prevents key typos and duplication
Use enabled to prevent queries from running with incomplete parameters

TypeScript Conventions

// Use `interface` for object shapes (components props, API responses)
interface User {
  id: number;
  email: string;
  displayName: string;
  role: "admin" | "editor" | "member";
}

// Use `type` for unions, intersections, and computed types
type UserRole = User["role"];
type CreateOrUpdate = UserCreate | UserUpdate;

// Discriminated unions for state machines
type AsyncState<T> =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: T }
  | { status: "error"; error: Error };

TypeScript rules:

Enable strict: true in tsconfig.json — no exceptions
Never use any — use unknown for truly unknown types
Use as const for literal object types
Prefer interface for extensible types, type for everything else
Use generics for reusable utility types and hooks
Export types from types/ directory for shared use

Form Handling

import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";

const userSchema = z.object({
  email: z.string().email("Invalid email"),
  displayName: z.string().min(1, "Required").max(100),
  role: z.enum(["admin", "editor", "member"]),
});

type UserFormData = z.infer<typeof userSchema>;

export function UserForm({ onSubmit }: { onSubmit: (data: UserFormData) => void }) {
  const {
    register,
    handleSubmit,
    formState: { errors, isSubmitting },
  } = useForm<UserFormData>({
    resolver: zodResolver(userSchema),
  });

  return (
    <form onSubmit={handleSubmit(onSubmit)} noValidate>
      <label htmlFor="email">Email</label>
      <input id="email" type="email" {...register("email")} aria-invalid={!!errors.email} />
      {errors.email && <span role="alert">{errors.email.message}</span>}

      <label htmlFor="displayName">Name</label>
      <input id="displayName" {...register("displayName")} aria-invalid={!!errors.displayName} />
      {errors.displayName && <span role="alert">{errors.displayName.message}</span>}

      <button type="submit" disabled={isSubmitting}>Save</button>
    </form>
  );
}

Accessibility Requirements

Every component must meet WCAG 2.1 AA:

Semantic HTML first: Use <button>, <nav>, <main>, <article> — not <div onClick>
Labels: Every form input has a <label> with matching htmlFor/id
ARIA only when needed: aria-label for icon-only buttons, aria-live for dynamic updates, for errors

Examples

User List Page with Search and Pagination

export default function UserListPage() {
  const [search, setSearch] = useState("");
  const debouncedSearch = useDebounce(search, 300);
  const pagination = usePagination();

  const { data, isPending } = useQuery(
    userQueries.list({ q: debouncedSearch, cursor: pagination.cursor })
  );

  return (
    <main>
      <h1>Users</h1>
      <input
        type="search"
        value={search}
        onChange={(e) => { setSearch(e.target.value); pagination.reset(); }}
        placeholder="Search users..."
        aria-label="Search users"
      />
      {isPending ? <Spinner /> : (
        <>
          <UserTable users={data.items} />
          {data.hasMore && (
            <button onClick={() => pagination.goToNext(data.nextCursor)}>
              Load more
            </button>
          )}
        </>
      )}
    </main>
  );
}

Edge Cases

Stale closures in hooks: When using callbacks that reference state, use useRef for mutable values that change frequently, or include dependencies in useCallback/useEffect arrays.
TanStack Query key collisions: Structure keys hierarchically: ["users"] for list, ["users", id] for detail, ["users", { q, page }] for filtered list. Use queryOptions() factory to centralize key definitions.
Infinite re-renders: Common causes: missing dependency arrays, creating new objects/arrays in render (wrap in useMemo), state updates in useEffect without proper conditions.
Hydration mismatches: Avoid rendering content that depends on browser-only APIs (window, localStorage) during initial render. Use useEffect or check .

See references/component-templates.md for annotated component templates. See references/tanstack-query-patterns.md for CRUD query patterns.

Weekly Installs

Repository

hieutrtr/ai1-skills

GitHub Stars

First Seen

Feb 4, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

codex71

opencode70

github-copilot69

gemini-cli66

kimi-cli62

amp62

TanStack Query v5 完全指南：React 数据管理、乐观更新、离线支持

2,500 周安装

Keyboard navigation: All interactive elements reachable via Tab, activatable via Enter/Space

Focus management: Set focus to main content on route change, trap focus in modals

Color contrast: Minimum 4.5:1 for normal text, 3:1 for large text

Alt text: All <img> tags have descriptive alt (or alt="" for decorative images)

typeof window !== "undefined"

Memory leaks: Cancel async operations in useEffect cleanup. TanStack Query handles this automatically for queries.