Tailwind CSS Academy · 课时

在单体仓库中扩展 Tailwind

在单体仓库的多个软件包之间共享单个 tailwind.config.js，使用预设共享令牌，并管理工作区专属扩展。

第 4 / 4 课13 个步骤

在单体仓库中扩展 Tailwind 是 CoddyKit 上的免费 Tailwind CSS Academy 课时。这是第 4 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Tailwind CSS Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Tailwind CSS Academy 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

Monorepo Basics for Tailwind

A monorepo is a single repository containing multiple packages or applications, managed with tools like Turborepo, Nx, or pnpm workspaces. When multiple apps in a monorepo use Tailwind, sharing configuration becomes important. Without sharing, each app duplicates color tokens, fonts, and plugin configurations — diverging gradually until the UI is inconsistent across products.

monorepo/
├── apps/
│   ├── web/          # Next.js marketing site
│   └── dashboard/    # React admin app
├── packages/
│   ├── ui/           # Shared component library
│   └── tailwind-config/  # ← Shared Tailwind config
├── package.json      # Workspace root
└── turbo.json

Creating a Shared Config Package

Extract the Tailwind configuration into a dedicated package, typically called @repo/tailwind-config or @acme/tailwind-config. This package exports a base configuration object that each consuming app imports and extends. The shared package lives in packages/tailwind-config/ with its own package.json marking it as an internal dependency.

// packages/tailwind-config/package.json
{
  "name": "@acme/tailwind-config",
  "version": "0.0.1",
  "private": true,
  "main": "./tailwind.config.js",
  "devDependencies": {
    "tailwindcss": "^3.4.0"
  }
}

// packages/tailwind-config/tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: { 500: '#3b82f6', 900: '#1e3a8a' },
      },
    },
  },
  plugins: [],
};

Consuming the Shared Config

Each app imports the shared config using require and spreads or merges it with app-specific overrides. The app's tailwind.config.js adds its own content paths (since content paths are always app-specific) and any extensions unique to that application. The shared config handles all common theme tokens and plugins.

// apps/web/tailwind.config.js
const sharedConfig = require('@acme/tailwind-config');

/** @type {import('tailwindcss').Config} */
module.exports = {
  // Merge shared config
  ...sharedConfig,
  // App-specific content paths (NEVER shared — paths differ per app)
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './public/**/*.html',
  ],
  theme: {
    ...sharedConfig.theme,
    extend: {
      ...sharedConfig.theme.extend,
      // App-specific extensions
      backgroundImage: {
        'hero-gradient': 'linear-gradient(to bottom, #eff6ff, #ffffff)',
      },
    },
  },
};

Using Tailwind Presets

Tailwind's preset system is the officially supported mechanism for sharing configs. A preset is an object passed to the presets array in the consuming config. Unlike spreading the config object, presets are merged intelligently by Tailwind — theme extensions are deep-merged, plugins are concatenated, and content arrays are combined without manual spreading.

// packages/tailwind-config/tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    extend: {
      colors: { brand: { 500: '#3b82f6' } },
    },
  },
  plugins: [require('@tailwindcss/forms')],
};

// apps/dashboard/tailwind.config.js
module.exports = {
  presets: [require('@acme/tailwind-config')],  // ← official preset
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      // Deep-merged with preset's theme.extend automatically
      spacing: { 18: '4.5rem' },
    },
  },
};

Shared UI Package Content Paths

A critical monorepo pitfall: if you have a shared packages/ui component library that exports Tailwind-classed components, the consuming app must include that package's files in its content array. Otherwise the JIT engine does not scan the shared components, and the classes used there get purged from the production build.

// apps/web/tailwind.config.js
module.exports = {
  presets: [require('@acme/tailwind-config')],
  content: [
    // App's own files
    './src/**/*.{js,ts,jsx,tsx}',
    // ⬇ CRITICAL: include shared UI package files
    '../../packages/ui/src/**/*.{js,ts,jsx,tsx}',
  ],
};

Workspace Dependencies Setup

In a pnpm or npm workspace monorepo, add the shared config package as a dev dependency using the workspace protocol. This creates a symlink to the local package without publishing it to npm. The consuming app's package.json lists @acme/tailwind-config: workspace:* and the build tools resolve it to the local package automatically.

// apps/web/package.json
{
  "name": "web",
  "devDependencies": {
    "@acme/tailwind-config": "workspace:*",
    "tailwindcss": "^3.4.0"
  }
}

// Install all workspace packages from the monorepo root:
pnpm install
# or
npm install --workspaces

Turborepo Caching for Tailwind Builds

