Bulletproof React Next.js App 应用本地运行指南环境配置、Mock Server 与开发工作流【免费下载链接】bulletproof-react️ ⚛️ A simple, scalable, and powerful architecture for building production ready React applications.项目地址: https://gitcode.com/GitHub_Trending/bu/bulletproof-react本文基于apps/nextjs-app子应用的官方 README 展开讲清如何从零把 Bulletproof React 的 Next.js App Router 示例应用跑起来前置环境要求、.env环境变量体系、Mock API Server 的启动原理以及yarn dev背后的目录结构与关键脚本。读完你可以独立启动该应用、理解四个环境变量的校验机制并根据 package.json 中的脚本清单完成日常开发、测试与构建。前置条件与初始化步骤官方 README 给出的启动前提非常明确Node 20Yarn 1.22初始化命令如下git clone https://gitcode.com/GitHub_Trending/bu/bulletproof-react.git cd bulletproof-react cd apps/nextjs-app cp .env.example .env yarn install从 package.json 的依赖声明看当前应用运行在Next.js 14App Router React 18.3 TypeScript 5.4之上状态层使用 TanStack Query 与 ZustandUI 层基于 Radix UI 与 Tailwind CSS这也是仓库整体架构单向数据流、特征模块化在 App Router 下的落地形态cp .env.example .env这一步不能跳过应用启动时会用 Zod 对必填环境变量做校验缺变量会直接抛错下文详述。仓库提供的 .env.example 内容如下NEXT_PUBLIC_API_URLhttp://localhost:8080/api NEXT_PUBLIC_ENABLE_API_MOCKINGfalse NEXT_PUBLIC_MOCK_API_PORT8080 NEXT_PUBLIC_URLhttp://localhost:3000环境变量体系四个变量的作用与 Zod 校验这组变量全部以NEXT_PUBLIC_前缀定义意味着它们会暴露给客户端 bundle。仓库中 .env.example-e2e 则用于 Playwright E2E 场景两者取值相同。真正的校验与解析逻辑集中在 src/config/env.ts。它把所有NEXT_PUBLIC_*变量映射到内部命名后用一个 Zod schema 做运行时校验// src/config/env.ts节选 const EnvSchema z.object({ API_URL: z.string(), // 必填无默认值 ENABLE_API_MOCKING: z .string() .refine((s) s true || s false) .transform((s) s true) .optional(), APP_URL: z.string().optional().default(http://localhost:3000), APP_MOCK_API_PORT: z.string().optional().default(8080), });由此可以整理出各变量的取值约束环境变量内部键必填默认值用途NEXT_PUBLIC_API_URLAPI_URL是无前端所有请求的 API 基地址README 中的http://localhost:8080/api即来源于此NEXT_PUBLIC_ENABLE_API_MOCKINGENABLE_API_MOCKING否无可选布尔字符串true时启用浏览器端 MSW Service Worker 拦截用于演示/联调NEXT_PUBLIC_URLAPP_URL否http://localhost:3000应用自身地址同时作为 Mock Server 的 CORS 白名单来源NEXT_PUBLIC_MOCK_API_PORTAPP_MOCK_API_PORT否8080Mock API Server 的监听端口ENABLE_API_MOCKING通过refine强制取值只能是true或false并transform成真正的布尔值避免了字符串false被当真值的经典坑。校验失败时createEnv()会抛出形如Invalid env provided.的错误并逐条列出缺失或非法的字段名——这就是为什么 README 要求先cp .env.example .env。Mock Server先于应用启动的 API 层README 特别强调先启动 Mock Server再运行应用Mock Server 监听http://localhost:8080/api。对应的脚本是yarn run-mock-server从 package.json 看它执行的是tsx ./mock-server.ts。mock-server.ts 的完整实现值得逐行看它把 MSW 的 handler 复用到 Node 侧从而让开发环境拥有一个“真实”的后端// mock-server.ts节选 const app express(); app.use(cors({ origin: process.env.NEXT_PUBLIC_URL, credentials: true })); app.use(express.json()); app.use(logger({ level: info, redact: [req.headers, res.headers], /* pino-pretty 彩色输出 */ })); app.use(createMiddleware(...handlers)); initializeDb().then(() { app.listen(process.env.NEXT_PUBLIC_MOCK_API_PORT, () { console.log(Mock API server started at http://localhost:${process.env.NEXT_PUBLIC_MOCK_API_PORT}); }); });这里有几个设计细节CORS 只放行NEXT_PUBLIC_URL且携带凭证credentials: true与 Mock Server 处理基于 Cookie 的会话认证相配套日志脱敏pino-http通过redact: [req.headers, res.headers]隐藏请求/响应头避免把 Cookie 打印到终端数据持久化Mock Server 使用mswjs/data建模。从 src/testing/mocks/db.ts 看定义了user、team、discussion、comment四个模型主键均为nanoid在 Node 环境下数据写入工作目录的mocked-db.json文件持久化在浏览器端则落到localStorage的msw-db键中initializeDb()负责启动时把持久化数据灌回内存模型因此重启 Mock Server 后数据仍在。MSW 的 handler 集合同样可复用src/testing/mocks/handlers/index.ts 聚合了auth、comments、discussions、teams、users五组 handler并额外提供一个${env.API_URL}/healthcheck探活端点带networkDelay模拟网络延迟。而 src/testing/mocks/browser.ts 中的setupWorker(...handlers)则服务于NEXT_PUBLIC_ENABLE_API_MOCKINGtrue时的浏览器端拦截public/mockServiceWorker.js 即对应 worker 文件。同一份 handler 同时驱动 E2E 测试与 Mock Server是本仓库“测试即契约”的体现。yarn dev开发模式与路由结构README 中yarn dev一步对应next dev启动后访问 http://localhost:3000。结合 src/config/paths.ts 的集中式路由定义本地可见的页面布局为/— 落地页/auth/login、/auth/register— 认证页支持?redirectTo查询参数/app— 仪表盘登录后/app/discussions、/app/discussions/[discussionId]— 讨论列表与详情/app/users、/app/profile— 用户管理需管理员权限与个人资料/public/discussions/[discussionId]— 无需登录即可访问的公开讨论对应源码位于 src/app 目录按app/auth/public三个路由组划分页面page.tsx与业务组件_components/分目录存放。全局 Provider 在 src/app/provider.tsx 中装配ErrorBoundary→QueryClientProvider→Notifications并在开发环境挂载 React Query Devtools。前端所有 HTTP 调用统一走 src/lib/api-client.ts 的api封装get/post/put/patch/delete。它会自动拼接env.API_URL前缀、序列化查询参数、默认cache: no-store在服务端运行时还会动态导入next/headers把当前请求的 Cookie 原样转发给 Mock APIgetServerCookies并开启credentials: include以维持会话。请求失败时客户端会调用 Zustand 通知存储弹出错误通知并抛出错误供 TanStack Query 接管——这套调用链正是 Mock Server 存在的意义应用前后端分离时仍有一个行为一致、数据可持久化的 API 可对接。完整脚本清单日常开发、测试与构建README 只列出了两个脚本而 package.json 实际提供了完整的工程化脚本集按用途归纳如下脚本实际命令用途yarn devnext dev开发模式HMR默认 3000 端口yarn build/yarn startnext build/next start生产构建与启动yarn run-mock-servertsx ./mock-server.ts启动 8080 端口的 Mock APIyarn testvitest单元测试Vitest Testing Libraryjsdom 环境yarn test-e2epm2 start yarn run-mock-server --name server yarn playwright test用 PM2 拉起 Mock Server 后跑 Playwright E2Eyarn lint/yarn check-typesnext lint/tsc --noEmit静态检查与类型检查yarn storybook/yarn build-storybookstorybook dev -p 6006/storybook buildUI 组件 Storybookyarn generateplop基于 generators/component 模板的代码生成两个脚本值得展开yarn test-e2e把“先起 Mock Server”这一 README 约定固化进了命令本身——先用pm2以独立进程名server托管 Mock Server再执行playwright test测试用例位于 e2e/testsauth.setup.ts、smoke.spec.ts、profile.spec.tsE2E 读取的环境变量则来自.env.example-e2e对应的配置。yarn generate通过 Plopplopfile.cjs按 generators/component 下的 Handlebars 模板生成组件 Story 索引文件保证新增 UI 组件时目录结构组件、stories、index.ts与仓库既有规范一致。小结apps/nextjs-app的本地启动路径可以概括为三步复制.env.example为.env满足 Zod 必填校验yarn run-mock-server在 8080 端口起一个带数据持久化的 MSW 模拟后端yarn dev在 3000 端口启动 Next.js App Router 应用并访问/auth/register开始体验。整套流程的价值在于环境变量有运行时校验、Mock 层与 E2E 测试共用同一份 MSW handler、工程脚本覆盖了单测、E2E、类型检查与组件文档化——这些细节与 README 中“先 Mock Server 后应用”的简单指引共同构成了该子应用可长期维护的基础。若需深入了解各层设计决策可继续阅读仓库根目录 README.md 指向的 项目结构 与 API 层 等文档。【免费下载链接】bulletproof-react️ ⚛️ A simple, scalable, and powerful architecture for building production ready React applications.项目地址: https://gitcode.com/GitHub_Trending/bu/bulletproof-react创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考