frontend-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Frontend Architecture Selection

前端架构选型

Guides frontend technology stack selection and project scaffolding for new or empty projects.

指导新建或空白项目的前端技术栈选型和项目脚手架搭建。

Step 1: Clarify Requirements

步骤1：明确需求

Before recommending a stack, MUST ask (or infer from context):

Question	Options	Impact
Rendering mode	SPA / SSR / SSG / Hybrid	Determines framework
Content type	Dashboard / Landing / Docs / App	Determines UI library
SEO required?	Yes / No	SSR vs SPA decision
Backend API	REST / GraphQL / gRPC-Web	Data layer strategy
Team size	Solo / Small / Large	Monorepo strategy
Backend stack	Go / Node / Other	Type-safe client gen

在推荐技术栈之前，必须询问（或者从上下文推断）：

问题	选项	影响
渲染模式	SPA / SSR / SSG / 混合	决定开发框架
内容类型	后台面板 / 落地页 / 文档 / 应用	决定UI库选型
是否需要SEO？	是 / 否	影响SSR与SPA的选择决策
后端API类型	REST / GraphQL / gRPC-Web	决定数据层策略
团队规模	单人 / 小型 / 大型	决定monorepo策略
后端技术栈	Go / Node / 其他	影响类型安全客户端生成方案

Step 2: Recommended Default Stack

步骤2：推荐默认技术栈

When requirements are general-purpose (no strong constraints), recommend this stack:

Framework:      Next.js 15 (App Router)     # SSR + SPA hybrid, SEO-friendly
Language:       TypeScript 5.x (strict)     # Non-negotiable
Build:          Turbopack (built-in Next.js) / Vite (standalone SPA)
Styling:        Tailwind CSS v4
UI Components:  Ant Design v5
Global State:   Zustand
Server State:   TanStack Query v5
Forms:          React Hook Form + Zod
Package Mgr:    pnpm (preferred)
Testing:        Vitest + Testing Library + Playwright (E2E)
Linting:        ESLint v9 (flat config) + Prettier

当需求为通用型（无强约束）时，推荐以下技术栈：

Framework:      Next.js 15 (App Router)     # SSR + SPA hybrid, SEO-friendly
Language:       TypeScript 5.x (strict)     # Non-negotiable
Build:          Turbopack (built-in Next.js) / Vite (standalone SPA)
Styling:        Tailwind CSS v4
UI Components:  Ant Design v5
Global State:   Zustand
Server State:   TanStack Query v5
Forms:          React Hook Form + Zod
Package Mgr:    pnpm (preferred)
Testing:        Vitest + Testing Library + Playwright (E2E)
Linting:        ESLint v9 (flat config) + Prettier

Step 3: Scenario-Based Selection

步骤3：基于场景选型

Use the decision tree below, then see stacks.md for full matrices.

New Frontend Project
        │
        ├─ SEO / SSR required? ──────▶ Next.js 15 (App Router)
        │
        ├─ Content / Docs / Blog? ───▶ Astro 5
        │
        ├─ Vue team? ────────────────▶ Nuxt 3 (mirrors Next.js)
        │
        └─ General SPA ──────────────▶ React 19 + Vite + Ant Design v5

使用下方的决策树进行判断，完整技术栈矩阵可查看stacks.md。

New Frontend Project
        │
        ├─ SEO / SSR required? ──────▶ Next.js 15 (App Router)
        │
        ├─ Content / Docs / Blog? ───▶ Astro 5
        │
        ├─ Vue team? ────────────────▶ Nuxt 3 (mirrors Next.js)
        │
        └─ General SPA ──────────────▶ React 19 + Vite + Ant Design v5

Step 4: Confirm Stack & Update README.md

步骤4：确认技术栈并更新README.md

After the user confirms the tech stack, MUST update (or create) the project's

README.md

with a Tech Stack section.

Template to insert/append:

markdown

undefined

用户确认技术栈后，必须在项目的

README.md

中更新（或新增）技术栈板块。

可插入/追加的模板：

markdown

undefined

Tech Stack

Layer	Choice
Framework	<!-- e.g. Next.js 15 (App Router) -->
Language	TypeScript 5.x (strict)
Build	<!-- e.g. Turbopack / Vite -->
Styling	<!-- e.g. Tailwind CSS v4 -->
UI Components	<!-- e.g. Ant Design v5 -->
Global State	<!-- e.g. Zustand -->
Server State	<!-- e.g. TanStack Query v5 -->
Forms	<!-- e.g. React Hook Form + Zod -->
Package Manager	pnpm
Testing	Vitest + Testing Library + Playwright
Linting	ESLint v9 + Prettier


