modern-react-spa

ITHwang 的头像作者 ITHwang

引导生产就绪的React单页应用(SPA)项目。在创建新React应用程序、设置前端项目或用户请求具有类型安全路由、数据获取和状态管理的现代React项目时使用。触发于“创建React应用”、“新React项目”、“设置React SPA”、“Vite React”或类似的 frontend项目初始化请求。

📖 中文导读:引导生产就绪的React单页应用(SPA)项目。在创建新React应用程序、设置前端项目或用户请求具有类型安全路由、数据获取和状态管理的现代React项目时使用。触发于“创建React应用”、“新React项目”、“设置React SPA”、“Vite React”或类似的 frontend项目初始化请求。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: modern-react-spa description: Bootstrap production-ready React SPA projects. Use when creating new React applications, setting up frontend projects, or when user requests a modern React project with type-safe routing, data fetching, and state management. Triggers on "create React app", "new React project", "setup React SPA", "Vite React", or similar frontend project initialization requests.

Modern React SPA Architecture

Bootstrap type-safe, scalable React SPAs with: Vite, TypeScript (strict), TanStack Router, TanStack Query, Zustand, and Tailwind CSS.

Quick Start

Run these commands to initialize:

pnpm create vite@latest . --template react-ts
pnpm add @tanstack/react-router @tanstack/react-query zustand axios zod react-hook-form clsx tailwind-merge
pnpm add -D @tanstack/router-plugin tailwindcss @tailwindcss/vite eslint prettier

Core Architecture Rules

State Separation (Critical)

State Type Tool Example
Server State TanStack Query API data, user profiles, lists
Client State Zustand UI toggles, theme, auth tokens

Never put API responses in Zustand. Use Query hooks for all server data.

Routing

Use TanStack Router with file-based routing in src/routes/. Validate search params with Zod schemas in route files.

API Layer

All HTTP requests through src/lib/api.ts. Handle 401 globally via interceptors.

Directory Structure

src/
├── components/
│   ├── ui/           # Primitives (Button, Input) - shadcn
│   └── layout/       # Navbar, Sidebar, Footer
├── hooks/            # Global hooks (useMediaQuery, useDebounce)
├── lib/
│   ├── api.ts        # HTTP client with interceptors
│   ├── queryClient.ts
│   └── utils.ts      # cn() helper
├── routes/
│   ├── __root.tsx    # Root layout + providers
│   └── index.tsx     # Homepage
├── stores/           # Zustand stores
└── main.tsx

Implementation

For detailed setup instructions and boilerplate code, see:

Styling

Use Tailwind utilities. Combine dynamic classes with clsx + tailwind-merge:

import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";
export const cn = (...inputs: ClassValue[]) => twMerge(clsx(inputs));

Quality Gates

{
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "lint": "eslint src",
    "test": "vitest",
    "validate": "pnpm lint && tsc --noEmit && pnpm test"
  }
}