RTD react-template

现代化 React 全家桶 Vite + React 19 + Tailwind v4 + shadcn/ui + oxlint + TanStack

技术栈

类别	选型
构建	Vite 6 + SWC
框架	React 19 + TypeScript 5.6
样式	Tailwind CSS v4(零配置)
组件	shadcn/ui(new-york)+ Radix Primitives
路由	TanStack Router(类型安全 + 文件路由)
数据	TanStack Query + Axios
状态	Zustand
表单	react-hook-form + Zod
动画	Framer Motion
反馈	Sonner(Toast)+ lucide-react(图标)
Lint	oxlint + oxlint-tailwindcss(比 ESLint 快 50-100×)
格式化	Prettier + prettier-plugin-tailwindcss
测试	Vitest + Testing Library + jsdom
Hooks	husky + lint-staged

快速开始

pnpm install        # 推荐 pnpm,也支持 npm/yarn/bun
pnpm dev            # 启动开发服务器(默认 http://localhost:5173)
pnpm build          # 生产构建
pnpm preview        # 预览构建产物
pnpm lint           # oxlint 检查
pnpm lint:fix       # oxlint 自动修复
pnpm format         # Prettier 格式化
pnpm test           # 单元测试

目录结构

src/
├── api/              HTTP 客户端(axios 实例 + 拦截器)
├── components/ui/    shadcn 基础组件(button/card/input/label)
├── hooks/            自定义 hooks(use-theme 等)
├── lib/utils.ts      cn() 工具
├── routes/           文件路由(TanStack Router)
│   ├── __root.tsx    根布局 + 主题切换
│   ├── index.tsx     首页(含表单示例)
│   └── about.tsx
├── index.css         Tailwind v4 + 主题 token(OKLCH)
└── main.tsx          入口

添加 shadcn 组件

pnpm dlx shadcn@latest add dialog dropdown-menu select sheet table

oxlint 配置说明

.oxlintrc.json 已启用以下 plugin:

• typescript react react-perf jsx-a11y import —— 替代 ESLint 主要规则
• tailwindcss —— Tailwind v4 类名校验、冲突检测、自动修复

主题

• 内置 light / dark 主题切换(右上角按钮)
• 颜色采用 OKLCH 色彩空间(感知均匀,Tailwind v4 推荐)
• 修改 src/index.css 中的 :root / .dark CSS 变量即可换肤

提交流程

git commit 时会自动:

1. lint-staged 仅检查改动文件
2. oxlint --fix 自动修复
3. prettier --write 格式化
4. 失败则阻止提交