Turborepo 示例中的 Next.js 应用实战基于examples/basic的apps/web开发、构建与部署指南【免费下载链接】turboBuild system optimized for JavaScript and TypeScript, written in Rust项目地址: https://gitcode.com/gh_mirrors/tu/turbo本指南以 Turborepo 官方 basic 示例中的apps/web应用为对象讲解在一个由 Rust 编写、专为 JavaScript/TypeScript 优化的构建系统 Turborepo 管理的 monorepo 中如何启动 Next.js 开发服务器、利用热更新迭代页面、集成共享 UI 包并完成构建与部署。读完本文你将掌握在examples/basic这一双 Next.js 应用 多个共享包的仓库结构中独立运行与交付web应用的完整实操路径。一、示例背景web应用在 monorepo 中的位置examples/basic是 Turborepo 官方维护的入门 starter其整体结构定义在根目录的 examples/basic/README.md 中它包含docs与web两个 Next.js 应用以及repo/ui共享 React 组件库、repo/eslint-configESLint 配置内置next/eslint-plugin-next与eslint-config-prettier、repo/typescript-config全仓库统一的tsconfig.json基座等包所有应用与包均为 100% TypeScript。本文的主角 examples/basic/apps/web/README.md 是web应用自身的引导文档。它本质上是一个由create-next-app生成的 Next.js 项目骨架说明但在 Turborepo 语境下它代表了 monorepo 中单个叶子应用的标准开发入口。web应用的关键依赖与脚本定义在 examples/basic/apps/web/package.jsonnext: 16.3.4、react / react-dom: 19.2.8工作区内部依赖repo/ui: workspace:*开发脚本devnext dev --port 3000、buildnext build、startnext start、linteslint --max-warnings 0、check-typesnext typegen tsc --noEmit。二、环境准备包管理器与依赖安装整个示例使用 pnpm 作为包管理器根 examples/basic/package.json 中packageManager指定为pnpm11.25.0engines.node要求24并通过 examples/basic/pnpm-workspace.yaml 声明工作区packages: - apps/* - packages/*这意味着apps/web与apps/docs自动成为工作区成员。安装全部依赖时在示例根目录执行pnpm install由于web通过workspace:*协议引用repo/uipnpm 会建立软链接使web可以像使用普通 npm 包一样import { Button } from repo/ui/button对应 examples/basic/packages/ui/package.json 中的./*: ./src/*.tsx导出映射而无需手工配置路径别名。三、启动开发服务器npm run dev与 Turborepo 的两种姿势原文档给出的启动方式是进入应用目录直接运行包管理器脚本npm run dev # or yarn dev # or pnpm dev # or bun dev四种方式等价最终都执行next dev --port 3000端口由 examples/basic/apps/web/package.json 的dev脚本显式指定为 3000。随后在浏览器打开 http://localhost:3000 即可看到页面。不过在 Turborepo 的 monorepo 中更常见的做法是从仓库根目录用turbo统一调度。在 examples/basic/README.md 中给出了两种写法# 全局安装 turbo推荐 turbo dev # 或通过包管理器按需调用 npx turbo dev pnpm exec turbo dev如果只想启动web这一个应用可以使用 filter 缩小任务范围turbo dev --filterweb这里dev任务的特殊之处体现在根 examples/basic/turbo.json 的配置中{ dev: { cache: false, persistent: true } }persistent: true表示该任务是一个不会自行结束的长驻进程开发服务器Turborepo 会据此调整调度与退出逻辑cache: false则表明开发模式不参与缓存——这也解释了为什么在根目录turbo dev时docs与web两个开发服务器可以并行常驻运行。四、热更新迭代编辑app/page.tsx即可即时生效原文档强调You can start editing the page by modifyingapp/page.tsx. The page auto-updates as you edit the file. 这正是 Next.js App Router 的热更新Fast Refresh机制。在 examples/basic/apps/web/app/page.tsx 中可以看到该示例页面的实际实现自定义ThemeImage组件通过srcLight/srcDark两个属性分别传入明暗主题下的 Logo 图turborepo-dark.svg与turborepo-light.svg利用next/image渲染由 examples/basic/apps/web/app/page.module.css 中的imgLight/imgDark类配合暗色模式控制显隐通过import { Button } from repo/ui/button使用共享组件库中的按钮这是 monorepo 内部依赖的直观演示——Button的实现位于 examples/basic/packages/ui/src/button.tsx它是一个标注了use client的客户端组件点击后弹出Hello from your ${appName} app!提示。这意味着你在 monorepo 中编辑任何一层代码都能获得即时反馈既包括web自己的页面与样式也包括repo/ui中的共享组件——只要 Turborepo 与 Next.js 的文件监听正常运行保存即可热更新。五、字体优化从next/font到本地字体加载原文档提到项目使用next/font自动优化并加载自定义 Google 字体 Inter。这一句来自create-next-app模板。在 Turborepo 的 basic 示例中实际实现有所演进根布局 examples/basic/apps/web/app/layout.tsx 改用next/font/local加载仓库本地字体文件import localFont from next/font/local; const geistSans localFont({ src: ./fonts/GeistVF.woff, variable: --font-geist-sans, }); const geistMono localFont({ src: ./fonts/GeistMonoVF.woff, variable: --font-geist-mono, });字体文件位于 examples/basic/apps/web/app/fontsGeistVF.woff 与 GeistMonoVF.woff。通过variable选项将字体挂载为 CSS 变量再在body上拼接geistSans.variable与geistMono.variable供 examples/basic/apps/web/app/globals.css 中的全局样式引用。无论采用 Inter 还是本地 Geist核心收益一致字体随页面自托管加载避免布局偏移CLS符合 Next.js 内置的最佳实践。六、构建、类型检查与产物缓存除了开发模式web应用还内置了生产构建与质量检查脚本npm run build # next build npm run start # next start生产模式运行 npm run lint # eslint --max-warnings 0任何 warning 都视为失败 npm run check-types # next typegen tsc --noEmit在根目录通过 Turborepo 执行时turbo build --filterweb turbo lint --filterweb turbo check-types --filterwebbuild任务在 examples/basic/turbo.json 中的定义值得关注build: { dependsOn: [^build], inputs: [$TURBO_DEFAULT$, .env*], outputs: [.next/**, !.next/cache/**, !.next/dev/**] }dependsOn: [^build]声明web的构建依赖其上游依赖repo/ui先完成构建Turborepo 会据此自动建立任务依赖图inputs参与哈希计算的输入$TURBO_DEFAULT$代表默认的文件集合源码等.env*将环境变量文件纳入缓存指纹outputs声明可缓存的产物目录.next/**同时排除!.next/cache/**与!.next/dev/**避免开发缓存污染构建缓存。这是 Turborepo 增量构建与缓存命中的核心机制当web的源码或依赖未变化时再次运行turbo build会直接复用上次的构建产物从而显著加速本地与 CI 的构建。七、部署将web应用发布到生产环境原文档建议使用 Vercel 平台部署 Next.js 应用并提示查阅 Next.js 官方部署文档。在 Turborepo 场景下部署web应用时通常需要告诉托管平台根目录是apps/webVercel 支持在项目设置中指定 Root Directory 为apps/web同时保留根目录的 lockfile 与turbo.json以便安装与构建。示例首页 examples/basic/apps/web/app/page.tsx 中的 Deploy now 按钮即指向 Vercel 的模板化部署入口整个 basic 示例也可直接从根 examples/basic/README.md 中描述的npx create-turbolatest一键生成后进行部署。八、继续深入仓库内的参考资源围绕web应用及其运行环境你可以在当前仓库中继续挖掘以下资源应用本体examples/basic/apps/web/app/page.tsx、examples/basic/apps/web/app/layout.tsx、examples/basic/apps/web/package.json共享依赖examples/basic/packages/ui/src/button.tsx、examples/basic/packages/ui/package.json任务编排examples/basic/turbo.json工作区与示例说明examples/basic/pnpm-workspace.yaml、examples/basic/README.md应用级工程配置examples/basic/apps/web/next.config.js、examples/basic/apps/web/tsconfig.json。此外apps/docs见 examples/basic/apps/docs/README.md与web结构完全对称可作为对照理解同一套 Turborepo 任务管线如何被多个 Next.js 应用共享。更完整的 Turborepo 任务、缓存与过滤机制可进一步查阅仓库根目录的 README.md 与示例目录中的其他示例。【免费下载链接】turboBuild system optimized for JavaScript and TypeScript, written in Rust项目地址: https://gitcode.com/gh_mirrors/tu/turbo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考