初学者的第一堂 monorepo 课sample-monorepo 带你理解 npm workspaces 核心概念【免费下载链接】sample-monorepoSample monorepo setup with npm workspaces and typescript project references项目地址: https://gitcode.com/gh_mirrors/sa/sample-monorepo对于刚接触前端工程化的新手来说npm workspaces往往是最值得先弄明白的概念之一。sample-monorepo 是一个专门为教学设计的 monorepo 示例项目它用极简的代码把 npm workspaces 和 TypeScript project references 的核心机制完整展示出来。读完这篇文章你不仅能看懂 monorepo 是什么还能亲手跑起来彻底搞懂多个 npm 包之间如何共享依赖、互相引用。什么是 monorepo为什么前端项目都在用 monorepo单仓库多包指的是把多个项目放进同一个 Git 仓库每个项目作为一个独立的 package 维护。与之相对的叫 multirepo多仓库。前端团队偏爱 monorepo 的核心原因有三个✅依赖统一所有包共用根目录的node_modules版本不再东一个西一个✅改动联动组件库改了应用立刻生效不用先发布再安装✅提交原子化一次 commit 可以同时包含组件库和应用的改动sample-monorepo 就是这种思想的教科书级范例仓库虽小五脏俱全。sample-monorepo 项目结构一目了然 ️整个仓库只有三个核心包全部放在packages/目录下包名作用依赖关系sample/componentsReact 组件库被 app 引用sample/appReact 前端应用依赖 componentssample/serverExpress 服务端含 SSR依赖 app依赖链条非常清晰server → app → components层层引用正好演示了 monorepo 里包之间互相引用这个最核心的能力。每个包都遵循同样的结构src/index.ts是入口src/test/放测试tsconfig.json是本包独立配置package.json声明自己的依赖和脚本。这种约定式目录降低了理解成本。npm workspaces 核心概念拆解重点1. 一行配置声明工作区在根目录的package.json中只需一行workspaces: [packages/*]这一行告诉 npmpackages/下的每个子目录都是一个独立的工作区workspace。以后新增包只要把新目录放进packages/重新执行npm i即可零额外配置。2. 依赖提升与去重npm 的魔法普通项目里每个包都有自己独立的node_modules。而在 npm workspaces 中所有依赖都会被提升hoist到根目录的node_modules使用与单包相同的去重机制。这意味着React、TypeScript 这类工具链只安装一份磁盘占用更小、安装速度更快版本冲突的概率也大大降低。3. 公共依赖统一放根目录sample-monorepo 有一个鲜明约定所有devDependencies只出现在根package.json而每个包只保留自己运行时需要的dependencies和peerDependencies。以sample/app为例它只声明了sample/components和sanitize.css两个运行时依赖而 React 则作为peerDependencies出现保证版本由宿主统一控制。新增公共工具时直接在根目录执行npm i 包名 -D即可。4. 包之间直接互相引用这是 monorepo 最爽的一点。sample/app的package.json里声明dependencies: { sample/components: ^1.0.0 }然后代码里直接importnpm 会自动把仓库内的sample/components软链接symlink到根目录node_modules。改完组件库源码应用无需重新发布即可看到效果开发体验极佳。服务端sample/server引用sample/app也是同样的机制。TypeScript project referencesmonorepo 的最佳搭档 纯 JavaScript 时代 monorepo 就有很多工具但加上 TypeScript 后跨包的类型检查会变得麻烦。sample-monorepo 给出的答案是TypeScript project references根目录的tsconfig.base.json是公共基础配置开启composite和strict所有包继承它根目录的tsconfig.json是解决方案式入口用references字段引用三个子项目每个包的tsconfig.json独立编译到各自的dist/目录这样执行根目录的npm run build即tsc --build时TypeScript 会按依赖顺序增量编译所有包并生成.d.ts声明文件让跨包的类型互相可见。源码、类型、引用关系完全闭环。新手最快上手指南4 步跑起来 克隆仓库后在根目录依次执行git clone https://gitcode.com/gh_mirrors/sa/sample-monorepo npm i npm run build npm startnpm i安装所有工作区依赖一次搞定全部包npm run build按依赖顺序编译所有 TypeScript 项目npm start以开发模式启动前端应用带 source-map方便调试想体验 SSR 服务端渲染再执行npm run start:server然后访问http://localhost:3000查看纯客户端渲染访问http://localhost:3000/server查看服务端渲染结果。前后端在同一仓库里协作这就是 monorepo 的魅力。常用脚本速查表 根目录package.json里预置了这些工作区级脚本命令作用npm run build增量编译全部 TS 项目npm run lintESLint 检查全部代码npm test先 lint build再跑全部测试npm run start:client开发模式启动前端npm run start:server启动带 SSR 的服务端npm run clean清理所有包的 dist 目录注意start:client的实现是npm run -w sample/app start这个-w参数正是 npm workspaces 提供的定向执行能力——只跑某个包的脚本不用手动 cd 进目录。发布与版本管理Lerna 的配合 sample-monorepo 还带了一个lerna.json用于解决多包发布的痛点。配置里useWorkspaces: true表示 Lerna 直接复用 npm workspaces 的工作区version: independent表示各包独立版本号。当某个包有改动时执行npx lerna publishLerna 会识别出自上次发布以来有变更的包并逐个发布到 npm每个包发布前还会自动运行prepack脚本完成构建。至此从开发到发布的完整链路都打通了。写在最后 sample-monorepo 的价值不在于代码量而在于它把npm workspaces TypeScript project references Lerna三件套的组合方式浓缩成了一个能跑、能测、能发布的最小闭环。对于想入门 monorepo 的开发者它是最值得精读的第一课。建议你 clone 下来之后亲手在packages/components里改一个组件、在packages/app里引用它感受一下改完即生效的体验——这比读任何文档都来得直观。祝你 monorepo 之旅顺利【免费下载链接】sample-monorepoSample monorepo setup with npm workspaces and typescript project references项目地址: https://gitcode.com/gh_mirrors/sa/sample-monorepo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考