Turborepo with-yarn 示例中 Next.js docs 应用实战从 yarn dev 启动、端口规划到 monorepo 任务编排【免费下载链接】turboBuild system optimized for JavaScript and TypeScript, written in Rust项目地址: https://gitcode.com/gh_mirrors/tu/turbo本文以 Turborepo 官方with-yarn示例仓库中的docs应用Next.js 16为对象完整讲解如何在 Yarn Workspaces Turbo 2.9.6 的 monorepo 环境下启动开发服务器、按端口区分多应用、利用热更新迭代页面、创建 API 路由并深入背后由根目录turbo.json编排的dev/build/lint任务机制。读完本文你将能独立在 examples/with-yarn 示例中完成 docs 应用的开发、构建与调试并理解其与web应用共享依赖包的协作方式。一、docs 应用在 with-yarn 示例中的定位examples/with-yarn是一个采用Yarn Workspaces组织依赖的 Turborepo 示例。按照其 README.md 的说明仓库内部包含两类 Next.js 应用和三个共享包apps/docs一个 Next.js 应用即本文的主角apps/web另一个 Next.js 应用与 docs 并列packages/uirepo/ui被web与docs共同使用的 React 组件库packages/eslint-configrepo/eslint-config包含eslint-config-next与eslint-config-prettier的 ESLint 配置packages/typescript-configrepo/typescript-config贯穿整个 monorepo 的tsconfig.json共享配置。依赖的划分在根目录 package.json 中通过workspaces: [apps/*, packages/*]声明这意味着yarn会在安装阶段一次性解析所有应用与包的依赖。根目录同时锁定了turbo: 2.9.6、packageManager: yarn1.22.22以及node 18的运行前提任何命令都应在该版本组合下执行。二、快速启动yarn dev 与端口规划docs 应用的 README.md 给出最直接的启动方式yarn dev然后在浏览器中打开 http://localhost:3001 即可看到页面。为什么是 3001 而不是默认的 3000docs 应用与web应用同处一个 monorepo若两者都占用 3000 端口必然冲突。查看 apps/docs/package.json 的 scripts 可以发现答案scripts: { dev: next dev --port 3001, build: next build, start: next start, lint: eslint . --max-warnings 0 }dev脚本显式携带了--port 3001对照 apps/web/package.json 中web应用的dev: next dev默认 3000两个应用形成web 跑 3000、docs 跑 3001的端口分工。因此在该示例中访问 3001 看到的是 docs 应用访问 3000 则是 web 应用。需要注意的是在仓库根目录直接执行yarn dev时实际触发的是根目录 package.json 中dev: turbo run dev脚本由 Turbo 同时调度两个应用的dev任务而进入apps/docs目录后再执行yarn dev则只启动 docs 这一个应用。三、页面热更新与 app 目录约定docs 应用采用 Next.js 的 App Router 约定。默认页面位于 apps/docs/app/page.tsx文档明确指出你可以通过修改app/page.tsx开始编辑页面文件保存后页面会自动更新。这一点在源码中也有印证page.tsx导出了一个默认Page组件内部引用了共享包中的Card与Code组件import Image from next/image; import { Card } from repo/ui/card; import { Code } from repo/ui/code; import styles from ./page.module.css;页面布局、Logo 与卡片网格则由 apps/docs/app/layout.tsx 与 apps/docs/app/page.module.css 共同支撑。整个应用 100% 使用 TypeScript入口类型声明在 apps/docs/tsconfig.json。共享组件为何能直接编译docs 的next.config.jsexamples/with-yarn/apps/docs/next.config.js中有一行关键配置module.exports { transpilePackages: [repo/ui], };由于repo/ui是一个 monorepo 内部包在 packages/ui/package.json 中通过exports暴露了./card与./code两个子路径Next.js 默认不转译node_modules下的源码因此需要transpilePackages显式声明让 docs 应用能直接编译共享包的 TypeScript 源码。这是所有以源码形式共享内部包的 Next.js 应用都必须理解的关键点。四、创建 API 路由从 route.ts 到端点映射docs 的 README 给出了在 App Router 下创建 API 路由的标准做法在app/目录下新建api/目录并放入route.ts文件即可创建 API 路由若需要独立端点可在api目录下创建子目录例如api/hello/route.ts会映射到 http://localhost:3001/api/hello。由于 docs 应用运行在 3001 端口其 API 端点也统一挂在该端口下与页面访问地址保持一致。这一约定与 Next.js App Router 的文件系统路由规则一致route.ts文件名与目录层级直接决定 URL 路径。五、深入 monorepo 任务编排turbo.json 如何驱动 yarn devdocs 应用之所以能在根目录一键启动依赖的是 Turbo 的任务编排能力。根目录 turbo.json 定义了三个任务的全局策略{ $schema: https://turborepo.dev/schema.json, tasks: { build: { dependsOn: [^build], inputs: [$TURBO_DEFAULT$, .env*], outputs: [.next/**, !.next/cache/**, !.next/dev/**] }, lint: { dependsOn: [^lint] }, dev: { cache: false, persistent: true } } }对 docs 应用而言这三段配置的影响分别是build增量构建与产物缓存dependsOn: [^build]表示先构建所有依赖包如repo/ui再构建应用本身inputs声明了参与哈希计算的输入默认文件集合加.env*outputs指定缓存产物为.next/**但排除.next/cache与.next/dev避免将 Next.js 自身缓存写入 Turbo 的缓存层。lint依赖顺序dependsOn: [^lint]保证先 lint 依赖包再 lint 应用。docs 的 lint 脚本为eslint . --max-warnings 0任何 warning 都会导致任务失败属于较严格的约束。dev开发服务器cache: false表示开发服务器不做缓存开发过程无需缓存命中persistent: true声明该任务是常驻进程——因为next dev不会自行退出Turbo 需将其标记为 persistent 才能正确进行进程管理配合--port 3001实现两个应用并行开发互不干扰。六、构建与代码质量检查除了yarn devdocs 应用还支持完整的构建与检查流程既可在应用目录内单独执行也可在仓库根目录通过 Turbo 统一调度# 在 apps/docs 目录内单独操作 yarn build # next build yarn start # 以生产模式启动 yarn lint # eslint . --max-warnings 0 # 在仓库根目录统一调度所有应用与包 yarn build # turbo run build yarn lint # turbo run lint根目录的format脚本prettier --write **/*.{ts,tsx,md}则负责全仓库的代码格式化docs 应用下的 TypeScript 与 Markdown 文件同样被覆盖。七、进一步探索远程缓存与部署作为 Turborepo 的核心能力之一该示例还支持远程缓存Remote Caching默认情况下 Turbo 只在本地缓存构建产物通过远程缓存可以将缓存工件跨机器共享给团队与 CI/CD 流水线。参考 examples/with-yarn/README.md 中的说明启用流程为cd my-turborepo npx turbo login # 使用 Vercel 账号认证 Turbo CLI npx turbo link # 将当前仓库链接到远程缓存docs 应用本身是一个标准的 Next.js 应用其生产构建产物位于.next/目录可直接部署到支持 Next.js 的平台。应用内的页面组件见 apps/docs/app/page.tsx已内置了指向 Turborepo 文档、教程与模板的导航卡片作为 monorepo 示例的展示入口。八、关键文件索引示例总览与远程缓存说明examples/with-yarn/README.md根依赖与 workspace 声明examples/with-yarn/package.json任务编排与缓存策略examples/with-yarn/turbo.jsondocs 应用脚本与依赖examples/with-yarn/apps/docs/package.jsondocs 应用共享包转译配置examples/with-yarn/apps/docs/next.config.jsdocs 应用默认页面examples/with-yarn/apps/docs/app/page.tsx共享 UI 组件包examples/with-yarn/packages/ui/package.jsonweb 应用脚本端口对照examples/with-yarn/apps/web/package.json【免费下载链接】turboBuild system optimized for JavaScript and TypeScript, written in Rust项目地址: https://gitcode.com/gh_mirrors/tu/turbo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/19 11:16:02 · 阅读 1.2k Turborepo with-yarn 示例中 Next.js docs 应用实战：从 yarn dev 启动、端口规划到 monorepo 任务编排
Turborepo with-yarn 示例中 Next.js docs 应用实战从 yarn dev 启动、端口规划到 monorepo 任务编排【免费下载链接】turboBuild system optimized for JavaScript and TypeScript, written in Rust项目地址: https://gitcode.com/gh_mirrors/tu/turbo本文以 Turborepo 官方with-yarn示例仓库中的docs应用Next.js 16为对象完整讲解如何在 Yarn Workspaces Turbo 2.9.6 的 monorepo 环境下启动开发服务器、按端口区分多应用、利用热更新迭代页面、创建 API 路由并深入背后由根目录turbo.json编排的dev/build/lint任务机制。读完本文你将能独立在 examples/with-yarn 示例中完成 docs 应用的开发、构建与调试并理解其与web应用共享依赖包的协作方式。一、docs 应用在 with-yarn 示例中的定位examples/with-yarn是一个采用Yarn Workspaces组织依赖的 Turborepo 示例。按照其 README.md 的说明仓库内部包含两类 Next.js 应用和三个共享包apps/docs一个 Next.js 应用即本文的主角apps/web另一个 Next.js 应用与 docs 并列packages/uirepo/ui被web与docs共同使用的 React 组件库packages/eslint-configrepo/eslint-config包含eslint-config-next与eslint-config-prettier的 ESLint 配置packages/typescript-configrepo/typescript-config贯穿整个 monorepo 的tsconfig.json共享配置。依赖的划分在根目录 package.json 中通过workspaces: [apps/*, packages/*]声明这意味着yarn会在安装阶段一次性解析所有应用与包的依赖。根目录同时锁定了turbo: 2.9.6、packageManager: yarn1.22.22以及node 18的运行前提任何命令都应在该版本组合下执行。二、快速启动yarn dev 与端口规划docs 应用的 README.md 给出最直接的启动方式yarn dev然后在浏览器中打开 http://localhost:3001 即可看到页面。为什么是 3001 而不是默认的 3000docs 应用与web应用同处一个 monorepo若两者都占用 3000 端口必然冲突。查看 apps/docs/package.json 的 scripts 可以发现答案scripts: { dev: next dev --port 3001, build: next build, start: next start, lint: eslint . --max-warnings 0 }dev脚本显式携带了--port 3001对照 apps/web/package.json 中web应用的dev: next dev默认 3000两个应用形成web 跑 3000、docs 跑 3001的端口分工。因此在该示例中访问 3001 看到的是 docs 应用访问 3000 则是 web 应用。需要注意的是在仓库根目录直接执行yarn dev时实际触发的是根目录 package.json 中dev: turbo run dev脚本由 Turbo 同时调度两个应用的dev任务而进入apps/docs目录后再执行yarn dev则只启动 docs 这一个应用。三、页面热更新与 app 目录约定docs 应用采用 Next.js 的 App Router 约定。默认页面位于 apps/docs/app/page.tsx文档明确指出你可以通过修改app/page.tsx开始编辑页面文件保存后页面会自动更新。这一点在源码中也有印证page.tsx导出了一个默认Page组件内部引用了共享包中的Card与Code组件import Image from next/image; import { Card } from repo/ui/card; import { Code } from repo/ui/code; import styles from ./page.module.css;页面布局、Logo 与卡片网格则由 apps/docs/app/layout.tsx 与 apps/docs/app/page.module.css 共同支撑。整个应用 100% 使用 TypeScript入口类型声明在 apps/docs/tsconfig.json。共享组件为何能直接编译docs 的next.config.jsexamples/with-yarn/apps/docs/next.config.js中有一行关键配置module.exports { transpilePackages: [repo/ui], };由于repo/ui是一个 monorepo 内部包在 packages/ui/package.json 中通过exports暴露了./card与./code两个子路径Next.js 默认不转译node_modules下的源码因此需要transpilePackages显式声明让 docs 应用能直接编译共享包的 TypeScript 源码。这是所有以源码形式共享内部包的 Next.js 应用都必须理解的关键点。四、创建 API 路由从 route.ts 到端点映射docs 的 README 给出了在 App Router 下创建 API 路由的标准做法在app/目录下新建api/目录并放入route.ts文件即可创建 API 路由若需要独立端点可在api目录下创建子目录例如api/hello/route.ts会映射到 http://localhost:3001/api/hello。由于 docs 应用运行在 3001 端口其 API 端点也统一挂在该端口下与页面访问地址保持一致。这一约定与 Next.js App Router 的文件系统路由规则一致route.ts文件名与目录层级直接决定 URL 路径。五、深入 monorepo 任务编排turbo.json 如何驱动 yarn devdocs 应用之所以能在根目录一键启动依赖的是 Turbo 的任务编排能力。根目录 turbo.json 定义了三个任务的全局策略{ $schema: https://turborepo.dev/schema.json, tasks: { build: { dependsOn: [^build], inputs: [$TURBO_DEFAULT$, .env*], outputs: [.next/**, !.next/cache/**, !.next/dev/**] }, lint: { dependsOn: [^lint] }, dev: { cache: false, persistent: true } } }对 docs 应用而言这三段配置的影响分别是build增量构建与产物缓存dependsOn: [^build]表示先构建所有依赖包如repo/ui再构建应用本身inputs声明了参与哈希计算的输入默认文件集合加.env*outputs指定缓存产物为.next/**但排除.next/cache与.next/dev避免将 Next.js 自身缓存写入 Turbo 的缓存层。lint依赖顺序dependsOn: [^lint]保证先 lint 依赖包再 lint 应用。docs 的 lint 脚本为eslint . --max-warnings 0任何 warning 都会导致任务失败属于较严格的约束。dev开发服务器cache: false表示开发服务器不做缓存开发过程无需缓存命中persistent: true声明该任务是常驻进程——因为next dev不会自行退出Turbo 需将其标记为 persistent 才能正确进行进程管理配合--port 3001实现两个应用并行开发互不干扰。六、构建与代码质量检查除了yarn devdocs 应用还支持完整的构建与检查流程既可在应用目录内单独执行也可在仓库根目录通过 Turbo 统一调度# 在 apps/docs 目录内单独操作 yarn build # next build yarn start # 以生产模式启动 yarn lint # eslint . --max-warnings 0 # 在仓库根目录统一调度所有应用与包 yarn build # turbo run build yarn lint # turbo run lint根目录的format脚本prettier --write **/*.{ts,tsx,md}则负责全仓库的代码格式化docs 应用下的 TypeScript 与 Markdown 文件同样被覆盖。七、进一步探索远程缓存与部署作为 Turborepo 的核心能力之一该示例还支持远程缓存Remote Caching默认情况下 Turbo 只在本地缓存构建产物通过远程缓存可以将缓存工件跨机器共享给团队与 CI/CD 流水线。参考 examples/with-yarn/README.md 中的说明启用流程为cd my-turborepo npx turbo login # 使用 Vercel 账号认证 Turbo CLI npx turbo link # 将当前仓库链接到远程缓存docs 应用本身是一个标准的 Next.js 应用其生产构建产物位于.next/目录可直接部署到支持 Next.js 的平台。应用内的页面组件见 apps/docs/app/page.tsx已内置了指向 Turborepo 文档、教程与模板的导航卡片作为 monorepo 示例的展示入口。八、关键文件索引示例总览与远程缓存说明examples/with-yarn/README.md根依赖与 workspace 声明examples/with-yarn/package.json任务编排与缓存策略examples/with-yarn/turbo.jsondocs 应用脚本与依赖examples/with-yarn/apps/docs/package.jsondocs 应用共享包转译配置examples/with-yarn/apps/docs/next.config.jsdocs 应用默认页面examples/with-yarn/apps/docs/app/page.tsx共享 UI 组件包examples/with-yarn/packages/ui/package.jsonweb 应用脚本端口对照examples/with-yarn/apps/web/package.json【免费下载链接】turboBuild system optimized for JavaScript and TypeScript, written in Rust项目地址: https://gitcode.com/gh_mirrors/tu/turbo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考