基于React和Vite的生产级TypeScript项目启动模板教程

作为开发者，我们经常发现自己在开始新项目时需要设置相同的工具和配置。为了解决这个挑战，我创建了一个完全类型安全的 React + Vite 模板，它可以作为生产就绪的 web 应用程序的良好起点，并且具有很好的扩展性。

这个模板是为了满足工作中的新项目标准化需求而产生的，重点放在开发体验、代码质量和可扩展性上。接下来我会告诉你这个模板的特点以及如何用它来启动你的下一个项目。

🚀 利用 Vite 实现飞速开发
💪 完整的 TypeScript 支持
🗂️ 结构清晰的项目
🔒 内置 JWT 认证
📡 现代数据获取，使用 Tanstack React Query
🗃️ 使用 Zustand 进行状态管理
🛣️ 使用 Tanstack Router 实现类型安全的文件路由
🌐 支持国际化 (i18n)
📝 表单处理，使用 React Hook Form + Zod
🎨 使用 Tailwind CSS 和 shadcn/ui 构建 UI 组件
📚 通过 Storybook 提供组件文档
✅ 使用 Vitest、Cypress 和 MSW 进行全面测试

• Node.js 20+（基于 Chrome V8 引擎的 JavaScript 运行时环境）
• npm（Node.js 包管理和分发平台）
• git（版本控制系统）

安装

    # 克隆仓库
    git clone https://github.com/singhAmandeep007/react-vite-boilerplate.git

    # 进入文件夹
    cd react-vite-boilerplate

    # 移除 .git 文件夹（以及你可能不需要的任何其他文件、文件夹或依赖项）
    rm -rf .git

    # 安装依赖
    npm install

    # 初始化 git 和 husky
    npm run prepare

    # 启动开发服务器，就这些
    npm run dev

进入全屏 退出全屏

这个项目的组织方式是怎么样的

    ├── .storybook
    ├── cypress
    │   ├── downloads
    │   ├── fixtures
    │   ├── specs
    │   ├── support
    |   └── tsconfig.json
    ├── env
    ├── public
    ├── src
    │   ├── __mocks__
    │   ├── app
    │   │   ├── auth.ts
    │   │   ├── App.ts
    │   │   └── router.ts
    │   ├── assets
    │   ├── api
    │   │   ├── auth
    │   │   ├── posts
    │   │   ├── user
    │   │   └── apiService.ts
    │   ├── components
    │   │   ├── forms
    │   │   ├── hooks
    │   │   ├── layout
    │   │   ├── ui
    │   │   └── developmentTools.tsx
    │   ├── config
    │   ├── mocker
    │   ├── modules
    │   │   └── i18n
    │   ├── pages
    │   │   ├── app
    │   │   ├── home
    │   │   └── auth
    │   ├── routes
    │   ├── store
    │   │   └── auth
    │   ├── tests
    │   ├── types
    │   ├── utils
    │   └── index.css
    │   └── main.tsx
    ├── index.html
    ├── .editorconfig
    ├── eslint.config.js
    ├── prettier.config.js
    ├── cypress.config.js
    ├── tailwind.config.js
    ├── .gitignore
    ├── tsconfig.json
    ├── vite.config.ts
    └── package.json

全屏 退出全屏

重要文件夹及其用途

根目录 (gēn mùlù)

• .storybook/: 包含用于构建和独立测试 UI 组件的工具 Storybook 的配置文件。

• cypress/: 包含配置与文件，用于端到端测试。

• downloads/: 存放测试过程中的临时下载文件。

• fixtures/: 用于测试的模拟数据。

• specs/: Cypress 的测试用例。

• support/: 自定义命令和可重用配置。

• tsconfig.json: 专门针对 Cypress 的 TypeScript 配置。
• env/: 环境特定的文件（例如 .env.development, .env.production）。
• public/: 公共可访问的资产，例如图片或静态文件。
• index.html: 应用程序的入口文件。

• 代码检查、格式化和构建工具的配置文件：

• .editorconfig, eslint.config.js, prettier.config.js

• tailwind.config.js: Tailwind CSS 配置。

• vite.config.ts: Vite 配置。

• tsconfig.json: TypeScript 配置。

src 目录
src 目录包含了应用程序的核心：

