如何在 Turborepo 集成 Tailwind4+Shadcn，同时兼容 Tailwind3 的组件

本教程将指导你如何在 Turborepo 项目中集成最新的 Tailwind 4 和 Shadcn/ui 组件库，同时保持与 Tailwind 3 组件的兼容性。

当前教程的示例项目

GitHub - nexmoe/turbo-tailwind4-shadcn: This is an enhanced project template based on the official Turborepo scaffold, integrated with the latest Tailwind 4 and Shadcn/ui component library.

项目基础配置

创建 Turborepo 项目

首先，使用官方命令创建一个新的 Turborepo 项目：

npx create-turbo@latest

按照提示完成项目创建。

集成 Tailwind 4

安装 Tailwind 4

在共享 UI 包中安装 Tailwind 4 及其依赖：

cd packages/ui
pnpm add tailwindcss@^4.0.9 @tailwindcss/cli@^4.0.9 @tailwindcss/postcss@^4.0.7 postcss@^8.5.3

创建 PostCSS 配置

在 packages/ui 目录中创建 postcss.config.mjs 文件：

/** @type {import('postcss-load-config').Config} */
const config = {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};


export default config;

设置全局 CSS

在 packages/ui/src/styles 目录中创建 global.css 文件：

@import "tailwindcss";

集成 Shadcn/ui

安装必要依赖

安装 Shadcn/ui 所需的依赖：

cd packages/ui
pnpm add class-variance-authority clsx tailwind-merge lucide-react tailwindcss-animate framer-motion

配置 Shadcn/ui

在 packages/ui 目录中创建 components.json 文件：

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "../../packages/ui/src/styles/global.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "iconLibrary": "lucide",
  "aliases": {
    "components": "@repo/ui/components",
    "utils": "@repo/ui/lib/utils",
    "hooks": "@repo/ui/hooks",
    "lib": "@repo/ui/lib",
    "ui": "@repo/ui/components"
  }
}

设置全局 CSS

在 packages/ui/src/styles 目录修改 global.css 文件，添加 shadcn 的样式代码：

@import "tailwindcss";
@plugin "tailwindcss-animate";



@custom-variant dark (&:is(.dark *));


@config "../../tailwind.config.ts";


@theme {
  --font-sans: var(--font-geist-sans);
  --font-mono: var(--font-geist-mono);
}


:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.145 0 0);
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --secondary: oklch(0.97 0 0);
  --secondary-foreground: oklch(0.205 0 0);
  --muted: oklch(0.97 0 0);
  --muted-foreground: oklch(0.556 0 0);
  --accent: oklch(0.97 0 0);
  --accent-foreground: oklch(0.205 0 0);
  --destructive: oklch(0.577 0.245 27.325);
  --destructive-foreground: oklch(0.577 0.245 27.325);
  --border: oklch(0.922 0 0);
  --input: oklch(0.922 0 0);
  --ring: oklch(0.87 0 0);
  --chart-1: oklch(0.646 0.222 41.116);
  --chart-2: oklch(0.6 0.118 184.704);
  --chart-3: oklch(0.398 0.07 227.392);
  --chart-4: oklch(0.828 0.189 84.429);
  --chart-5: oklch(0.769 0.188 70.08);
  --radius: 0.625rem;
  --sidebar: oklch(0.985 0 0);
  --sidebar-foreground: oklch(0.145 0 0);
  --sidebar-primary: oklch(0.205 0 0);
  --sidebar-primary-foreground: oklch(0.985 0 0);
  --sidebar-accent: oklch(0.97 0 0);
  --sidebar-accent-foreground: oklch(0.205 0 0);
  --sidebar-border: oklch(0.922 0 0);
  --sidebar-ring: oklch(0.87 0 0);
}


.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --card: oklch(0.145 0 0);
  --card-foreground: oklch(0.985 0 0);
  --popover: oklch(0.145 0 0);
  --popover-foreground: oklch(0.985 0 0);
  --primary: oklch(0.985 0 0);
  --primary-foreground: oklch(0.205 0 0);
  --secondary: oklch(0.269 0 0);
  --secondary-foreground: oklch(0.985 0 0);
  --muted: oklch(0.269 0 0);
  --muted-foreground: oklch(0.708 0 0);
  --accent: oklch(0.269 0 0);
  --accent-foreground: oklch(0.985 0 0);
  --destructive: oklch(0.396 0.141 25.723);
  --destructive-foreground: oklch(0.637 0.237 25.331);
  --border: oklch(0.269 0 0);
  --input: oklch(0.269 0 0);
  --ring: oklch(0.439 0 0);
  --chart-1: oklch(0.488 0.243 264.376);
  --chart-2: oklch(0.696 0.17 162.48);
  --chart-3: oklch(0.769 0.188 70.08);
  --chart-4: oklch(0.627 0.265 303.9);
  --chart-5: oklch(0.645 0.246 16.439);
  --sidebar: oklch(0.205 0 0);
  --sidebar-foreground: oklch(0.985 0 0);
  --sidebar-primary: oklch(0.488 0.243 264.376);
  --sidebar-primary-foreground: oklch(0.985 0 0);
  --sidebar-accent: oklch(0.269 0 0);
  --sidebar-accent-foreground: oklch(0.985 0 0);
  --sidebar-border: oklch(0.269 0 0);
  --sidebar-ring: oklch(0.439 0 0);
}


