/react-ts-template

一套基于react19、ts、vite6的项目模板,帮助快速搭建react项目。集成了一些项目规范,封装了axios、router路由懒加载等,配置了环境变量、scss样式全局变量等,集成了import顺序自动美化排序等插件。

Primary LanguageTypeScriptMIT LicenseMIT

中文 | English

GitHub 项目地址:React-Ts-Template

在现代前端开发中,我们常常需要快速搭建一个 React 项目。而 create-react-app 脚手架也已经很久不维护了,为了解决这一需求,React-Ts-Template 应运而生!这是一个基于最新的 React 19、TypeScript 和 Vite 6 打造的项目模板,旨在帮助你极速启动项目,节省大量重复的配置时间。同时,模板集成了各种开发规范和流行插件,开箱即用,让你专注于业务逻辑的实现!

功能配备

  • 路由懒加载:封装实现了路由懒加载,提升页面切换性能,减少初始加载时间。(详见router
  • 路由守卫:封装了灵活的路由守卫管理,确保用户访问权限控制,增强应用的安全性。(详见router
  • 全局状态管理:提供了 Zustand 全局状态管理示例代码,简化跨组件状态共享,提升开发效率。(详见store
  • Axios 请求封装:对 Axios 进行封装,统一处理 HTTP 请求和响应,简化与后端接口的交互流程。(详见services
  • 工具函数、hooks:提供了一些方便实用的工具函数和hooks。(详见utilshooks
  • react-dev-inspector集成:点击页面元素,IDE直接打开对应代码插件,方便开发者调试代码,提高开发效率。(详见vite.config.ts)
  • import顺序自动美化排序:集成了 prettier-plugin-sort-imports 插件,可以自动美化 import 顺序,提高代码的可读性和可维护性。
  • 其他:提供一些方便根据环境运行、打包的命令;配置了分包策略;本地反向代理解决跨域;还有详细的保姆级注释等等。

技术栈一览

🛠 技术栈选型

  • React 19 & React-DOM:使用最新版 React 实现前端高性能和更流畅的用户体验。
  • React-Router:最新v7版本,支持路由懒加载,优化页面切换性能。
  • SCSS 预编译:全面采用新版 SCSS,使用 @use 替代 @import,模块化更强。
  • ahooks:提供丰富的 React Hooks 类似 VueUse,进一步简化逻辑代码。
  • zustand:轻量级的状态管理库。通过对比 Redux、Dva、React-Toolkit、MobX,以及 useContext 结合 useReducer 的管理方式,最终选择了更简单的 Zustand。
  • Immer:简化不可变数据结构操作,尤其在多层次嵌套对象中处理更方便。
  • es-toolkit:一个现代的 JavaScript 实用库,提供了一系列强大的函数供日常使用,更小的体积、更好的性能(类似于lodash-es)。
  • Axios:封装 HTTP 请求库,更方便与后端接口对接。
  • classnames:动态类名管理工具,特别适合条件渲染样式。
  • Dayjs:轻量级的日期处理库,提供类似 Moment.js 的 API,但体积更小,性能更好。

🔧 其他推荐工具

  • Alova.js:新一代请求工具,便于请求数据管理。
  • SWR:数据请求缓存和同步管理的另一选择。

项目规范与配置

为确保团队合作时的代码一致性和规范性,React-Ts-Template 引入了一整套项目规范:

  • 全面使用 ESM 规范:采用模块化导入,符合现代 JavaScript 的发展趋势。
  • 包管理器强制使用 pnpm:提高依赖安装速度,减少磁盘空间占用,解决幽灵依赖问题。
  • 样式 BEM 命名规范:结构清晰,减少样式冲突,提升代码可维护性(为了方便样式穿透,并没有采用CSS Modules,需要的也可以自行使用xxx.module.scss)。
  • 文件与文件夹命名:统一使用 kebab-case,这种最可靠,尤其是在版本控制共享代码时,不同操作系统对大小写的敏感性不同。

💡 高效的代码规范管理

除了代码结构的规范化,项目还集成了多种代码质量检查工具,确保开发体验与代码质量:

  • ESLint:代码风格和错误检查,已升级到最新版,弃用 .eslintignore,改用 ignores 配置项。
  • Prettier:统一代码格式,避免团队协作中因格式问题产生的冲突。
  • Stylelint:针对样式的 Lint 工具,确保 SCSS 代码的一致性。
  • Commitlint + Husky + Lint-Staged:配合 Git Hooks 实现代码提交规范化,避免低质量代码入库。
  • EditorConfig:编辑器的统一配置,减少因编辑器差异产生的问题。

项目结构

├── .vscode # VSCode 编辑器配置文件夹
│   └── settings.json # VSCode 编辑器的具体设置
│   └── extensions.json # VSCode 推荐插件
├── .husky # Husky 配置文件夹,用于管理 Git 钩子
│   └── commit-msg # 检查提交钩子配置
│   └── pre-commit # 格式化钩子配置
├── .github # GitHub 特定配置和工作流文件夹
│   └── workflows # GitHub Actions 工作流配置
│       └── deploy.yml # 持续集成配置文件
├── public # 静态资源目录,用于存放不经过 Vite 处理的静态资源
├── src # 源代码目录
│ ├── assets # 静态资源文件,如图片、字体等
│ ├── components # 公共组件目录
│ │ ├── high-light # 代码高亮组件
│ │ └── auto-scroll-to-top # 自动滚动到页面顶部组件
│ │ └── ...
│ ├── hooks # 自定义 React Hooks
│ │ └── use-design # 设计相关的自定义 Hook
│ │ └── ...
│ ├── layouts # 页面布局组件
│ ├── views # 页面组件
│ ├── router # 路由配置
│ │ └── utils # 路由相关工具函数
│ │ └── ...
│ ├── services # API 服务封装
│ ├── store # 状态管理
│ │ └── modules # 状态管理模块
│ │ │ └── use-loading-store.ts # 计数loading状态管理
│ │ └── ...
│ ├── styles # 样式
│ ├── types # TypeScript 类型定义
│ └── utils # 工具函数
├── .env # 环境配置文件
├── .editorconfig # 编辑器配置文件,用于统一不同编辑器的代码风格
├── eslint.config.js # ESLint 配置文件,用于代码风格和错误检查
├── .prettierrc.js # Prettier 配置文件,用于代码格式化
├── stylelint.config.js # Stylelint 配置文件,用于样式文件的风格和错误检查
├── .commitlintrc.js # Commitlint 配置文件,用于 Git 提交信息的风格检查
├── lint-staged.config.js # Lint-Staged 配置文件,用于在 Git 提交前自动运行 Linters
├── package.json # 项目依赖配置文件
├── tsconfig.json # TypeScript 配置文件
└── vite.config.ts # Vite 配置文件,用于定义 Vite 项目的构建和服务选项

其他

📦 关于路由缓存 keep-alive

React 官方暂时没有实现 vue <keep-alive> 类似的功能。React 官方出于两点考虑拒绝添加这个功能,具体可以自行搜索查阅。为了达到状态保存的效果,官方推荐以下两种手动保存状态的方式:

  • 将需要保存状态组件的 state 提升至父组件中保存。
  • 使用 CSS visible 属性来控制需要保存状态组件的渲染,而不是使用 if/else,以避免 React 将其卸载。

不过也有一些相关库实现了这个功能,如:react-router-cache-route、react-activation、keepalive-for-react等等,如果项目中需要状态缓存处理的数据量较小,那最好还是按照 React 官方的建议,手动解决状态缓存问题。


总结

React-Ts-Template 项目模板的目标是通过预设的最佳实践配置,减少开发者在项目初始化时的琐碎配置步骤,让你可以更快上手项目开发。同时,配备了成熟的开发工具链和强大的插件支持,以确保团队开发的一致性和代码的高质量。如果你正在寻找一款高效的 React 项目模板,不妨试试 React-Ts-Template

👉 赶快 Star 项目,开启你的 React 项目之旅!

React-Ts-Template

注意

1.目前有一些ui库还未支持React19,注意甄别安装使用。
2.本项目并未使用19版本的相关特性,如需要,可以直接使用如下命令降级到18版本。

pnpm install react@18.3.1 react-dom@18.3.1