Rules:
- If `README.md` already exists: append the Tech Stack section; **do NOT overwrite** existing content.
- If `README.md` does not exist: create it with project name as heading and the Tech Stack section.
- Fill in each row with the actual confirmed choices, removing placeholder comments.

Layer	Choice
Framework	<!-- e.g. Next.js 15 (App Router) -->
Language	TypeScript 5.x (strict)
Build	<!-- e.g. Turbopack / Vite -->
Styling	<!-- e.g. Tailwind CSS v4 -->
UI Components	<!-- e.g. Ant Design v5 -->
Global State	<!-- e.g. Zustand -->
Server State	<!-- e.g. TanStack Query v5 -->
Forms	<!-- e.g. React Hook Form + Zod -->
Package Manager	pnpm
Testing	Vitest + Testing Library + Playwright
Linting	ESLint v9 + Prettier


规则：
- 如果`README.md`已存在：追加技术栈板块；**不要覆盖**现有内容。
- 如果`README.md`不存在：创建文件，以项目名为一级标题，追加技术栈板块。
- 用实际确认的选型填充每一行，移除占位注释。

Step 5: Go Backend Integration

步骤5：Go后端集成

When the backend is Go (common in this workspace):

Type-safe API client: Use Orval or Hey API to auto-generate TypeScript client from OpenAPI/Swagger spec — eliminates manual type definitions
Auth (JWT): Handle token refresh in TanStack Query's
```
defaultOptions
```
or axios interceptor
CORS: Confirm Go handler sets correct headers for the frontend origin

当后端技术栈为Go（本工作区常见场景）时：

类型安全API客户端：使用Orval或Hey API从OpenAPI/Swagger规范自动生成TypeScript客户端，无需手动编写类型定义
鉴权（JWT）：在TanStack Query的
```
defaultOptions
```
或axios拦截器中处理令牌刷新逻辑
跨域（CORS）：确认Go handler为前端源设置了正确的请求头

Step 6: Scaffold the Project

步骤6：搭建项目

After README.md is updated, run the appropriate init commands.
See templates/nextjs.md, templates/vite-spa.md, or templates/astro.md for exact commands.

更新完README.md后，运行对应的初始化命令。具体命令可查看templates/nextjs.md、templates/vite-spa.md或templates/astro.md。

Project Structure Convention

项目结构规范

Follow Feature-Sliced Design (aligned with Go Clean Architecture on the backend):

src/
├── app/          # App-level setup: providers, router, global styles
├── pages/        # Route-level components (or Next.js app/ dir)
├── features/     # Feature modules: each has ui/, model/, api/
├── shared/       # Reusable: ui components, lib, types, hooks
└── entities/     # Domain models (aligned with backend domain layer)

遵循特性切片设计（与后端的Go整洁架构对齐）：

src/
├── app/          # 应用层配置：全局 providers、路由、全局样式
├── pages/        # 路由级组件（或Next.js的app/目录）
├── features/     # 特性模块：每个模块包含 ui/, model/, api/
├── shared/       # 通用资源：UI组件、工具库、类型定义、自定义hooks
└── entities/     # 领域模型（与后端领域层对齐）

Code Quality Checklist

代码质量检查清单

TypeScript
```
strict: true
```
enabled in tsconfig
ESLint + Prettier configured with pre-commit hook (Husky + lint-staged)
Path aliases (
```
@/
```
) configured in tsconfig and build tool
Environment variables typed (e.g.
```
env.d.ts
```
or
```
t3-env
```
)
Zod schemas colocated with forms / API boundaries
TanStack Query keys in a central
```
queryKeys.ts
```
file
Tests: unit (Vitest), component (Testing Library), E2E (Playwright)

tsconfig中开启TypeScript
```
strict: true
```
配置ESLint + Prettier以及pre-commit钩子（Husky + lint-staged）
在tsconfig和构建工具中配置路径别名（
```
@/
```
）
环境变量添加类型定义（例如
```
env.d.ts
```
或
```
t3-env
```
）
Zod schema与表单/API边界代码放在同一目录
TanStack Query的key统一存放在
```
queryKeys.ts
```
文件中
测试覆盖：单元测试（Vitest）、组件测试（Testing Library）、端到端测试（Playwright）

Reference

参考资料

Full technology stack matrices → stacks.md
Next.js scaffold commands → templates/nextjs.md
Vite SPA scaffold commands → templates/vite-spa.md
Astro scaffold commands → templates/astro.md

完整技术栈矩阵 → stacks.md
Next.js脚手架命令 → templates/nextjs.md
Vite SPA脚手架命令 → templates/vite-spa.md
Astro脚手架命令 → templates/astro.md