@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-card: var(--card);
  --color-card-foreground: var(--card-foreground);
  --color-popover: var(--popover);
  --color-popover-foreground: var(--popover-foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-secondary: var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-accent: var(--accent);
  --color-accent-foreground: var(--accent-foreground);
  --color-destructive: var(--destructive);
  --color-destructive-foreground: var(--destructive-foreground);
  --color-border: var(--border);
  --color-input: var(--input);
  --color-ring: var(--ring);
  --color-chart-1: var(--chart-1);
  --color-chart-2: var(--chart-2);
  --color-chart-3: var(--chart-3);
  --color-chart-4: var(--chart-4);
  --color-chart-5: var(--chart-5);
  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 4px);
  --color-sidebar: var(--sidebar);
  --color-sidebar-foreground: var(--sidebar-foreground);
  --color-sidebar-primary: var(--sidebar-primary);
  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
  --color-sidebar-accent: var(--sidebar-accent);
  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
  --color-sidebar-border: var(--sidebar-border);
  --color-sidebar-ring: var(--sidebar-ring);
}

创建工具函数

在 packages/ui/src/lib 目录中创建 utils.ts 文件：

import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"


export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

配置 tsconfig.json

{
  "extends": "@repo/typescript-config/react-library.json",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@repo/ui/*": ["./src/*"]
    }
  },
  "include": ["src"],
  "exclude": ["node_modules"]
}

创建 UI 组件

在 packages/ui/ 目录下直接执行 pnpm dlx shadcn@canary add button

配置 package.json 导出

确保在 packages/ui/package.json 中正确配置导出和 dev 脚本：

{
  "name": "@repo/ui",
  "version": "0.0.0",
  "private": true,
  "exports": {
    "./global.css": "./dist/global.css",
    "./postcss.config": "./postcss.config.mjs",
    "./tailwind.config": "./tailwind.config.ts",
    "./lib/*": "./src/lib/*.ts",
    "./components/*": "./src/components/*.tsx",
    "./hooks/*": "./src/hooks/*.ts"
  },
  "scripts": {
    "dev": "tailwindcss -i src/styles/global.css -o ./dist/global.css --watch"
  }
}

与 Tailwind 3 兼容性

Tailwind 4 设计时考虑了与 Tailwind 3 的兼容性，所以大多数 Tailwind 3 的类名和功能在 Tailwind 4 中仍然可用。以下是确保兼容性的关键点：

兼容 Tailwind3 组件

支持旧版 tailwind.config.ts 文件

在 packages/ui/src/styles 目录中修改 global.css 文件：

@import "tailwindcss";


@config "../../tailwind.config.ts";

核心类名兼容性

Tailwind 4 保持了与 Tailwind 3 相同的核心类名结构，如 bg-blue-500、text-lg、flex 等，因此现有组件无需修改即可使用。

新语法与旧语法共存

Tailwind 4 引入了新的 @ 指令语法，但保留了对传统 @apply 语法的支持，允许你逐步迁移。

tailwind-merge 工具

使用 tailwind-merge 与 clsx 结合的 cn 工具函数可以智能地处理类名合并，确保 Tailwind 3 和 Tailwind 4 的类名可以和谐共存：

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

测试与迁移

1. 首先在非关键组件上测试 Tailwind 4
2. 利用 CSS 变量系统逐步迁移颜色方案
3. 确保所有响应式断点表现一致

在应用中使用

在应用的 CSS 中导入 UI 样式

在应用的主 CSS 文件中导入 UI 样式：

import "@repo/ui/global.css";


/* 应用特定的样式 */

导入和使用组件

在应用中导入和使用组件：

import { Button } from "@repo/ui/components/button";


export default function MyComponent() {
  return (
    <div>
      <Button>点击我</Button>
    </div>
  );
}

结语

通过上述步骤，你已经成功在 Turborepo 中集成了 Tailwind 4 和 Shadcn/ui，同时保持了与 Tailwind 3 组件的兼容性。这种设置让你可以逐步迁移到新版本，同时保持设计系统的一致性和代码复用。

记住，Tailwind 4 相比 Tailwind 3 带来了更好的性能、更强大的功能和更好的开发体验，但完全兼容旧版本，使得过渡更加平滑。