# react-template

**Repository Path**: monoplasty/react-template

## Basic Information

- **Project Name**: react-template
- **Description**: 一套基于 Vite 8 + React 19 + TanStack Router + TanStack Query + Tailwind v4 + shadcn/ui + Paraglide JS + lightningcss + Zustand + Axios + Biome + pnpm 的前端基线工程。
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-02
- **Last Updated**: 2026-04-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Frontend

一套基于 `Vite 8 + React 19 + TanStack Router + TanStack Query + Tailwind v4 + shadcn/ui + Paraglide JS + lightningcss + Zustand + Axios + Biome + pnpm` 的前端基线工程。

## 启动

```bash
pnpm install
pnpm dev
```

常用命令:

```bash
pnpm lint
pnpm typecheck
pnpm build

# 按需添加组件
pnpm dlx shadcn@latest add button
```

## 技术栈

- `Vite 8 + @vitejs/plugin-react-swc`: 构建与 React 编译
- `Tailwind CSS v4 + @tailwindcss/vite`: 样式层。文档地址: [https://tailwindcss.com/](https://tailwindcss.com/docs/flex)
- `shadcn/ui`: 组件基建与设计系统接入。文档地址: [https://ui.shadcn.com/](https://ui.shadcn.com/docs/components)
- `Paraglide JS`: 类型安全 i18n 编译方案。文档地址: [https://inlang.com/m/gerre34r/library-inlang-paraglideJs/basics](https://inlang.com/m/gerre34r/library-inlang-paraglideJs/basics)
- `lightningcss`: CSS transformer + minifier
- `@tanstack/react-router + @tanstack/router-plugin`: 类型安全文件路由。文档地址: [https://tanstack.com/router](https://tanstack.com/router/v1/docs/overview)
- `@tanstack/react-query`: 服务端状态与缓存。文档地址: [https://tanstack.com/query](https://tanstack.com/query/v4/docs/framework/react/overview)
- `axios`: 统一 HTTP transport
- `zustand + immer`: 客户端全局状态。文档地址: [https://zustand-demo.pmnd.rs/](https://zustand.docs.pmnd.rs/learn/getting-started/introduction)
- `@biomejs/biome`: format + lint + organize imports

## 目录职责

```txt
messages/                    # i18n 源文件
src/
├─ app/                      # providers、 context
├─ features/                 # 功能模块
│  ├─ auth/
│  │  ├─ api/                # queryOptions / request functions
│  │  ├─ model/              # 用户类型
│  │  └─ store/              # auth Zustand store
│  ├─ theme/
│  │  ├─ components/         # ThemeSync 副作用边界
│  │  └─ store/              # 主题偏好 store
│  └─ users/                 # 示例数据
├─ lib/                      # 项目依赖库：axios 实例、错误模型、env
├─ components/ui/            # shadcn/ui 基础组件
├─ paraglide/                # Paraglide 编译产物（不可编辑）
├─ routes/                   # TanStack Router 文件路由（基于文件的路由）存放页面路由。路由中的组件放在 features 下
├─ routeTree.gen.ts          # 路由生成文件（不可编辑）
└─ styles/
```

## 请求层最佳实践

核心原则:

- `axios` 负责 **HTTP 传输**
- `request()` 负责 **泛型封装与统一返回结构**
- `feature/api` 负责 **领域 API**
- `feature/hooks` 负责 **查询和 mutation 行为**
- 组件只面向 hooks

示例链路:

1. `src/lib/http.ts`
   统一 `baseURL`、`withCredentials`、超时、token 注入、`ApiError` 归一化。
2. `src/features/auth/api/current-user.ts`
   导出 `getCurrentUser()` 和 `currentUserQueryOptions()`。
3. `src/routes/dashboard.tsx`
   在 `loader` 里 `ensureQueryData(currentUserQueryOptions())` 预热缓存。
4. 组件内部再用 `useSuspenseQuery(currentUserQueryOptions())` 消费同一份缓存。

这样做的好处:

- 请求定义不重复
- 路由预取和组件读取使用同一份 query key / query fn
- 错误模型统一，不需要每个页面单独处理 AxiosError

## Zustand 最佳实践

这份基线刻意把 Zustand 的边界收得比较窄:

- `auth store`
  只保存当前会话快照和动作，例如 `status`、`user`、`accessToken`。
- `theme store`
  只保存 `preference: light | dark | system`，并持久化到 `localStorage`。
- `immer middleware`
  让 store action 直接以“可变写法”更新草稿状态，减少对象展开样板代码。
- `ThemeSync`
  负责把 store 状态同步到 `document.documentElement`，不把 DOM 副作用写进 store。

## i18n

- `project.inlang/settings.json`
  定义 Paraglide 项目、语言列表和本地 plugin 模块。
- `messages/*.json`
  保存翻译源文件。
- `src/paraglide`
  由 `pnpm paraglide:compile` 或 Vite plugin 自动生成，请勿手改。

不推荐的做法:

- 把 React Query 里的服务端数据整仓同步进 Zustand
- 在组件里散落写 `localStorage`
- 长期持久化敏感 access token


## TanStack Router 类型安全路由

当前项目使用文件路由，并已注册 Router 类型:

- `src/routes/users.$userId.tsx`
  展示动态参数 `userId` 的类型安全消费。
- `Link to="/users/$userId" params={{ userId }}`
  会在编译期校验路径参数。
- `beforeLoad`
  用于做鉴权 guard。
- `loader`
  用于预取 Query 数据。

## Mock API

为了让工程开箱即可运行，默认 `VITE_API_BASE_URL` 指向:

```txt
/mock-api
```

示例接口文件:

```txt
public/mock-api/auth/me.json
```

接真实后端时，通常只需要:

1. 新建 `.env`
2. 配置 `VITE_API_BASE_URL=http://your-api-host`
3. 把 `src/features/auth/api/current-user.ts` 中的 demo endpoint 改成真实 `/auth/me`

## 备注

- `src/routeTree.gen.ts` 是 TanStack Router 生成文件，建议提交到仓库。
- `Biome` 已排除 `routeTree.gen.ts`，避免对生成代码做无意义 lint。