技术栈分析与Cursor规则生成器

=================== --- description: 本规则概述了项目的技术栈、依赖版本及最佳实践，适用于所有文件。 globs: alwaysApply: true --- # 页面UI技术栈与依赖指南 ## 项目概览 **页面UI** 是一个基于现代React/Next.js技术栈的落地页组件库，包含： - **网站**：Next.js 14文档站点，包含组件演示 - **CLI工具**：`@page-ui/wizard`，用于快速初始化项目 - **组件**：基于Radix UI和Tailwind CSS的可复制粘贴React组件 ## 核心框架技术栈 ### **Next.js 14.2.24**（App Router） - **框架**：React元框架，采用App Router架构 - **使用特性**：API路由、SSG/SSR、OG图像生成、包分析 - **最佳实践**：使用App Router模式，避免使用pages目录 ### **React 18.2.0** - **UI库**：核心React库，支持并发特性 - **特性**：Suspense、自动批处理、服务端组件 - **最佳实践**：使用React 18模式 ### **TypeScript 5.1.3** - **配置**：启用严格模式以获得更好的类型安全性 - **最佳实践**：使用现代TypeScript版本 ## UI组件系统 ### **Radix UI原语**（v1.x系列） 完整的无障碍优先组件库生态系统： **最佳实践**： - 使用复合组件模式 - 始终使用Tailwind类进行自定义，而非内联样式 - 实现正确的ARIA属性（内置） - 包装在自定义组件中以实现一致的样式 ### **Shadcn/UI设计模式** - **位置**：`/components/shared/ui/`目录 - **理念**：复制粘贴组件，而非NPM依赖 - **样式**：Tailwind CSS + CSS变量用于主题化 - **变体**：使用`class-variance-authority`实现类型安全的变体 ## 样式与设计系统 ### **Tailwind CSS 3.3.3** + 生态系统 ```json { "tailwindcss": "^3.3.3", "@tailwindcss/forms": "^0.5.4", "@tailwindcss/typography": "^0.5.9", "tailwindcss-animate": "^1.0.7", "tailwind-merge": "^1.14.0" } ``` **最佳实践**： - 使用`tailwind-merge`处理条件类：`cn(baseClasses, conditionalClasses)` - 利用CSS变量进行主题化：`hsl(var(--primary))` - 使用插件处理表单和排版 - 实施一致的间距和颜色系统 ### **动画库** - **Framer Motion 10.16.4**：复杂动画、页面过渡 - **Tailwind Animate**：简单CSS动画 - **最佳实践**：简单效果使用CSS动画，复杂交互使用Framer Motion ```typescript // Framer Motion最佳实践： import { motion, AnimatePresence } from 'framer-motion' function AnimatedComponent() { return ( <motion.div initial={{ opacity: 0, y: 20 }} animate={{ opacity: 1, y: 0 }} exit={{ opacity: 0, y: -20 }} transition={{ duration: 0.3 }} > 内容 </motion.div> ) } ``` ## 状态管理与表单 ### **Zustand 4.5.2**（全局状态） - **理念**：极简、非固执己见的状态管理 - **用途**：主题偏好、全局UI状态、组件游乐场状态 - **最佳实践**：创建带正确选择器的类型化存储 ```typescript interface ThemeState { theme: 'light' | 'dark' setTheme: (theme: 'light' | 'dark') => void } export const useThemeStore = create<ThemeState>((set) => ({ theme: 'light', setTheme: (theme) => set({ theme }), })) ``` ### **React Hook Form 7.46.2** + 验证 - **表单库**：高性能、非受控表单 - **验证**：`@hookform/resolvers` ^3.3.1 + `zod` ^3.22.2 - **集成**：与Radix UI表单组件无缝协作 ```typescript // 最佳实践表单设置： const formSchema = z.object({ email: z.string().email(), name: z.string().min(2), }) function ContactForm() { const form = useForm<z.infer<typeof formSchema>>({ resolver: zodResolver(formSchema), }) return <form onSubmit={form.handleSubmit(onSubmit)}>...</form> } ``` ### **Zod 3.22.2**（模式验证） - **用途**：表单验证、API响应验证、类型生成 - **最佳实践**：在靠近使用处定义模式，利用类型推断 ## 内容管理系统 ### **自定义Contentlayer实现** ```json { "@shipixen/next-contentlayer-module": "1.0.2", "shipixen-contentlayer": "1.0.2", "@shipixen/pliny": "1.0.13" } ``` **特性**： - 类型安全的MDX处理 - Frontmatter解析 - 自动化内容导入 - RSS源生成 ### **MDX处理管道** **Remark插件**（Markdown处理）： - `remark-gfm` ^3.0.1：GitHub风格Markdown - `remark-math` ^5.1.1：数学表达式 **Rehype插件**（HTML处理）： - `rehype-slug` ^5.1.0：自动生成标题ID - `rehype-autolink-headings` ^6.1.0：自动链接标题 - `rehype-prism-plus` ^1.6.1：语法高亮 - `rehype-katex` ^6.0.3：数学渲染 **最佳实践**： - 在构建时处理内容，而非运行时 - 使用一致的插件版本以确保稳定构建 - 使用生成类型进行类型安全的内容查询 ## 开发体验 ### **代码质量工具** ```json { "eslint": "^8.45.0", "@typescript-eslint/eslint-plugin": "^6.1.0", "@typescript-eslint/parser": "^6.1.0", "eslint-config-next": "^14.2.24", "eslint-config-prettier": "^8.8.0", "prettier": "^3.0.0", "prettier-plugin-tailwindcss": "^0.4.1" } ``` **Git工作流**： - **Husky 8.0.0**：Git钩子自动化 - **lint-staged 13.0.0**：预提交时进行代码检查和格式化 ### **交互式开发工具** - **Monaco Editor 0.45.0**：用于组件游乐场的浏览器内代码编辑 - **命令面板**：`cmdk` ^0.2.0，用于全局搜索和导航 - **包分析器**：`@next/bundle-analyzer`，用于性能监控 ## CLI工具（@page-ui/wizard） ### **包配置** ```json { "name": "@page-ui/wizard", "type": "module", "bin": "./packages/cli/index.mjs", "engines": { "node": ">=14.17.0" } } ``` ### **CLI依赖** ```json { "chalk": "^5.3.0", // 终端颜色和样式 "commander": "^12.0.0", // 命令行界面框架 "enquirer": "^2.4.1", // 交互式CLI提示 "ora": "^8.0.1" // CLI加载动画 } ``` **最佳实践**： - 使用ESM模块（`.mjs`扩展名） - 使用enquirer提供交互式提示 - 使用ora显示加载动画 - 使用chalk保持终端样式一致 ## 分析与外部服务 ### **Vercel生态系统** - **分析**：`@vercel/analytics` ^1.1.1 - **OG图像**：`@vercel/og` ^0.5.20 - **最佳实践**：使用Vercel原生工具以获得最佳性能 ### **产品分析** - **PostHog 1.130.1**：功能标志、用户跟踪、A/B测试 - **最佳实践**：隐私合规设置，并正确管理用户同意 ### **HTTP客户端** - **Axios 1.7.7**：API调用、新闻通讯订阅 - **最佳实践**：创建带基础配置的axios实例 ## 工具库 ### **日期与时间** - **date-fns 2.30.0**：模块化日期工具库 - **最佳实践**：仅导入所需函数以实现树摇优化 ```typescript // 好：可树摇的导入 import { format, parseISO } from 'date-fns' // 差：完整库导入 import * as dateFns from 'date-fns' ``` ### **样式与UI工具** - **clsx 2.0.0**：条件className工具 - **class-variance-authority 0.7.0**：类型安全的组件变体 - **chroma-js 2.4.2**：颜色操作和主题生成 ### **数据展示** - **@tanstack/react-table 8.10.7**：强大的表格组件 - **lucide-react 0.400.0**：图标库 - **sonner 1.3.1**：Toast通知