# vite-react19-ts-template

**Repository Path**: SuHangWeb/vite-react19-ts-template

## Basic Information

- **Project Name**: vite-react19-ts-template
- **Description**: React 19 + Vite + TypeScript 集成模板，集成【Zustand 模块化、路由守卫（Auth / Guest）、Axios 请求封装与拦截器、TanStack Query、React Hook Form + Zod、Tailwind CSS + CSS Modules】
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-06
- **Last Updated**: 2026-04-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# react19-template

基于 [Vite](https://vite.dev/) 驱动的 **React 19** 集成模板，TypeScript 全量覆盖，适合中后台与产品型 H5。

## 特点

- 🛣 **Router**：使用 [React Router v7](https://reactrouter.com/)，`AuthGuard` / `GuestGuard` 模块化路由守卫，登录态与重定向可配置。
- 📦 **Store**：使用 [Zustand](https://zustand-demo.pmnd.rs/) 按模块拆分状态；用户会话与 `localStorage` 同步，供守卫与请求头读取（可按需接入持久化插件）。
- 🌐 **Request**：使用 [Axios](https://axios-http.com/) 单例封装，`baseURL` 随环境变量切换；请求/响应拦截、业务 `{ code, data }` 解包可在此统一处理。
- 🔄 **Server State**：集成 [TanStack Query v5](https://tanstack.com/query) 管理异步数据缓存；提供 `useApiQuery` / `useApiMutation` 快捷封装，亦推荐 `api/modules` + `useQuery` 组合。
- ✅ **校验**：使用 [Zod](https://zod.dev/) 做表单/协议校验（示例见登录页）。
- 📝 **表单**：可选 [React Hook Form](https://react-hook-form.com/)，与 Zod 搭配方便扩展。
- 💅 **样式**：**Tailwind CSS v4** + **CSS Modules** 混用；全局变量与移动端优先布局见 `src/assets/styles/`。
- 🧭 **路径别名**：`@` → `src`（Vite + TS 已对齐）。
- 📖 **教程页**：内置「状态」「API」示例路由，配套 `SNIPPETS.md` / `snippets.ts` 便于复制粘贴。

## 技术栈摘要

| 类别     | 选型 |
|----------|------|
| 运行时   | React 19、TypeScript 5.9 |
| 构建     | Vite 8 |
| 路由     | react-router-dom 7 |
| 状态     | zustand 5 |
| 请求     | axios 1.x |
| 异步数据 | @tanstack/react-query 5 |

## 使用方法

### 安装依赖

```bash
pnpm install
# 或
npm install
# 或
yarn
```

### 本地开发

**请在包含 `package.json` 的项目根目录执行**（例如 `react19-template/`）：

```bash
pnpm dev
# 或
npm run dev
# 或
yarn dev
```

### 构建

```bash
pnpm run build:prod   # 生产（mode production）
pnpm run build:dev    # 预发/测试（mode build-dev，需对应 .env）
```

### 代码检查

```bash
pnpm run lint
```

### 环境变量

- `.env.development`：本地开发（如 `VITE_API_BASE_URL`）
- `.env.production`：生产构建
- `.env.build-dev`：`build:dev` 使用

变量需以 `VITE_` 开头方可在前端代码中通过 `import.meta.env` 访问。

## 目录结构

整棵目录树如下（`#` 后为简要说明）：

```text
react19-template/
├── public/                              # 静态资源，构建时原样输出
│   ├── favicon.svg
│   ├── icons.svg
│   └── logo.svg
├── index.html
├── package.json
├── vite.config.ts                       # Vite：别名 @、dev 代理等
├── postcss.config.js
├── tailwind.config.js
├── tsconfig.json
├── tsconfig.app.json
├── tsconfig.node.json
├── .env.development                     # 本地开发
├── .env.production
├── .env.build-dev                       # pnpm run build:dev
├── README.md
└── src/
    ├── main.tsx                         # 入口：QueryClient、Router、全局样式
    ├── App.tsx                          # 根布局：Suspense + Outlet
    ├── vite-env.d.ts
    ├── api/                             # HTTP 接口（按业务拆模块）
    │   ├── index.ts                     # 统一导出
    │   ├── types.ts
    │   └── modules/
    │       ├── user.ts
    │       ├── goods.ts
    │       └── demo.ts                  # 教程演示接口
    ├── assets/
    │   ├── images/
    │   ├── styles/
    │   │   ├── global.css               # Tailwind + 全局样式
    │   │   └── variables.css            # CSS 变量
    │   └── fonts/
    ├── components/
    │   ├── common/                      # 通用：Button、Input、Empty…
    │   │   ├── Button/
    │   │   ├── Input/
    │   │   └── Empty/
    │   └── business/                    # 业务复用：UserCard、GoodsList…
    │       ├── UserCard/
    │       └── GoodsList/
    ├── constants/
    │   └── demoAuth.ts                  # 演示账号等常量
    ├── hooks/
    │   ├── index.ts
    │   ├── useAuth.ts
    │   ├── useDebounce.ts
    │   └── useRequest.ts                # useApiQuery / useApiMutation
    ├── pages/
    │   ├── Home/
    │   ├── User/
    │   │   ├── Login/
    │   │   └── Profile/
    │   ├── Tutorial/
    │   │   ├── Api/                     # API、React Query 说明与演示
    │   │   └── Store/                   # Zustand；snippets.ts、SNIPPETS.md
    │   └── NotFound/
    ├── router/
    │   ├── index.ts
    │   ├── app-router.tsx               # RouterProvider
    │   ├── routes.tsx                   # 路由表
    │   ├── routerGuard.tsx              # AuthGuard、GuestGuard
    │   └── pages.ts                     # 懒加载页面
    ├── store/
    │   ├── index.ts
    │   ├── types.ts
    │   └── modules/
    │       ├── userStore.ts             # 用户、token，与 storage 同步
    │       └── appStore.ts              # 主题、侧栏等 UI 状态
    ├── types/
    │   ├── env.d.ts
    │   └── global.ts
    └── utils/
        ├── index.ts
        ├── request.ts                   # axios 单例与拦截器
        ├── storage.ts
        ├── format.ts
        ├── validate.ts                  # Zod 辅助
        └── sessionToken.ts
```

## 许可

私有模板自用即可；开源发布时请自行补充 LICENSE。