React Best Practices 是一份用于构建现代 React 与 Next.js 应用的综合指南，内容涵盖性能优化、组件架构、shadcn/ui 模式、Motion 动画、无障碍访问以及 React 19+ 特性。
适用时机
在以下场景中可参考这些准则：编写新的 React 组件或 Next.js 页面；实现数据获取（客户端或服务端）；使用 shadcn/ui 组件构建 UI；添加动画与微交互；审查代码质量与性能；重构现有 React/Next.js 代码；优化包体积或加载时间。
规则分类与优先级
指南按优先级将规则分为十类，每类带有前缀标识：
- 组件架构（关键，arch-）
- 消除瀑布流（关键，async-）
- 包体积优化（关键，bundle-）
- 服务端组件与 Actions（高，server-）
- shadcn/ui 模式（高，shadcn-）
- 状态管理（中高，state-）
- Motion 与动画（中，motion-）
- 重渲染优化（中，rerender-）
- 无障碍（中，a11y-）
- TypeScript 模式（中，ts-）
组件架构（关键）
快速参考规则包括：仅使用带 hooks 的函数组件；优先组合而非继承；单一职责；在有益时分离展示与容器；相关文件就近放置（组件、样式、测试）；避免深层 prop 传递，改用 Context 或组合。
关键原则：只使用函数组件，例如 function UserProfile({ userId }: { userId: string }) { const { data: user } = useUser(userId); return <div>{user?.name}</div> }，而非类组件。组合模式通过构建更小的组件实现，如 Card 与 CardHeader 组合使用。避免 prop drilling 时，应使用 Context 共享状态，例如 const UserContext = createContext<User | null>(null)，并在 Provider 中包裹组件树。
消除瀑布流（关键）
快速参考规则：将 await 移入实际使用的分支；对独立操作使用 Promise.all()；正确处理部分依赖；在 API 路由中尽早启动 Promise、延迟 await；使用 Suspense 流式传输内容。
瀑布流是首要性能杀手，每个顺序 await 都会增加完整网络延迟。应使用并行数据获取，例如 const [user, posts, comments] = await Promise.all([fetchUser(), fetchPosts(), fetchComments()])。同时可使用 Suspense 边界流式渲染内容，如 <Suspense fallback={<PostsSkeleton />}><Posts /></Suspense>。
包体积优化（关键）
快速参考规则：直接导入，避免 barrel 文件；对重型组件使用 next/dynamic；在水合后加载分析/日志；仅在功能激活时加载模块；在悬停/聚焦时预加载以提升感知速度。
避免 barrel 文件导入，应使用直接导入以启用 tree-shaking，例如 import { Button } from '@/components/ui/button' 而非 import { Button } from '@/components'。动态导入示例：const HeavyChart = dynamic(() => import('./HeavyChart'), { loading: () => <ChartSkeleton />, ssr: false })。
服务端组件与 Actions（高）
快速参考规则：组件默认是服务端组件；仅在需要时添加 'use client'；使用 Server Actions 处理变更；使用 React.cache() 进行每请求去重；最小化传递给客户端组件的数据。
服务端组件默认可为异步，例如 async function ProductPage({ id }: { id: string }) { const product = await db.product.findUnique({ where: { id } }); return <ProductDetails product={product} /> }。客户端组件仅在需要交互时使用 'use client'。Server Actions 示例：在 actions.ts 中 'use server'; export async function createPost(formData: FormData) { ... await db.post.create({ data: { title, content } }); revalidatePath('/posts') }，组件中通过 <form action={createPost}> 使用。
shadcn/ui 模式（高）
快速参考规则：基于现有 shadcn/ui 原语构建；使用 class-variance-authority 实现组件变体；使用 CSS 自定义属性进行主题化；利用 Radix 内置无障碍；修改复制的组件而非过度包装。
核心原则：开放代码（组件复制到项目中，完全可定制）、组合（每个组件使用通用可组合接口）、美观默认值、默认无障碍（基于 Radix UI 原语）。
组件安装命令：npx shadcn@latest add button、npx shadcn@latest add card、npx shadcn@latest add dialog、npx shadcn@latest add form。
构建自定义组件时优先组合，例如基于 Card、CardHeader、CardTitle、CardContent 和 Badge 构建 ProductCard。使用 CVA 定义变体，如 const statusBadgeVariants = cva('inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-semibold', { variants: { status: { pending: 'bg-yellow-100 text-yellow-800', active: 'bg-green-100 text-green-800', inactive: 'bg-gray-100 text-gray-800', error: 'bg-red-100 text-red-800' } }, defaultVariants: { status: 'pending' } })。
常见组件模式包括：使用 React Hook Form + Zod 构建表单（含 zodResolver、useForm、FormField 等）；Dialog/Modal 模式（Dialog、DialogTrigger、DialogContent、DialogHeader、DialogTitle、DialogDescription、DialogFooter）；使用 Tanstack Table 构建数据表格（useReactTable、getCoreRowModel、flexRender）。
状态管理（中高）
快速参考规则：本地状态优先使用 useState/useReducer；对不常变化的数据使用 Context；计算派生值而非存储；使用 URL 存储可分享/可收藏状态；服务端状态使用 SWR/TanStack Query。
避免派生状态，例如应使用 const count = items.length 而非单独存储 count。URL 状态用于筛选/分页，例如通过 useSearchParams 和 useRouter 设置 category 参数。
Motion 与动画（中）
快速参考规则：动画应增强 UX 而非分散注意力；使用 transform/opacity，避免触发布局；尊重 prefers-reduced-motion；使用 layoutId 实现共享元素过渡；使用 AnimatePresence 实现退出动画；定义可复用动画状态。
安装命令：npm install motion。Motion（原 Framer Motion）提供声明式动画。基础动画示例：<motion.div initial={{ opacity: 0, y: 20 }} animate={{ opacity: 1, y: 0 }} transition={{ duration: 0.3 }} className="rounded-lg border p-4">{children}</motion.div>。交互状态示例：<motion.button whileHover={{ scale: 1.02 }} whileTap={{ scale: 0.98 }} transition={{ type: 'spring', stiffness: 400, damping: 17 }} className="px-4 py-2 bg-primary text-primary-foreground rounded-md">{children}</motion.button>。
其他类别
指南还包含重渲染优化（rerender-）、无障碍（a11y-）和 TypeScript 模式（ts-）等类别，具体规则内容在提供的资料中未完整展开，暂未提供详细说明。
限制
资料未提供该指南的收费、价格、平台支持范围、效果保证或具体使用步骤等信息，暂未提供。