Turborepo 实战:在 Monorepo 中共享 Tailwind CSS 主题与 React 组件库(with-tailwind 示例解析)

原创2026-09-18 09:04:191,839 阅读
文章标签:构建工具开发工具CLI

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 给出的理由有四点:

  1. 让 packages/tailwind-config/shared-styles.css 中定义的单一主题尽可能方便地共享给应用和包;
  2. 只依赖 Next.js 编译器与 tailwindcss 两个能力,使包编译保持简单;
  3. 确保 Tailwind 类名互不覆盖——ui 包通过 @import "tailwindcss" prefix(ui); 为自己的类加上 ui- 前缀;
  4. 保持清晰的包导出边界。

第 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-config flat 配置(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 管跨包拓扑。

登录后查看全文
turbo