In a Turborepo monorepo, configure the turbo.json pipeline to cache Tailwind build outputs. Because the shared config is a dependency of each app's build, changes to packages/tailwind-config correctly invalidate the build cache for all consuming apps. This prevents stale cached CSS from shipping when the design system updates.

// turbo.json
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**", "!.next/cache/**"]
    },
    "type-check": {
      "dependsOn": ["^build"]
    }
  }
}

# Build only what has changed since last run:
npx turbo build
# Turbo caches CSS output and invalidates when tailwind-config changes

Handling Content Path Differences

Content paths are the one configuration that cannot be shared — they must be local to each app. Different apps have different directory structures. Avoid temptation to put content paths in the shared config; doing so would either miss files or scan too broadly. The shared config should export only theme, plugins, and presets. Content is always defined locally in each consuming app's config.

// packages/tailwind-config/tailwind.config.js
// ⚠ DO NOT include content paths here
module.exports = {
  // content: []  ← Leave this OUT of the shared config
  theme: {
    extend: { colors: { brand: { 500: '#3b82f6' } } },
  },
  plugins: [],
};

// Each app defines its own content:
// apps/web: './src/**/*.{js,ts,jsx,tsx}'
// apps/dashboard: './pages/**/*.tsx', './components/**/*.tsx'

Versioning the Shared Config

Even though the shared config package is private (never published to npm), treat it with version discipline. Bump its version in package.json on every breaking change — removing a color, renaming a token, removing a plugin. Consumers of the preset can then pin to a version and upgrade deliberately rather than having breaking changes silently propagate to all apps at once.

// packages/tailwind-config/package.json
{
  "name": "@acme/tailwind-config",
  "version": "1.3.0",   // ← bump on breaking changes
  "private": true,
  "main": "./tailwind.config.js"
}

// apps/dashboard/package.json — pin to a specific version
{
  "devDependencies": {
    "@acme/tailwind-config": "workspace:^1.2.0"  // pin minor version
  }
}

Testing Shared Config Changes

Before merging changes to the shared Tailwind config, run a visual regression test on all consuming apps. A change to a brand color or a removed spacing value affects every app simultaneously. Build all apps in CI (turbo build) and run screenshot comparison on key pages. Treat config changes as cross-app breaking changes and communicate them in changelogs.

# Run all affected builds when tailwind-config changes
npx turbo build --filter='...[origin/main]'
# Turborepo detects which apps depend on the changed package
# and builds only those apps

# Run visual regression on changed apps:
npx playwright test --project=web
npx playwright test --project=dashboard

Storybook Integration in Monorepos

If you use Storybook in the shared UI package to document components, configure Storybook to use the same shared Tailwind preset. Add the Storybook Tailwind addon (@storybook/addon-styling-webpack or framework equivalent) and point it to the shared config. This ensures components render in Storybook with the same tokens they use in the apps.

// packages/ui/.storybook/main.js
module.exports = {
  addons: ['@storybook/addon-styling-webpack'],
  framework: '@storybook/react-webpack5',
};

// packages/ui/.storybook/preview.js
import '../src/styles/globals.css'; // imports Tailwind

// packages/ui/tailwind.config.js
module.exports = {
  presets: [require('@acme/tailwind-config')],
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
};

Quick Check

Test your understanding of Tailwind CSS Mastery concepts from this lesson.

在交互式课程中回答

Lesson Recap

In this lesson you learned: creating a shared Tailwind config package using the official preset system for intelligent deep-merging, including shared UI package files in content paths to prevent class purging, and treating config changes as cross-app breaking changes with versioning and visual regression tests. Next up we plan a complete Tailwind design system for the capstone project.

免费开始

用 AI 导师学习 HTML — 免费

在浏览器中编写并运行真实代码，获得全天候 AI 导师的即时帮助，并在网页或应用中继续学习。

课程: 30
课程: 120

免费开始学习查看完整课程

常见问题解答

「在单体仓库中扩展 Tailwind」课时是免费的吗？

是的 — 「在单体仓库中扩展 Tailwind」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Tailwind CSS Academy 课程的其余内容，请升级到 CoddyKit PRO。 Tailwind CSS Academy 课程共包含 4 节课。

「在单体仓库中扩展 Tailwind」这节课中我会学到什么？

在单体仓库的多个软件包之间共享单个 tailwind.config.js，使用预设共享令牌，并管理工作区专属扩展。你通过在浏览器中直接运行的动手代码来练习 Tailwind CSS Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Tailwind CSS Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Tailwind CSS Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 4 节课，共 4 节。

「在单体仓库中扩展 Tailwind」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Tailwind CSS Academy 课中编写并运行代码吗？

能。每节 Tailwind CSS Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Tailwind CSS Academy