• __mocks__/: 用于测试的模拟文件。
• app/: 应用级配置，如提供者（例如 React Query、Router 等）。
• api/: 按相关端点组织的 API 文件夹。
• assets/: 存储应用静态资源的文件夹。

• components/:

• forms/: 可重用表单组件，如输入字段或按钮。

• hooks/: 自定义 React 钩子。

• layout/: 与应用布局相关的组件（如头部、尾部）。

• ui/: 可重用的 UI 组件（如按钮、卡片）。

• developmentTools.tsx: 用于本地开发的工具或实用程序，例如 react query devtools。
• config/: 配置文件，如 API 基础 URL 或环境设置。
• mocker/: 开发期间用于模拟 API 响应和其他实用程序的文件夹。

• modules/:

• i18n/: 国际化配置和翻译文件。

• pages/: 顶层页面，通常与路由相对应。

• App/: 与主应用相关的页面（如仪表盘、设置等）。

• Home/: 首页或登陆页。

• Auth/: 与认证相关的页面（如登录、注册等）。
• routes/: 使用 Tanstack 路由器的应用文件级路由配置。

• store/: 按领域组织的全局状态管理文件夹。

• auth/: 认证的状态管理逻辑。
• tests/: 单元测试的实用函数和包装器。
• types/: 共享的 TypeScript 类型和接口。
• utils/: 可重用的实用函数和辅助函数。
• index.css: 全局 CSS 或 Tailwind 导入。
• main.tsx: 应用入口点，用于初始化 React 并渲染应用。

实现认证

这里包含了一个完整的JWT认证配置，展现了最佳实践。

数据流动

• 使用 ky 进行 API 请求，以支持现代 HTTP 客户端功能。Ky 允许通过钩子来修改请求的生命周期。
• 使用 React Query 处理请求和响应以实现缓存和同步
• 通过 Zustand 管理身份验证状态和用户数据
• 使用 Tanstack Router 来实现受保护的路由

锅炉配备一套完整的测试配置：

• 单元测试：Vitest + React Testing Library
• 端到端测试（E2E）：Cypress
• API 模拟（API Mocking）：模拟服务工作者 (MSW)

单测

    npm run test:unit

    # 或者带有覆盖率统计
    npm run test:unit:coverage

    # 或者开启监听模式
    npm run test:unit:watch

    # 或者切换到UI模式
    npm run test:unit:ui

（进入全屏）（退出全屏）

应用程序已配置使用 vitest 来运行类型测试，这些测试默认情况下被视为位于 *.test-d.ts 文件中的类型测试。

端到端(E2E)测试

    npm run test:e2e

    # 或者以无头模式运行命令
    npm run test:e2e:headless

全屏模式（按ESC退出）

• 开发工具

• @tanstack/react-query-devtools — 专为帮助可视化 React Query 内部工作原理的开发工具

• @tanstack/router-devtools — 专为帮助可视化 TanStack Router 内部工作原理的开发工具

• @hookform/DevTools — 用于调试表单验证问题的 React Hook Form 开发工具

• 代码质量

• ESLint 用于代码规范检查
• Prettier 用于代码美化
• husky 用于 Git 钩子
• commitizen + devmoji 用于标准化提交信息

• 提交前的自动化检查

• 在每次提交前自动执行，代码检查工具会自动运行以下检查：

• 代码格式检查

• 类型检查

• 代码风格校验

该项目包含了 GitHub Actions 的工作流，包括：

• 持续集成（CI）

• 运行端到端测试（E2E测试）

• 代码质量审核
  *, 持续部署,

• 实现自动部署到生产环境

这个脚手架旨在为你的 React 项目提供坚实的基础，同时保持灵活性。它集成了现代工具和最佳实践，而不过于偏向任何特定做法，让你可以根据具体需求进行调整。

• 克隆代码库
• 查看演示实现代码
• 根据您的项目需求自定义它
• 提供反馈或进行贡献

记住，并不是所有设计都适合每个人，所以您可以根据自己的需要随意调整。

你的意见和帮助非常受欢迎！随时欢迎在 GitHub 上提出问题或提交拉取请求。

• GitHub 仓库。
• 在线示例。
• README

反馈和问题总是受欢迎，我很感激任何愿意看看这个项目的朋友们。

祝你的下一个项目一路顺利，好运!