sample-monorepo 快速上手指南：3 个命令跑通 React 19 应用与 SSR 服务端
【免费下载链接】sample-monorepoSample monorepo setup with npm workspaces and typescript project references项目地址: https://gitcode.com/gh_mirrors/sa/sample-monorepo
sample-monorepo 是一个基于 npm workspaces 与 TypeScript project references 的 React 19 monorepo 示例工程。它以最小的目录结构演示了"组件库 + 前端应用 + SSR 服务端"如何在一个仓库内协同工作：你只需要依次执行 3 个命令，就能在本地同时跑通 React 19 客户端渲染和带水合（hydration）的 SSR 服务端。本文将带你一步步完成安装、构建与启动，并拆解这个 monorepo 的目录结构与工程配置，适合刚接触 monorepo 或 SSR 的前端新手快速上手。
3 个命令快速启动 sample-monorepo
首先将仓库克隆到本地：
git clone https://gitcode.com/gh_mirrors/sa/sample-monorepo cd sample-monorepo然后在项目根目录依次执行下面 3 个命令即可：
| 命令 | 作用 |
|---|---|
npm i | 一键安装全部依赖（依赖统一安装在根目录node_modules） |
npm run build | 使用 TypeScript 项目引用编译所有包，产出dist |
npm start | 启动 webpack dev server，自动打开 React 19 客户端页面 |
如果你想体验 SSR 服务端渲染，只需追加一条命令：
npm run start:server服务默认监听http://localhost:3000：
http://localhost:3000/—— 纯客户端渲染http://localhost:3000/server—— SSR 服务端渲染（带水合）
💡 提示：
npm run start:server执行前会自动先构建 app 的生产包（见根目录 package.json 中的prestart:server脚本），所以首次运行稍慢属正常现象。
最快配置方法：一行命令安装全部依赖
得益于 npm workspaces，根目录 package.json 中声明的"workspaces": ["packages/*"]会让所有子包共享同一个node_modules，并自动完成包之间的相互链接。这意味着：
- 公共的
devDependencies只需维护在根目录，版本统一、升级方便； - 每个包各自维护独立的
dependencies与scripts； - 新增一个包，只需放进
packages目录并重新执行npm i即可。
依赖的维护原则也很清晰：开发期工具（如 TypeScript、ESLint、Webpack）放根目录，运行时依赖（如express、sanitize.css）放在对应子包的 package.json 中。
monorepo 目录结构一图看懂
sample-monorepo/ ├── package.json # 公共脚本与 devDependencies ├── lerna.json # Lerna 发布配置 ├── tsconfig.base.json # 公共 TypeScript 配置 ├── tsconfig.json # solution 风格根配置 └── packages/ ├── components/ # React 组件库 ├── app/ # React 19 前端应用 └── server/ # Express + SSR 服务端三个包之间的依赖关系是单向的：
@sample/server依赖@sample/app@sample/app依赖@sample/components
整个工程严格采用 TypeScript strict 模式，公共编译选项统一放在 tsconfig.base.json（开启composite、declaration、sourceMap等），每个子包再通过各自的 tsconfig.json 继承并增量编译到各自的dist目录。根目录的 tsconfig.json 采用 solution 风格统一引用所有子项目，因此一条npm run build就能按依赖顺序编译全部包。
用 TypeScript project references 管理跨包引用
monorepo 的核心价值在于"跨包开发"。在 sample-monorepo 中，app 直接引用组件库的源码：
- packages/app/src/app.tsx 中
import { Main } from "@sample/components"，类型与运行时代码都来自同一仓库； - packages/components/src/index.ts 统一导出组件入口，供 app 与 server 复用。
依赖关系在 package.json 中只是普通的dependencies声明，配合根目录的tsc --build增量编译，修改组件库后无需手动重复构建即可被上层感知。
SSR 服务端渲染：3 个关键文件
服务端侧的实现非常精简，核心就两个文件：
- packages/server/src/server-main.ts —— 启动入口，监听 3000 端口并打印两个访问地址；
- packages/server/src/http-server.tsx —— 使用
ReactDOMServer.renderToString将<App />渲染为 HTML 字符串，并注入main.js脚本实现水合（hydration）。
服务端通过compression中间件压缩响应、express.static提供 app 打包产物，一条/server路由即可完成 SSR 全流程。生产模式构建由根目录脚本npm run -w @sample/app bundle:prod完成，产出的 UMD 包会被服务端自动解析加载（见 webpack.config.js）。
测试与代码规范：一条命令全部搞定
sample-monorepo 内置了完整的质量保障链路：
- 根目录
npm test会先执行lint+build，再运行 Node 内置测试运行器； - 测试代码与源码同目录存放，例如 packages/app/src/test/app.test.tsx 与 packages/components/src/test/test.test.ts；
- 启用
--enable-source-maps，报错信息可直接映射回 TypeScript 源码，排查更轻松； npm run prettify一键格式化全仓库代码。
常见问题速查
Q1：npm run build报找不到模块？请确认根目录执行过npm i，且 Node 版本 ≥ 22（见 package.json 的engines字段）。
Q2：启动服务端后访问/server报错？npm run start:server会自动触发 app 的生产构建，若失败请先单独执行npm run -w @sample/app bundle:prod排查。
Q3：如何发布到 npm？根目录已配置 lerna.json，执行npx lerna publish即可按变更情况逐个发布，每个包都有prepack脚本保证发布前自动构建。
总结
sample-monorepo 用不到 10 个源文件，就完整示范了 monorepo 时代的前端标准姿势：npm workspaces 统一依赖、TypeScript project references 跨包类型安全、React 19 + SSR 水合开箱即用。无论你是想给团队搭建 monorepo 基建，还是想快速理解 SSR 渲染流程，克隆下来跑一遍这 3 个命令，收获会远超读十篇教程。现在就去试试吧！🚀
【免费下载链接】sample-monorepoSample monorepo setup with npm workspaces and typescript project references项目地址: https://gitcode.com/gh_mirrors/sa/sample-monorepo
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
