К основному содержанию
скилл CX Codex

react-frontend-expert — скилл для Claude Code

Скилл react-frontend-expert задаёт правила вёрстки React-компонентов на TypeScript, создания кастомных хуков и работы с TanStack Query.

MIT 208 установок ★ 8 обновлён 2026-02-06

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add hieutrtr/ai1-skills --skill react-frontend-expert -a claude-code
Открыть на GitHub

Что делает react-frontend-expert

Скилл подключает набор строгих соглашений для фронтенда на стеке React 18+, TypeScript 5+, TanStack Query 5+, Vite 5+ и React Router 6+. Внутри собрана типовая структура каталогов с разделением на фичи, общие UI-компоненты и слой API-клиента.

По правилам скилла ассистент пишет только функциональные компоненты без React.FC, именует интерфейсы пропсов через {Component}Props и деструктурирует их прямо в аргументах. Ограничение по объёму — не больше 200 строк на компонент: всё, что крупнее, агент выносит в подкомпоненты или кастомные хуки вроде useDebounce, useAuth и usePagination. Запросы данных организуются через фабрику queryOptions, чтобы ключи кэша не пересекались.

Этот скилл рассчитан только на этап написания кода приложения: тестирование, E2E-сценарии и настройку CI/CD он напрямую исключает.

Какие задачи решает

  • Спроектировать архитектуру папок приложения на Vite и React Router
  • Описать кастомные хуки с изоляцией состояния и таймеров
  • Настроить запросы и мутации через TanStack Query с типизацией
  • Разбить разросшийся компонент на мелкие части без React.FC

Примеры запросов агенту

  • Создай хук usePagination для серверной пагинации по курсору
  • Собери компонент профиля пользователя и вынеси запросы в queryOptions
  • Разложи фичу авторизации по структуре проекта с формой и useAuth

Как установить react-frontend-expert

1Через Skills CLI (Vercel)

npx skills add hieutrtr/ai1-skills --skill react-frontend-expert -a claude-code

2Вручную: положить файлы

~/.claude/skills/react-frontend-expert/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/react-frontend-expert/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о react-frontend-expert

Как установить react-frontend-expert в Claude Code?

Выполните в терминале команду npx skills add hieutrtr/ai1-skills --skill react-frontend-expert -a claude-code.

Что делает react-frontend-expert?

Направляет ИИ-ассистента следовать единым паттернам React и TypeScript: писать лаконичные функциональные компоненты, правильно изолировать хуки и организовывать слой API.

Подходит ли скилл для написания тестов?

Нет, скилл сфокусирован только на реализации кода интерфейса, а для модульных и E2E-тестов авторы рекомендуют отдельные скиллы.

Исходный текст

SKILL.md · MIT
---
name: react-frontend-expert
description: >-
  React/TypeScript frontend implementation patterns. Use during the implementation phase
  when creating or modifying React components, custom hooks, pages, data fetching logic
  with TanStack Query, forms, or routing. Covers component structure, hooks rules, custom
  hook design (useAuth, useDebounce, usePagination), TypeScript strict-mode conventions,
  form handling, accessibility requirements, and project structure. Does NOT cover testing
  (use react-testing-patterns), E2E testing (use e2e-testing), or deployment.
license: MIT
compatibility: 'React 18+, TypeScript 5+, TanStack Query 5+, Vite 5+, React Router 6+'
metadata:
  author: platform-team
  version: '1.0.0'
  sdlc-phase: implementation
allowed-tools: Read Edit Write Bash(npm:*) Bash(npx:*)
context: fork
---

# 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

```tsx
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
1. Only call hooks at the top level — never inside loops, conditions, or nested functions
2. Only call hooks from React function components or custom hooks
3. Custom hooks must start with `use`

#### Custom Hook Patterns

**useDebounce:**
```tsx
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:**
```tsx
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:**
```tsx
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:

```tsx
// 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

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

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

```tsx
// 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

