React SSR 模板 —— Next.js 企业级基线

next-react-ssr 是 cwa-stack 的 React 服务端渲染模板。它基于 Next.js 16.3.5 App Router 与 React 19.3，适合需要首屏 HTML、SEO、服务端请求上下文或 Node.js 部署的项目。

核心能力

• SSR 默认开启：使用 Next.js App Router，Server Component 是默认组件类型。
• 清晰分层：路由入口位于 src/app，业务代码位于 src/features，共享能力位于 src/shared。
• 服务端边界：密钥、请求上下文和特权调用放在 src/server，避免进入客户端 bundle。
• 现代 UI：集成 shadcn/ui、Radix UI、Tailwind CSS 4、Heroicons 和 lucide-react。
• 完整质量门禁：内置 Vitest、Testing Library、MSW、jest-axe、Playwright、ESLint 和 TypeScript 检查。
• AI 协作约定：根目录提供 AGENTS.md，明确目录归属、SSR 安全规则和验证命令。

技术栈

分类	方案
SSR 框架	Next.js 16.3.5 App Router
UI 框架	React 19.3
开发语言	TypeScript
状态管理	Zustand
UI 与样式	shadcn/ui、Radix UI、Tailwind CSS 4、Sass
API	Axios
测试	Vitest、Testing Library、MSW、jest-axe、Playwright
工程规范	Next.js 官方 ESLint flat config、oxfmt、commitlint、simple-git-hooks

快速开始

运行时统一使用 Node.js 24 LTS（Krypton），支持范围为 >=24.11.0 <25，推荐使用最新 24.x。

npx cwa-stack create

? 请选择技术栈 React
? 请选择应用类型 SSR 服务端渲染
? 请选择模板 Next.js React SSR 企业级模板（next-react-ssr）

创建后进入项目并启动开发服务：

cd <项目名称>
pnpm install
pnpm dev

开发服务器默认运行在 http://localhost:3000。

项目结构

src/
├── app/               # App Router 布局、页面和路由状态
├── features/          # auth、docs 等业务模块
├── shared/            # API、基础组件、UI 和工具函数
├── server/            # server-only 请求上下文和特权调用
└── test/              # Vitest setup 与渲染工具
tests/e2e/             # Playwright E2E 用例

SSR 开发约定

• 默认编写 Server Component，只有交互组件或浏览器能力需要添加 "use client"。
• window、document、localStorage 和 sessionStorage 不得在服务端渲染路径直接执行。
• 模板通过 Route Handler 写入 HttpOnly Cookie，并由 proxy.ts 保护受限路由；接入业务时替换示例凭据校验。
• 业务请求通过 src/shared/api 发起，需要密钥或请求上下文的调用留在 src/server。
• 页面文件保持为薄入口，业务 UI 和逻辑放入对应的 src/features/<name>。

常用命令

命令	说明
pnpm dev	启动 Next.js 开发服务器
pnpm build	构建生产版本
pnpm preview	启动生产预览服务
pnpm test	运行单元与组件测试
pnpm test:coverage	运行覆盖率门禁
pnpm test:component-coverage	检查组件测试是否齐全
pnpm typecheck	执行 TypeScript 类型检查
pnpm lint	执行代码检查
pnpm test:e2e	运行 Playwright E2E

开发调试开关

默认关闭源码定位功能，可按需开启：

NEXT_ENABLE_CODE_INSPECTOR=true pnpm dev

NEXT_CODE_INSPECTOR_ACTION 可设置为 open、copy 或 both。

相关资源

• React SSR 模板仓库
• Next.js 文档
• React 文档
• shadcn/ui 文档

🔐 真实登录与契约（BFF）

React SSR 模板已与配套后端 springboot-template 形成真实登录闭环：

• 浏览器只与 BFF 会话 API（/api/session）交互：登录 POST、退出 DELETE；token 只存在于 HttpOnly Cookie auth_token 与服务端上下文，绝不进入浏览器 JS。
• BFF 调用真实后端 POST {BACKEND_API_BASE_URL}/login（服务端私有环境变量，禁止 NEXT_PUBLIC_* 暴露），Cookie Max-Age 不超过后端 expiresAt。
• 服务端请求通过 src/server/backend.ts 把 Cookie token 转换为 Authorization: Bearer；后端错误 Problem Details 顶层 code/msg/requestId 透传到浏览器。
• 会话 Mock 显式开启：ENABLE_AUTH_MOCK=true（演示账号 admin/admin），用于无后端本地开发与模板 E2E；真实后端 E2E 用 E2E_AUTH_MOCK=false + E2E_AUTH_USERNAME/E2E_AUTH_PASSWORD。
• 契约类型由 pnpm run api:generate 生成（openapi/api-contract.yaml → src/shared/api/generated），服务端统一从 src/server/contract.ts 导入。