- 文件作用
package.json
npm脚本部分"scripts"
项目启动与打包
"dev": "vite"
启动 开发环境,开启本地服务器,支持热更新。
用法:npm run dev
"build": "tsc && vite build --base=/"
先运行 TypeScript 编译 (tsc),再用 Vite 打包项目生成生产环境文件。
用法:npm run build
"preview": "vite preview"
本地预览打包后的生产环境效果,通常在 build 之后使用。
用法:npm run preview
测试相关
"test": "vitest"
运行 单元测试,Vitest 是 Vite 推荐的测试工具。
用法:npm run test
"test-e2e": "pm2 start "yarn run-mock-server" --name server && yarn playwright test"
运行 端到端测试(E2E):
用 pm2 启动一个 mock server(模拟后端接口)。
用 Playwright 运行测试脚本。
用法:npm run test-e2e
代码质量与类型检查
"lint": "eslint src --ignore-path .gitignore"
使用 ESLint 检查 src 目录下代码的规范和风格。
"check-types": "tsc --project tsconfig.json --pretty --noEmit"
用 TypeScript 检查类型错误,但不生成文件(--noEmit)。
工具与生成
"prepare": "husky"
配置 Husky,通常用于 Git 钩子(比如提交前自动 lint 或测试)。
"generate": "plop"
运行 Plop,用于 代码模板生成(比如快速生成组件或页面模板)。
Storybook 相关
"storybook": "storybook dev -p 6006"
启动 Storybook 本地开发环境,用于组件展示与开发。
"build-storybook": "storybook build"
打包 Storybook,为上线或共享准备静态页面。
Mock Server
"run-mock-server": "vite-node mock-server.ts | pino-pretty -c"
启动本地 mock server(用 Vite Node 运行 mock-server.ts),并用 pino-pretty 格式化日志。
依赖dependencies
- 核心框架
react / react-dom
React 核心库和 DOM 渲染库,必须依赖。
@vitejs/plugin-react
Vite 项目中支持 React 的插件,处理 JSX/TSX 和热更新。
- 状态管理
zustand
轻量状态管理库,用于全局状态存储。
@tanstack/react-query
数据请求与缓存管理库,优化网络请求与状态同步。
@tanstack/react-query-devtools
React Query 调试工具,帮助查看请求状态。
- 路由
react-router
React 官方路由库,用于单页应用的页面跳转与路由管理。
- UI 组件和样式工具
@radix-ui/react-* 系列
高可访问性的 UI 组件,如 Dialog、Dropdown、Switch、Label 等。
clsx
用于条件组合 className,常和 Tailwind CSS 一起使用。
tailwind-merge / tailwindcss-animate
Tailwind CSS 工具,优化类名合并与动画效果。
lucide-react
React 图标库。
- 表单和验证
react-hook-form
高性能表单库,易于验证和收集表单数据。
@hookform/resolvers
配合 zod 或 yup 进行表单验证。
zod
类型安全的验证库,用于表单或接口数据校验。
- HTTP 请求与工具
axios
HTTP 请求库,用于与后端接口通信。
dayjs
轻量日期处理库,类似 moment.js。
dompurify
安全处理 HTML,防止 XSS 注入。
nanoid
生成唯一 ID 的库。
marked
Markdown 解析为 HTML。
- 错误处理与优化
react-error-boundary
捕获 React 组件渲染中的错误,防止整个页面崩溃。
react-helmet-async
动态设置页面 meta 标签、标题等。
- 开发工具(devDependencies)
vite / typescript / eslint / prettier
构建、类型检查、代码规范、格式化。
vitest / playwright / @testing-library/react
单元测试与端到端测试。
storybook / plop
UI 组件开发与代码生成模板。
husky / lint-staged
Git 钩子,保证提交前代码质量。
开发阶段需要的依赖dev-dependencies
常见示例
类别 包 作用
构建工具 vite, webpack 编译、打包、热更新
类型检查 typescript TypeScript 类型检查
代码规范 eslint, prettier 检查和格式化代码
测试工具 vitest, jest, playwright 单元测试、端到端测试
组件开发 storybook, plop UI 组件展示或代码生成
Git 钩子 husky, lint-staged 提交前自动检查或格式化代码