```tsx
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:

1. **Semantic HTML first:** Use `<button>`, `<nav>`, `<main>`, `<article>` — not `<div onClick>`
2. **Labels:** Every form input has a `<label>` with matching `htmlFor`/`id`
3. **ARIA only when needed:** `aria-label` for icon-only buttons, `aria-live` for dynamic updates, `role="alert"` for errors
4. **Keyboard navigation:** All interactive elements reachable via Tab, activatable via Enter/Space
5. **Focus management:** Set focus to main content on route change, trap focus in modals
6. **Color contrast:** Minimum 4.5:1 for normal text, 3:1 for large text
7. **Alt text:** All `<img>` tags have descriptive `alt` (or `alt=""` for decorative images)

## Examples

### User List Page with Search and Pagination

```tsx
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 `typeof window !== "undefined"`.

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

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

© platform-team · MIT · hieutrtr/ai1-skills

Похожие скиллы

Все скиллы по теме «Фронтенд и UI» →
vite-react-best-practices ant-gravity Скилл vite-react-best-practices задаёт агенту правила архитектуры, кэширования и деплоя для SPA на React 19 и Vite 8. Включается при сборке проекта, настройке роутинга или рефакторинге компонентов. CX Codex +1 670установок frontend-react-router-best-practices sergiodxa Скилл frontend-react-router-best-practices для Claude Code задаёт архитектурные правила React Router: переносит загрузку данных в loader и помогает писать параллельные запросы и безопасные формы. CX Codex +1 406установок react-vite-dashboard официальный google-labs-code Скилл react-vite-dashboard превращает макеты из Stitch в рабочий код дашборда на React и Vite. Он связывает дизайн-токены из DESIGN.md с кодом и подключает выборку данных через TanStack Query. CX Codex +1 7 100установок clerk-react-patterns clerk Скилл clerk-react-patterns для Claude Code и Codex помогает настроить авторизацию @clerk/react в SPA на базе Vite или Create React App. Задаёт провайдер, хуки сессии и защиту маршрутов. CX Codex +1 20 800установок react-frontend-development-expert Giuseppe Trisciuoglio Субагент react-frontend-development-expert, который берёт на себя React-фронтенд: компоненты, состояние, стили, доступность. Работает со стеком React 19, Vite, TypeScript, Tailwind CSS и shadcn/ui. CX Codex ★ 372звёзд репо react-query Mindrally Задаёт агенту правила работы с React Query: кэширование, фоновые обновления, инвалидация запросов и оптимистичные апдейты. CX Codex +1 1 500установок

Из того же набора8

e2e-testing Скилл e2e-testing задаёт шаблоны E2E-тестирования на Playwright для веб-приложений на React и Python. Помогает строить надёжные сквозные сценарии и Page Objects. CX Codex +1 1 600установок code-review-security Скилл code-review-security для Claude Code проверяет изменения кода на уязвимости и секреты. Запускается при ревью pull request, проверке авторизации и обработке пользовательского ввода. CX Codex +1 446установок react-testing-patterns Скилл react-testing-patterns задаёт правила тестирования компонентов и хуков React с помощью Testing Library, MSW и Vitest. Помогает писать надёжные проверки без привязки к деталям реализации. CX Codex +1 141установок python-backend-expert Скилл python-backend-expert задаёт паттерны бэкенда на FastAPI, SQLAlchemy 2.0 и Pydantic v2. Помогает писать асинхронные эндпоинты, репозитории и миграции Alembic. CX Codex +1 138установок system-architecture Скилл system-architecture помогает выбрать слои и границы модулей в связке FastAPI и React, а результат складывает в architecture.md и ADR. CX Codex +1 125установок ui-design-system Скилл ui-design-system задаёт единые правила для UI в React/TypeScript: токены, отступы, типографику и доступность. Нужен при создании и ревью компонентов. CX Codex +1 124установок pytest-patterns Скилл pytest-patterns для Claude Code помогает писать тесты Python-бэкенда на pytest. Он включается при работе с сервисами, репозиториями и API FastAPI. CX Codex +1 123установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой