🪢 Langfuse 图解教程Langfuse Visual Guide 第十部分 · 平台与运维Part 10 · Platform & Operations 53 / 55
第十部分 · 平台与运维Part 10 · Platform & Operations

构建·测试·开发流Build, test & dev workflow

🧭 读前Before you start
先读 第4课 的 monorepo 全景,本课讲构建、测试与开发流。
Read Lesson 4 on the monorepo map; this lesson covers the build, test, and dev workflow.

你已经把 Langfuse 从摄取到运维看了个遍。最后一课换个角度:这个平台自己是怎么被构建、测试、迭代的?答案藏在三样东西里。① pnpm monorepo——web、worker、shared、ee 四个包住在同一个仓库里,共享代码、还由工具强制好依赖方向。② Turborepo——用一套任务管道 + 内容哈希缓存,让「改一个包、只重建这个包」成为可能,把几十个包的构建/CI 从「每次全量、慢到崩溃」变成「秒级增量」。③ 一键开发流——一条 dx 命令就能从零拉起完整本地环境(装依赖→起 Docker 基础设施→重置库→灌种子数据→跑起来),外加一个 seed CLI 一键生成逼真的测试数据。 作为第十部分(平台与运维)的收尾,这一课讲的是「开发者每天的循环」——一个项目好不好上手、好不好维护,往往就藏在这些不起眼的工程基建里。

📋 生活类比
把这套工程基建想象成一座高效运转的「中央厨房」。monorepo 是把所有档口(前厅 web、后厨 worker、共享调料台 shared、特供窗口 ee)集中在同一栋楼里——要改一份所有档口都用的酱料配方(shared 里的代码),一处改、各处即时同步,不必挨家挨户去通知。 Turbo 的缓存像一位记忆超群的主厨:他记得每道菜的「原料指纹」,只要某道菜的原料和上次一模一样,他就直接端出上次做好的成品,绝不重做(缓存命中,秒出);只有原料变了的那几道,才重新下锅。于是哪怕菜单有几十道,每次出餐也只需重做「真正改了的那几道」。 而 dx 一键命令,是给新来的厨师的「开工自动化」:一声令下,水电气全开、灶台预热、备菜到位——从空厨房到能出餐,一步到位,不用新人对着十几页手册手忙脚乱地配置半天。

monorepo:四个包一个仓库,依赖方向被强制

Langfuse 是个 monorepo(单仓库多包):pnpm-workspace.yaml 把 web(Next.js 应用)、worker(队列消费者)、packages/shared(共享领域/DB/队列契约)、ee(企业包)放进同一个仓库。好处是共享代码即时联动:改一处 shared 里的类型或函数,web 和 worker 立刻都看得到,一个 commit 就能跨包原子地改完——不必像多仓库那样发版、升级、再对齐。包管理器是 pnpm(preinstall: only-allow pnpm 强制只能用 pnpm,不许 npm/yarn 混入),还设了 minimumReleaseAge(新依赖要发布满若干天才许装,防供应链投毒)。

而依赖方向是有纪律的:web → shared、worker → shared、ee → shared,而 shared 谁也不依赖(不反向 import web/worker/ee)。这条「底层不依赖上层」的铁律,让 shared 成为干净的地基——任何人都能安全复用它,而不会被上层的具体实现污染。下一节会看到,Turbo 还会顺着这条依赖图自动安排构建顺序。

