Turborepo 实战:在 Monorepo 中共享 Tailwind CSS 主题与 React 组件库(with-tailwind 示例解析)
Turborepo 实战:在 Monorepo 中共享 Tailwind CSS 主题与 React 组件库(with-tailwind 示例解析)
本篇以 Turborepo 仓库中官方维护的 with-tailwind 示例工程为主体,拆解“多个 Next.js 应用共享同一套 Tailwind CSS 主题、并共用一个 React 组件库”的完整落地方案。读完后,你将掌握:如何组织 ui 组件包的构建产物与 exports 边界、如何通过共享包分发 Tailwind 主题与 PostCSS 配置,以及如何为样式编译、组件编译配置可缓存、可并发的 Turborepo 任务图。
示例定位与快速上手
examples/with-tailwind 是由 Turborepo 核心团队维护的官方 starter,可在 Turborepo 仓库中直接查看其 README。按照文档说明,通过以下命令可以基于该模板脚手架出完整工程:
npx create-turbo@latest -e with-tailwind
从仓库中的根 package.json 可以看到该模板的运行时前提:
- 包管理器固定为
pnpm@11.22.0(packageManager字段),工作区由 pnpm-workspace.yaml 定义; - 要求
node >= 24; - 根目录内置
turbo 2.10.10以及prettier+prettier-plugin-tailwindcss(用于 Tailwind 类名的排序格式化),根级脚本build、dev、lint、check-types、format全部委托给turbo run执行。
仓库结构:两个 Next.js 应用与三个共享包
该模板的组织方式(见 README)是:
| 名称 | 角色 |
|---|---|
docs |
一个 Next.js 应用,使用 Tailwind CSS |
web |
另一个 Next.js 应用,使用 Tailwind CSS |
ui |
一个存根(轻量)React 组件库,被 web 与 docs 共同消费,使用 Tailwind CSS |
@repo/tailwind-config |
共享的 Tailwind CSS 主题与 PostCSS 配置 |
@repo/eslint-config |
ESLint flat 配置(包含 @next/eslint-plugin-next 与 eslint-config-prettier) |
@repo/typescript-config |
全仓库共用的 tsconfig.json 基线 |
每个包/应用都 100% 使用 TypeScript。对应到仓库目录,组件库源码位于 packages/ui/src(包含 card.tsx、gradient.tsx、turborepo-logo.tsx 等组件),两个应用分别位于 apps/web 与 apps/docs,共享包位于 packages/tailwind-config、packages/eslint-config、packages/typescript-config。
共享 Tailwind 主题:@repo/tailwind-config
Tailwind CSS v4 采用 CSS-first 配置:主题不再写在 tailwind.config.js 中,而是通过 CSS 的 @theme 块直接声明。模板把这套主题集中放在共享包 shared-styles.css 中:
@import "tailwindcss";
@theme {
--color-blue-1000: #2a8af6;
--color-purple-1000: #a853ba;
--color-red-1000: #e92a67;
}
任意应用只要在自己的 CSS 入口里 @import "@repo/tailwind-config";,即可复用同一套自定义颜色令牌。以 web 应用的入口样式 globals.css 为例:
@import "tailwindcss";
@import "@repo/tailwind-config";
:root {
--foreground-rgb: 0, 0, 0;
--background-start-rgb: 214, 219, 220;
--background-end-rgb: 255, 255, 255;
}
/* prefers-color-scheme: dark 下覆盖为深色变量 */
body {
color: rgb(var(--foreground-rgb));
background: linear-gradient(...) rgb(var(--background-start-rgb));
}
PostCSS 侧的配置同样被收进共享包。postcss.config.js 导出一个可复用的对象:
// Optional PostCSS configuration for applications that need it
export const postcssConfig = {
plugins: {
"@tailwindcss/postcss": {},
},
};
应用端的 postcss.config.js 因此只有三行——转手导出共享配置:
import { postcssConfig } from "@repo/tailwind-config/postcss";
export default postcssConfig;
docs 应用采用完全相同的接入方式。这套“主题、PostCSS 配置各放一处,应用只做 import”的做法,是 v4 CSS-first 工作流在多包仓库中避免配置漂移的关键。
构建策略:ui 组件库的产物化构建
这是该示例最有技术含量的部分。模板为 ui 包选择的策略是:样式编译产物与组件编译产物都进入 dist,消费方拿到的全部是构建后的文件,而组件 .tsx 源码则由 Next.js 侧配合处理。README 给出的理由有四点:
- 让
packages/tailwind-config/shared-styles.css中定义的单一主题尽可能方便地共享给应用和包; - 只依赖 Next.js 编译器与
tailwindcss两个能力,使包编译保持简单; - 确保 Tailwind 类名互不覆盖——
ui包通过@import "tailwindcss" prefix(ui);为自己的类加上ui-前缀; - 保持清晰的包导出边界。
第 3 点在 packages/ui/src/styles.css 中只有三行,却定义了组件包样式的隔离方式:
/* Component-level styles for the UI package */
@import "tailwindcss" prefix(ui);
@import "@repo/tailwind-config";
prefix(ui) 使该包生成的工具类都带 ui- 前缀,与宿主应用自身无 ui- 前缀的类形成天然隔离,从源码结构看这正是“确保 Tailwind 类不互相覆盖”的实现机制。
再看 packages/ui/package.json 中的导出与脚本设计:
{
"name": "@repo/ui",
"sideEffects": ["**/*.css"],
"files": ["dist"],
"exports": {
"./styles.css": "./dist/index.css",
"./*": "./dist/*.js"
},
"scripts": {
"build:styles": "tailwindcss -i ./src/styles.css -o ./dist/index.css",
"build:components": "tsc",
"check-types": "tsc --noEmit",
"dev:styles": "tailwindcss -i ./src/styles.css -o ./dist/index.css --watch",
"dev:components": "tsc --watch",
"lint": "eslint src --max-warnings 0"
}
}
要点:
exports是清晰的边界声明:./styles.css精确映射到dist/index.css(由 Tailwind CLI 从src/styles.css编译而来),./*映射到dist/*.js(tsc编译产物);files: ["dist"]与sideEffects: ["**/*.css"]保证发布面最小化、且 CSS 不会被打包器当作无副作用文件误删;- 开发/构建脚本一一对应:
build:styles/dev:styles、build:components/dev:components,开发态都带--watch。
一个值得注意的细节:README 提到 .tsx 组件文件通过 next.config.ts 中的 transpilePackages 被 Next.js 应用直接消费;而从当前仓库的 apps/web/next.config.ts 看,文件内只配置了 typescript: { ignoreBuildErrors: true },且 @repo/ui 的 exports 已把 ./* 指向 dist/*.js 编译产物。可以推断,当前仓库版本已将组件消费路径收敛为“tsc 编译产物”,而 transpilePackages 对应的是直接从源码消费的另一种可选配置——两种方式的取舍在下文“替代方案”中进一步展开。
组件编译由 packages/ui/tsconfig.json 控制,继承共享的 react-library.json 基线,并将 rootDir/outDir 锁定为 src → dist:
{
"extends": "@repo/typescript-config/react-library.json",
"compilerOptions": {
"outDir": "dist",
"rootDir": "src",
"strictNullChecks": true
},
"include": ["src"],
"exclude": ["dist", "build", "node_modules"]
}
替代方案:直接从源码消费 ui 包
模板同时给出“不构建、直接从源码消费 packages/ui”的可行路径。Tailwind CSS v4 会自动检测源码文件中的类名,但不会扫描 node_modules 中其他包的内容。若选择该方案,需要在应用的 CSS 入口中显式添加 @source 指令,让 Tailwind 找到 ui 包使用的类名:
@import "tailwindcss";
@import "@repo/tailwind-config";
@source "../../../packages/ui/src";
选择这种策略后,即可从 ui 包中移除 tailwindcss 依赖与 build:styles 脚本,样式完全由宿主应用统一生成。两种方案的本质区别是:产物化构建用“前缀 + 独立 CSS 产物”换取包边界清晰、应用零改动;源码消费则用 @source 换取更少的构建环节,但要求每个消费方都记得声明源码路径。
任务图:让样式与组件编译可缓存、可并行
ui 包的 turbo.json 展示了任务依赖与持久化任务的组合方式:
{
"extends": ["//"],
"tasks": {
"build": {
"dependsOn": ["build:styles", "build:components"]
},
"build:styles": {
"outputs": ["dist/**"]
},
"build:components": {
"outputs": ["dist/**"]
},
"dev": {
"with": ["dev:styles", "dev:components"]
},
"dev:styles": {
"cache": false,
"persistent": true
},
"dev:components": {
"cache": false,
"persistent": true
}
}
}
可以读出三层设计:
"extends": <a href="https://link.gitcode.com/i/90278789d64d4f678bc455461ba80f9b" target="_blank">"//"]使该包继承仓库根的 [turbo.json 全局任务配置;- 构建侧
build依赖build:styles与build:components两个子任务,两者都声明outputs: ["dist/**"],Turborepo 因此能对dist产物做增量缓存; - 开发侧
dev用with同时拉起两个watch进程,并统一标记cache: false, persistent: true,使其不被缓存、且作为长驻进程运行。
根 turbo.json 则定义了跨包的任务拓扑:
{
"$schema": "https://turborepo.dev/schema.json",
"ui": "tui",
"tasks": {
"build": {
"dependsOn": ["^build"],
"inputs": ["$TURBO_DEFAULT$", ".env*"],
"outputs": ["dist/**", ".next/**", "!.next/cache/**", "!.next/dev/**"]
},
"lint": {
"dependsOn": ["^lint"]
},
"check-types": {
"dependsOn": ["^build", "^check-types"]
},
"dev": {
"cache": false,
"persistent": true
}
}
}
其中 build.dependsOn: ["^build"] 保证依赖包(如 @repo/ui)先于消费它的 web/docs 完成构建;check-types 依赖上游的 ^build 与 ^check-types,使类型检查基于已就绪的依赖产物执行;outputs 中用 ! 排除 .next/cache 与 .next/dev,避免把 Next.js 的缓存目录计入产物哈希。对 ui 包而言,其包级 turbo.json 覆盖的 build 任务(build:styles + build:components)会叠加在这条拓扑上,形成“ui 样式/组件 → 应用构建”的完整 DAG。
工程化工具链:TypeScript、ESLint 与 Prettier
模板预置的通用工具链(见 README):
- Tailwind CSS 负责样式;
- TypeScript 负责静态类型检查(各应用/包的
check-types脚本通过tsc --noEmit执行,web应用还会先跑next typegen); - ESLint 负责代码检查,配置来自共享的
@repo/eslint-configflat 配置(base.js、next.js、react-internal.js),ui包以eslint src --max-warnings 0保持零警告; - Prettier 负责代码格式化,根脚本
format执行prettier --write "**/*.{ts,tsx,md}",并配合prettier-plugin-tailwindcss对 Tailwind 类名排序。
类型基线由 packages/typescript-config 中的 base.json、nextjs.json、react-library.json 三个文件按应用类型分发,ui 包继承其中的 react-library.json(如上文 tsconfig.json 所示)。
要点回顾
- 模板获取:
npx create-turbo@latest -e with-tailwind,pnpm 工作区 + Node >= 24 + Turborepo 2.10.x; - 主题共享:Tailwind v4 的
@theme令牌集中在@repo/tailwind-config/shared-styles.css,PostCSS 配置以导出对象形式被各应用postcss.config.js转手复用; - 组件包边界:
exports+files+sideEffects三者配合,消费方只接触dist产物;prefix(ui)隔离类名冲突; - 任务编排:包级
turbo.json用extends: ["//"]、dependsOn、outputs、persistent把“样式编译”与“组件编译”纳入统一的可缓存 DAG; - 可替换路径:Tailwind v4 的
@source指令支持跳过ui包构建、直接扫描其源码,代价是样式生成收敛到宿主应用。
整套方案可以直接作为多前端应用 monorepo 中“共享设计系统 + 组件库”的参考骨架:共享包管配置与主题,包级 turbo.json 管构建细节,根 turbo.json 管跨包拓扑。