一个仓库装四个包,依赖只朝下不朝上 webNext.js 应用(UI+tRPC+REST) worker队列消费者/后台处理 ee企业包(第50课) packages/shared(干净地基)领域模型 · DB(Prisma/ClickHouse) · 队列契约 · 仓储不反向依赖 web/worker/ee 依赖只朝下:上层用下层,下层不知上层 pnpm 强制(only-allow) + minimumReleaseAge 防供应链投毒;同仓库共享代码一个 commit 原子改
pnpm monorepo:pnpm-workspace.yaml packages = web / worker / packages/** / ee;package.json 的 packageManager: pnpm@11.4.0、preinstall: only-allow pnpm;pnpm-workspace.yaml 的 minimumReleaseAge(供应链防护)。依赖方向 web/worker/ee → @langfuse/shared,shared 不反向依赖——与 .agents/ARCHITECTURE_PRINCIPLES.md 一致。
示例:Turbo 任务图与 affected 缓存 ✎ 改了 packages/shared db:generate ↻ 受影响重跑 cache:false build ↻ 受影响重跑 ^build · cache typecheck ⚡ 缓存命中 lint ↻ 受影响重跑 test ⚡ 缓存命中 build:check ↻ 受影响重跑 ↻ 受影响 → 真正执行 ⚡ 未受影响 → 指纹缓存秒回 hash(inputs + deps + config) → 命中则跳过执行、直接重放缓存的输出与日志 turbo run build lint test --filter=...[origin/main] 只跑改动波及的包;其余 >>> FULL TURBO 秒过
Turbo 把 monorepo 的构建变成「带缓存的任务 DAG」(任务与 dependsOn 取自 turbo.json;值为示例):build 依赖 db:generate 和 ^build(先建上游包),lint/typecheck/build:check 依赖 ^build、test 依赖 ^test。每个任务有一个指纹=hash(输入 + 依赖 + 配置):你只改了 packages/shared,于是 shared 和依赖它的 web/worker 被标为 affected 真正重跑(黄),其余包命中缓存秒回(绿,>>> FULL TURBO)。配合 --filter=...[origin/main],CI 只跑改动波及的那部分——这就是大仓库还能快的原因。
上层web / worker / ee
三个可独立部署/运行的「应用层」包:web 是 Next.js 全栈、worker 是后台队列消费者、ee 是企业功能。它们都依赖 shared,彼此之间尽量不直接耦合。
地基packages/shared
领域模型、Prisma/ClickHouse 访问、队列名与负载契约、仓储层——全平台共享的核心。它不 import 任何上层,所以能被安全复用、独立测试。这条「地基不依赖楼层」的纪律是 monorepo 不腐化的关键。
管理pnpm 工作区
pnpm 用硬链接共享依赖、省磁盘又快;only-allow pnpm 杜绝包管理器混用导致的锁文件冲突;minimumReleaseAge 拒装「刚发布几天」的新版本,给供应链投毒留出被发现的窗口。

Turborepo:任务管道 + 内容哈希缓存

几十个包,每次都全量构建/检查会慢到无法忍受。Turborepo 用两招解决:① 任务管道(dependsOn)——turbo.json 里每个任务声明依赖,build 的 dependsOn: ["db:generate", "^build"] 里那个 ^build 意思是「先把所有依赖包的 build 跑完」。于是 Turbo 顺着上一节的依赖图自动排出拓扑顺序:shared 先 build,web/worker 再 build——你不用手写顺序。② 内容哈希缓存(cache + outputs)——Turbo 把每个任务的输入(源码 + 依赖 + 环境变量)算一个哈希;只要哈希和上次一模一样,它就直接重放上次缓存的输出(outputs 里声明的 dist/、.next/),跳过真正的构建。

这一招的威力在于「只重建真正改了的」:你改了 web 的一个文件,shared 没动——Turbo 一看 shared 的输入哈希没变,秒级重放它的缓存,只老老实实重建 web。CI 上更是救命:大部分包没变,缓存全中,几十个包的构建可能几秒就过。注意有些任务故意不缓存(cache: false):dev(是个常驻服务、persistent: true)、db:generate(Prisma 把类型写进 node_modules,是缓存日志重放恢复不了的副作用,turbo.json 里专门有注释说明)——凡是「有副作用、不能靠重放日志还原」的任务,都不能缓存。

顺依赖图排顺序 + 没变就重放缓存 ① 任务管道 dependsOnbuild: ["db:generate", "^build"]^build = 先建所有依赖包shared → web/worker 自动拓扑序 ② 算输入哈希源码 + 依赖 + env每个任务一个指纹 哈希命中重放缓存 outputsdist/.next 秒出 哈希变了真正重建这个包只重建改了的 CI 救命大部分包没变→缓存全中→几秒过 cache: false(不缓存)dev(常驻) · db:generate(写 node_modules)有副作用、重放日志恢复不了 改一个 web 文件、shared 没动 → shared 缓存秒重放,只重建 web;几十个包不再每次全量 原则:纯函数式任务(输入定输出)可缓存;有副作用的(起服务、写 node_modules)必须 cache:false
Turbo 管道 + 缓存:turbo.json build.dependsOn ["db:generate","^build"](^ = 先建依赖包,拓扑序)、outputs ["dist/**",".next/**"]、cache: true;lint/typecheck/build:check/test 同样 cache: true。dev/db:generate cache: false(dev persistent: true;db:generate 注释明确「写 node_modules、缓存只重放日志恢复不了副作用」)。
turbo.json任务管道 + 缓存声明
// 每个任务声明:依赖谁、产出什么、能否缓存
"tasks": {
  "build": {
    "dependsOn": ["db:generate", "^build"],   // ^build = 先建所有依赖包(拓扑序)
    "outputs": ["dist/**", ".next/**", "!.next/cache/**"],  // 这些产物进缓存
    "cache": true                              // 输入没变 → 重放缓存、跳过构建
  },
  "dev": {
    "cache": false,                             // 常驻服务,不能缓存
    "persistent": true,
    "dependsOn": ["db:generate"]
  },
  "db:generate": {                            // Prisma 把类型写进 node_modules——
    "inputs": ["…/schema.prisma"],
    "cache": false                             // 缓存只重放日志,恢复不了这个副作用
  }
}

🧭 自动拓扑序

^build 让 Turbo 顺依赖图排顺序:shared 先建、web/worker 后建。你声明「依赖谁」,顺序由工具算——不会手写错。

⚡ 缓存重放

输入哈希没变就重放上次 outputs、跳过构建。只重建真正改了的包;CI 上缓存全中,几十个包几秒过。

🎯 --filter 缩范围

turbo run dev --filter=web 把操作精确缩到单个包,只跑 web、不惊动其它——开发时只关心眼前那一块。

一键开发流:从空环境到能跑,一步到位

一个新人 clone 下代码,要跑起来得做多少事?装依赖、起数据库/Redis/ClickHouse、建表、灌测试数据、再启动……手动来十几步,错一步就卡半天。Langfuse 把这一长串压成一条命令 dx(developer experience):pnpm i 装依赖 → infra:dev:up 用 docker compose 拉起本地基础设施 → 重置 PG/ClickHouse → db:seed:examples 灌示例数据 → dev 跑起来。还有 dx-f(强制重置)、dx:skip-infra(跳过基础设施)等变体应对不同场景。所有命令都走 turbo run 或 pnpm --filter,--filter 能把操作精确缩到单个包(dev:web = turbo run dev --filter=web)。

一条命令 pnpm dx:从空环境到能跑,一步到位 ① clone 空环境 ② pnpm i 装依赖 ③ infra:dev:up docker 起 PG/Redis/CH ④ 重置库 PG / ClickHouse ⑤ db:seed 灌示例数据 ⑥ dev ✓ 跑起来 变体:dx-f 强制重置 · dx:skip-infra 跳过基础设施 · --filter 缩到单个包

测试数据则交给 seed CLI(packages/shared/scripts/seeder/):它能按场景(scenario)生成逼真的 trace/observation/score、长会话、大批量数据——用来本地调试、压列表性能、复现 bug。这比手写 SQL insert 或往 ClickHouse 里硬塞数据靠谱得多,也是「让 bug 可廉价复现」的关键工具。

开发任务命令背后
一键起完整本地环境pnpm dx装依赖→docker 基础设施→重置库→灌种子→dev,一条龙
只开发 web / workerpnpm dev:web / dev:workerturbo run dev --filter=web,--filter 缩到单包
构建 / 检查 / 测试pnpm build / lint / tc / test全走 turbo run,享受拓扑序 + 缓存
灌逼真测试数据pnpm seedseed CLI 按 scenario 生成 trace/session/批量数据
本地基础设施infra:dev:up/downdocker compose 起停 PG/Redis/ClickHouse 等

把这一课连起来看,「好不好开发」其实是一连串把摩擦降到最低的工程决策:monorepo 让跨包改动一个 commit 搞定、Turbo 让重建只花在真正改了的地方、dx 让新人一条命令上手、seed 让复现 bug 不用手攒数据。这些基建平时隐形,却实打实决定了一个团队迭代有多快、维护有多稳——也正是「平台与运维」这一部分最接地气的收尾。

🎯 设计取舍
monorepo(所有包一个仓库)相比 polyrepo(一包一仓库),到底好在哪、又牺牲了什么? 最大的好处是「跨包改动的原子性」:当你要改一个 shared 里的接口、同时更新所有调用它的 web/worker 代码,monorepo 里一个 commit、一个 PR、一次 CI 就全搞定,永远不会出现「shared 发了新版但 web 还没升级」的中间断裂态。其次是代码共享零摩擦(直接 import,不必发包)、统一的工具链(一套 lint/test/构建配置管全部)。代价是:仓库变大、构建/CI 天然更重——而这正是 Turbo 缓存要解决的问题。所以「monorepo + Turbo」几乎是绑定出现的:monorepo 带来协作上的原子性,Turbo 的内容哈希缓存把它在构建上的代价摊平。选 monorepo,本质是用「构建工具的复杂度」换「协作与一致性的简单」——对一个多包紧密协作的产品,这笔交易非常划算。

为什么 Turbo 要区分「可缓存」和「不可缓存(cache:false)」的任务?把什么都缓存上不是更快吗? 因为缓存的前提是「纯函数式」——同样的输入必然产生同样的、可被完整重放的输出。build 满足:给定源码+依赖,产物就是 dist/、.next/ 那几个文件,缓存把它们存下来、下次原样吐出即可。但 dev 是个常驻服务(persistent),它的「输出」是一个一直在跑的进程,根本没有「最终产物」可缓存;db:generate 更隐蔽——它的真正效果是把 Prisma 类型写进 node_modules,而 Turbo 的缓存命中只会「重放当时的日志」,并不会真的把文件再写进 node_modules(turbo.json 里专门有注释点破这点),于是在干净的 CI 机器上若缓存了它,就会出现「日志说成功了、可类型其实没生成」的诡异故障。这给我们一个普适判据:一个任务能不能缓存,取决于它的全部效果是否都体现在可声明的 outputs 里;凡有「藏在别处的副作用」(起进程、写 node_modules、改外部状态)的任务,必须 cache:false。
🎯 本课要点 · 第十部分收官
  • pnpm monorepo:web/worker/packages/shared/ee 一个仓库;依赖只朝下(web/worker/ee → shared,shared 不反向依赖);pnpm 强制(only-allow) + minimumReleaseAge 防供应链投毒。共享代码一个 commit 原子改。
  • Turbo 任务管道:dependsOn 的 ^build 让 Turbo 顺依赖图自动排拓扑构建序(shared 先、web/worker 后),不用手写顺序。
  • Turbo 内容哈希缓存:把输入(源码+依赖+env)算哈希,没变就重放缓存 outputs、跳过构建——「只重建真正改了的包」,CI 上缓存全中可几秒过。build/lint/typecheck/test 皆可缓存。
  • 有副作用的任务 cache:false:dev(常驻服务)、db:generate(写 node_modules)——效果不在可声明 outputs 里、重放日志恢复不了,必须不缓存。判据:全部效果是否都体现在 outputs 里。
  • 一键开发流 + seed:dx 一条命令从空环境到能跑(装依赖→docker 基础设施→重置库→灌种子→dev);--filter 缩到单包;seed CLI 按 scenario 生成逼真测试数据(让 bug 可廉价复现)。把开发摩擦降到最低,正是「好维护」的底色。

🧪 自测 · 想一想为什么这么设计

1. Turborepo 的内容哈希缓存让 Langfuse 的多包构建变快。它的核心机制是?
  1. 并行编译所有包,不管有没有改
  2. 把所有包压缩成一个文件来加速
  3. 把每个任务的输入(源码+依赖+环境变量)算一个哈希;只要哈希和上次一模一样,就直接重放上次缓存的outputs(dist/.next)、跳过真正构建。于是改了web、shared没动时,shared缓存秒重放,只重建web——「只重建真正改了的包」
  4. 缓存数据库查询结果
看答案与解析 点击展开
答案:C。几十个包若每次都全量构建,会慢到无法忍受。Turbo 的关键洞察是:一个构建任务本质是「输入→输出」的纯函数,只要输入没变,输出就一定一样,那就没必要重算。它把每个任务的全部输入(该包源码 + 它依赖的包 + 相关环境变量)算成一个内容哈希;下次跑时先比哈希,命中就把上次存下的 outputs(turbo.json 里声明的 dist/、.next/)原样吐出,完全跳过编译。于是你只改了 web 的一个文件、shared 纹丝未动时,shared 的输入哈希不变、缓存秒重放,Turbo 只老实重建 web。这让「增量构建」名副其实,CI 上大部分包没变、缓存全中,几十个包可能几秒就过。
2. turbo.json 里,build/lint/test 都是 cache:true,但 dev 和 db:generate 故意设了 cache:false。这个区分背后的判断标准是?
  1. 一个任务能否缓存,取决于它的全部效果是否都体现在可声明的outputs里。build/lint产出确定的文件可缓存;但dev是常驻服务(没有最终产物)、db:generate把Prisma类型写进node_modules(缓存只重放日志、恢复不了这个副作用)——凡有「藏在别处的副作用」的任务必须cache:false
  2. cache:false 是为了节省磁盘空间
  3. dev 和 db:generate 运行太快,缓存没意义
  4. 只有构建产物才值得缓存,其他都不缓存
看答案与解析 点击展开
答案:A。缓存的前提是「纯函数式」:同样输入必然产生同样的、能被完整重放的输出。build 满足——给定源码+依赖,产物就是 dist/、.next/ 那些文件,存下来下次原样吐出即可。但 dev 是 persistent 常驻服务,它的「输出」是一个一直跑着的进程,根本没有可缓存的「最终产物」。db:generate 更隐蔽:它真正的效果是把 Prisma 生成的类型写进 node_modules,而 Turbo 缓存命中只会重放当时的日志、并不会真的把文件再写进 node_modules(turbo.json 专门有注释点破),于是在干净的 CI 机器上若缓存它,会出现「日志显示成功、类型却没生成」的诡异故障。所以普适判据是:任务的全部效果是否都落在可声明的 outputs 里?凡有起进程、写 node_modules、改外部状态这类「藏在别处的副作用」,就必须 cache:false。
3. Langfuse 把 web/worker/shared/ee 放进同一个 monorepo,而不是每个包一个独立仓库(polyrepo)。monorepo 最突出的好处是?
  1. 跨包改动的原子性:改一个shared接口并同时更新所有调用它的web/worker代码,可以一个commit、一个PR、一次CI全搞定,永远不出现「shared发了新版但web还没升级」的中间断裂态;外加代码共享零摩擦、统一工具链
  2. monorepo 不需要任何构建工具
  3. monorepo 让每个包的代码量更少
  4. monorepo 自动让代码运行更快
看答案与解析 点击展开
答案:A。polyrepo(一包一仓库)下,改一个被多处依赖的 shared 接口是件痛事:你得先在 shared 仓库改完、发版,再到 web、worker 仓库分别升级依赖、改调用、各自发版——这期间必然存在「shared 已是新版、web 还是旧版」的不一致窗口,跨仓库的原子性根本无法保证。monorepo 把它们放一起后,这种改动就是一个 commit、一个 PR、一次 CI 的事,要么全过要么全不过,永远一致。此外还有代码直接 import(不必发包)、一套 lint/test/构建配置管全部等好处。代价是仓库变大、构建变重——但这恰恰由 Turbo 的缓存来摊平。所以「monorepo + Turbo」往往绑定出现:前者给协作的原子性,后者还构建的速度。
💭 发散思考(没有标准答案,动手或动脑想想)
  • 这一课(也是「平台与运维」的收尾)讲的是「开发者每天的循环」——monorepo 让跨包改动原子化、Turbo 让重建只花在改了的地方、dx 让新人一条命令上手、seed 让 bug 可廉价复现。请回想你参与过的项目:从 clone 代码到能跑起来要几步、花多久?哪些「隐形的工程基建」最影响你的开发幸福感?如果让你为一个新项目投资「开发者体验」,你会优先做哪三件事,为什么?

You've seen Langfuse from ingestion to operations. The last lesson takes a different angle: how is the platform itself built, tested, and iterated? The answer hides in three things. ① pnpm monorepo — the four packages web, worker, shared, ee live in one repo, sharing code with a tool-enforced dependency direction. ② Turborepo — a task pipeline + content-hash cache that makes "change one package, rebuild only that package" possible, turning dozens of packages' builds/CI from "full every time, slow to a crawl" into "seconds, incremental." ③ one-command dev workflow — a single dx command spins up a full local environment from scratch (install deps → bring up Docker infra → reset DBs → seed data → run), plus a seed CLI for realistic test data in one command. As the close of Part 10 (Platform & Operations), this lesson is about the developer's daily loop — whether a project is approachable and maintainable often hides in this unglamorous engineering infrastructure.

📋 Analogy
Picture this engineering infrastructure as an efficiently-run "central kitchen." The monorepo puts all stations (front-of-house web, back kitchen worker, shared seasoning bench shared, special window ee) in the same building — to change a sauce recipe all stations use (code in shared), change it once and every station syncs instantly, no need to notify each one door to door. Turbo's cache is like a chef with stunning memory: he remembers each dish's "ingredient fingerprint," and as long as a dish's ingredients are identical to last time, he serves the previously-made dish directly, never remaking it (a cache hit, instant); only the few dishes whose ingredients changed go back on the stove. So even with dozens of dishes on the menu, each service only remakes "the few that actually changed." And the dx one-command is "startup automation" for a new chef: one order, and water/electric/gas all on, stove preheated, prep done — from empty kitchen to ready-to-serve in one step, no fumbling through a dozen pages of manual to configure for half a day.

Monorepo: four packages one repo, dependency direction enforced

Langfuse is a monorepo (one repo, many packages): pnpm-workspace.yaml puts web (Next.js app), worker (queue consumers), packages/shared (shared domain/DB/queue contracts), and ee (enterprise package) in one repo. The benefit is instant code-sharing linkage: change a type or function in shared and web and worker see it immediately, an atomic cross-package change in one commit — no multi-repo cycle of release, upgrade, re-align. The package manager is pnpm (preinstall: only-allow pnpm forces pnpm only, no npm/yarn mixing), with a minimumReleaseAge set (a new dependency must have been published for some days before it can be installed, against supply-chain poisoning).

And the dependency direction is disciplined: web → shared, worker → shared, ee → shared, while shared depends on no one (never reverse-imports web/worker/ee). This "the lower layer doesn't depend on the upper" iron rule makes shared a clean foundation — anyone can safely reuse it without being polluted by upper-layer specifics. The next section shows Turbo follows this dependency graph to auto-order builds.

One repo holds four packages; dependencies only point down webNext.js app (UI+tRPC+REST) workerqueue consumers / background eeenterprise package (L50) packages/shared (clean foundation)domain · DB(Prisma/ClickHouse) · queue contracts · reposnever reverse-depends on web/worker/ee Dependencies only point down: upper uses lower, lower doesn't know upper pnpm enforced (only-allow) + minimumReleaseAge against supply-chain poisoning; same repo, atomic cross-package commit
pnpm monorepo: pnpm-workspace.yaml packages = web / worker / packages/** / ee; package.json packageManager: pnpm@11.4.0, preinstall: only-allow pnpm; pnpm-workspace.yaml minimumReleaseAge (supply-chain protection). Dependency direction web/worker/ee → @langfuse/shared, shared doesn't reverse-depend — consistent with .agents/ARCHITECTURE_PRINCIPLES.md.
Example: the Turbo task graph & affected cache ✎ changed packages/shared db:generate ↻ affected cache:false build ↻ affected ^build · cache typecheck ⚡ cache hit lint ↻ affected test ⚡ cache hit build:check ↻ affected ↻ affected → really runs ⚡ unaffected → fingerprint cache replay hash(inputs + deps + config) → on hit, skip execution and replay cached outputs+logs turbo run build lint test --filter=...[origin/main] runs only affected packages; the rest is >>> FULL TURBO instantly
Turbo turns a monorepo build into a "cached task DAG" (tasks and dependsOn from turbo.json; values illustrative): build depends on db:generate and ^build (upstream packages first), then lint/typecheck/build:check depend on ^build and test on ^test. Every task has a fingerprint = hash(inputs + deps + config): change only packages/shared and shared plus the web/worker depending on it are marked affected and really re-run (amber), while the rest hit the cache instantly (green, >>> FULL TURBO). With --filter=...[origin/main], CI runs only the affected slice — which is why a big repo stays fast.
upperweb / worker / ee
Three independently-deployable/runnable "application-layer" packages: web is full-stack Next.js, worker is background queue consumers, ee is enterprise features. They all depend on shared and avoid coupling directly to each other.
foundationpackages/shared
Domain models, Prisma/ClickHouse access, queue names and payload contracts, the repository layer — the platform-wide core. It imports no upper layer, so it can be safely reused and independently tested. This "foundation doesn't depend on floors" discipline is key to a monorepo not rotting.
managepnpm workspaces
pnpm shares deps via hard links, saving disk and fast; only-allow pnpm prevents lockfile conflicts from mixed package managers; minimumReleaseAge refuses "just published days ago" versions, leaving a window for supply-chain poisoning to be discovered.

Turborepo: task pipeline + content-hash cache

With dozens of packages, building/checking everything every time would be unbearably slow. Turborepo solves it with two moves: ① task pipeline (dependsOn) — each task in turbo.json declares its dependencies, and the ^build in build's dependsOn: ["db:generate", "^build"] means "run build in all dependency packages first." So Turbo follows the previous section's dependency graph to auto-derive the topological order: shared builds first, then web/worker — you don't hand-write the order. ② content-hash cache (cache + outputs) — Turbo hashes each task's inputs (source + deps + env vars); as long as the hash is identical to last time, it directly replays the cached output (the dist/, .next/ declared in outputs), skipping the actual build.

The power of this move is "rebuild only what actually changed": you edit one web file, shared untouched — Turbo sees shared's input hash unchanged, replays its cache in seconds, and dutifully rebuilds only web. On CI it's a lifesaver: most packages unchanged, all cache hits, dozens of packages' builds may pass in seconds. Note some tasks deliberately don't cache (cache: false): dev (a long-running service, persistent: true), db:generate (Prisma writes types into node_modules, a side effect a cache-log replay can't restore, as turbo.json's comment specifically explains) — any task with "side effects that can't be restored by replaying logs" must not be cached.

Order by the dep graph + replay cache if unchanged ① task pipeline dependsOnbuild: ["db:generate", "^build"]^build = build all deps firstshared → web/worker auto-topology ② hash the inputssource + deps + envone fingerprint per task hash hitreplay cached outputsdist/.next instant hash changedactually rebuild itonly the changed CI lifesavermost unchanged→all hits→seconds cache: false (no cache)dev(persistent) · db:generate(writes node_modules)side effects, log-replay can't restore Edit one web file, shared untouched → shared cache replays in seconds, only web rebuilds; dozens of packages no longer full every time Principle: pure-functional tasks (inputs determine outputs) are cacheable; side-effecting ones (start a service, write node_modules) must be cache:false
Turbo pipeline + cache: turbo.json build.dependsOn ["db:generate","^build"] (^ = build deps first, topological), outputs ["dist/**",".next/**"], cache: true; lint/typecheck/build:check/test likewise cache: true. dev/db:generate cache: false (dev persistent: true; db:generate's comment explicitly: "writes node_modules, cache only replays logs and can't restore the side effect").
turbo.jsontask pipeline + cache declarations
// each task declares: who it depends on, what it outputs, whether it caches
"tasks": {
  "build": {
    "dependsOn": ["db:generate", "^build"],   // ^build = build all deps first (topological)
    "outputs": ["dist/**", ".next/**", "!.next/cache/**"],  // these artifacts go in the cache
    "cache": true                              // inputs unchanged → replay cache, skip build
  },
  "dev": {
    "cache": false,                             // long-running service, can't cache
    "persistent": true,
    "dependsOn": ["db:generate"]
  },
  "db:generate": {                            // Prisma writes types into node_modules —
    "inputs": ["…/schema.prisma"],
    "cache": false                             // cache only replays logs, can't restore this side effect
  }
}

🧭 auto topological order

^build lets Turbo order by the dependency graph: shared first, web/worker after. You declare "who it depends on", the tool computes the order — no hand-written mistakes.

⚡ cache replay

Input hash unchanged → replay last outputs, skip the build. Rebuild only what actually changed; on CI all cache hits, dozens of packages pass in seconds.

🎯 --filter scoping

turbo run dev --filter=web scopes the operation precisely to one package, running only web without disturbing others — focus on just the piece in front of you.

One-command dev: from empty environment to running, in one step

How much must a newcomer do after cloning the code to get it running? Install deps, start DB/Redis/ClickHouse, create tables, seed test data, then launch… a dozen manual steps, one slip and you're stuck for hours. Langfuse compresses this long chain into one command, dx (developer experience): pnpm i installs deps → infra:dev:up brings up local infra via docker compose → resets PG/ClickHouse → db:seed:examples seeds example data → dev runs it. There are also dx-f (force reset), dx:skip-infra (skip infra), and other variants for different scenarios. All commands go through turbo run or pnpm --filter, and --filter scopes an operation precisely to a single package (dev:web = turbo run dev --filter=web).

one command pnpm dx: from empty environment to running, in one step 1 clone empty env 2 pnpm i install deps 3 infra:dev:up docker brings up PG/Redis/CH 4 reset DBs PG / ClickHouse 5 db:seed example data 6 dev ✓ running variants: dx-f force reset · dx:skip-infra skip infra · --filter scopes to a single package

Test data is handled by the seed CLI (packages/shared/scripts/seeder/): it generates realistic trace/observation/score, long sessions, bulk data by scenario — for local debugging, stress-testing list performance, reproducing bugs. This is far more reliable than hand-writing SQL inserts or force-stuffing ClickHouse, and is a key tool for "making bugs cheaply reproducible."

Dev taskCommandBehind it
One-command full local envpnpm dxinstall→docker infra→reset DBs→seed→dev, all-in-one
Develop only web / workerpnpm dev:web / dev:workerturbo run dev --filter=web, --filter scopes to one package
Build / check / testpnpm build / lint / tc / testall via turbo run, enjoying topology + cache
Seed realistic test datapnpm seedseed CLI generates trace/session/bulk data by scenario
Local infrastructureinfra:dev:up/downdocker compose to start/stop PG/Redis/ClickHouse etc.

Read this lesson together and "how good is the developer experience" is really a chain of engineering decisions that minimize friction: the monorepo makes cross-package changes one commit, Turbo spends rebuild effort only where it actually changed, dx gets newcomers productive in one command, seed reproduces bugs without hand-assembling data. This infrastructure is usually invisible, yet it concretely decides how fast a team iterates and how stably it maintains — a fitting, down-to-earth close to "Platform & Operations."

🎯 Design trade-off
What exactly is a monorepo (all packages in one repo) better at versus a polyrepo (one package per repo), and what does it sacrifice? The biggest win is "atomicity of cross-package changes": when you change an interface in shared and simultaneously update all the web/worker code calling it, a monorepo does it all in one commit, one PR, one CI run — there's never an intermediate broken state of "shared released a new version but web hasn't upgraded." Next is frictionless code sharing (import directly, no publishing) and a unified toolchain (one lint/test/build config rules all). The cost: the repo grows larger and builds/CI are naturally heavier — which is exactly the problem Turbo's cache solves. So "monorepo + Turbo" almost always appears bundled: the monorepo brings collaborative atomicity, and Turbo's content-hash cache amortizes its build cost. Choosing a monorepo is essentially trading "build-tool complexity" for "collaboration and consistency simplicity" — for a product of tightly-collaborating packages, a very worthwhile trade.

Why does Turbo distinguish "cacheable" from "uncacheable (cache:false)" tasks? Wouldn't caching everything be faster? Because caching presupposes "pure-functional" — the same inputs necessarily produce the same, fully-replayable outputs. build qualifies: given source + deps, the products are those dist/, .next/ files; the cache stores them and spits them back next time. But dev is a long-running service (persistent); its "output" is a continuously-running process with no "final product" to cache; db:generate is subtler — its real effect is writing Prisma types into node_modules, and a Turbo cache hit only "replays the logs of that time" and doesn't actually re-write the files into node_modules (turbo.json has a comment specifically pointing this out), so caching it on a clean CI runner causes the weird failure of "logs say success, but the types weren't actually generated." This gives a universal criterion: whether a task can be cached depends on whether all its effects are captured in declarable outputs; any task with "side effects hidden elsewhere" (start a process, write node_modules, change external state) must be cache:false.
🎯 Key points · Part 10 wrap-up
  • pnpm monorepo: web/worker/packages/shared/ee in one repo; dependencies point only down (web/worker/ee → shared, shared doesn't reverse-depend); pnpm enforced (only-allow) + minimumReleaseAge against supply-chain poisoning. Shared code, atomic one-commit changes.
  • Turbo task pipeline: dependsOn's ^build lets Turbo auto-order builds topologically by the dependency graph (shared first, web/worker after), no hand-writing the order.
  • Turbo content-hash cache: hash the inputs (source+deps+env); if unchanged, replay cached outputs, skip the build — "rebuild only what actually changed," all cache hits on CI may pass in seconds. build/lint/typecheck/test are all cacheable.
  • Side-effecting tasks cache:false: dev (long-running service), db:generate (writes node_modules) — effects not in declarable outputs, unrestorable by log replay, must not cache. Criterion: are all effects captured in outputs?
  • One-command dev + seed: dx goes from empty environment to running in one command (install→docker infra→reset DBs→seed→dev); --filter scopes to one package; the seed CLI generates realistic test data by scenario (making bugs cheaply reproducible). Minimizing dev friction is the baseline of "maintainable."

🧪 Self-test - think about the design

1. Turborepo's content-hash cache makes Langfuse's multi-package builds fast. What's its core mechanism?
  1. compiles all packages in parallel regardless of changes
  2. compresses all packages into one file to speed up
  3. hash each task's inputs (source+deps+env vars); if the hash is identical to last time, directly replay the previously-cached outputs (dist/.next) and skip the real build. So when web changed but shared didn't, shared's cache replays in seconds and only web rebuilds — 'rebuild only what actually changed'
  4. caches database query results
Show answer & explanation click to expand
Answer: C. With dozens of packages, building everything every time would be unbearably slow. Turbo's key insight: a build task is essentially a pure function 'inputs→outputs', so if inputs are unchanged the output must be identical, no need to recompute. It hashes each task's full inputs (that package's source + the packages it depends on + relevant env vars) into a content hash; next run it compares hashes first, and on a hit spits back the previously-stored outputs (the dist/, .next/ declared in turbo.json) verbatim, fully skipping compilation. So when you changed one web file and shared is untouched, shared's input hash is unchanged, its cache replays in seconds, and Turbo dutifully rebuilds only web. This makes 'incremental build' live up to its name; on CI most packages unchanged, all cache hits, dozens of packages may pass in seconds.
2. In turbo.json, build/lint/test are cache:true, but dev and db:generate deliberately set cache:false. What's the criterion behind this distinction?
  1. whether a task can be cached depends on whether all its effects are captured in declarable outputs. build/lint produce definite files and are cacheable; but dev is a long-running service (no final product), db:generate writes Prisma types into node_modules (the cache only replays logs and can't restore this side effect) — any task with 'side effects hidden elsewhere' must be cache:false
  2. cache:false is to save disk space
  3. dev and db:generate run too fast for caching to matter
  4. only build artifacts are worth caching, nothing else
Show answer & explanation click to expand
Answer: A. Caching presupposes 'pure-functional': the same inputs necessarily produce the same, fully-replayable output. build qualifies — given source+deps, the products are those dist/, .next/ files, stored and spat back verbatim. But dev is a persistent long-running service; its 'output' is a continuously-running process with no cacheable 'final product'. db:generate is subtler: its real effect is writing Prisma-generated types into node_modules, and a Turbo cache hit only replays the logs of that time, not actually re-writing the files into node_modules (turbo.json has a comment pointing this out), so caching it on a clean CI runner causes the weird failure of 'logs say success but types weren't generated'. So the universal criterion: are all of a task's effects captured in declarable outputs? Any task with 'side effects hidden elsewhere' — starting a process, writing node_modules, changing external state — must be cache:false.
3. Langfuse puts web/worker/shared/ee in one monorepo rather than one repo per package (polyrepo). The most prominent benefit of a monorepo is?
  1. atomicity of cross-package changes: changing a shared interface and updating all the web/worker code calling it can be done in one commit, one PR, one CI run, never an intermediate broken state of 'shared released a new version but web hasn't upgraded'; plus frictionless code sharing and a unified toolchain
  2. a monorepo needs no build tools at all
  3. a monorepo makes each package's code smaller
  4. a monorepo automatically makes code run faster
Show answer & explanation click to expand
Answer: A. Under polyrepo (one repo per package), changing a widely-depended-on shared interface is painful: you must change and release in the shared repo first, then upgrade deps, fix calls, and release separately in the web and worker repos — during which there's inevitably an inconsistency window of 'shared is new, web is still old', and cross-repo atomicity simply can't be guaranteed. With a monorepo, such a change is one commit, one PR, one CI run, all-pass-or-all-fail, always consistent. Plus direct imports (no publishing), one lint/test/build config ruling all. The cost is a larger repo and heavier builds — which is exactly amortized by Turbo's cache. So 'monorepo + Turbo' often appear bundled: the former gives collaborative atomicity, the latter returns build speed.
💭 Open questions (no single right answer - just think or try)
  • This lesson (also the close of 'Platform & Operations') is about the developer's daily loop — the monorepo makes cross-package changes atomic, Turbo spends rebuild effort only where it changed, dx gets newcomers productive in one command, seed makes bugs cheaply reproducible. Recall projects you've joined: from cloning the code to getting it running, how many steps and how long? Which 'invisible engineering infrastructure' most affects your development happiness? If investing in 'developer experience' for a new project, which three things would you prioritize, and why?