shadcn-ui 项目全面拥抱 Tailwind v4 和 React 19 的技术解析

shadcn-ui 项目近日发布了重大更新，全面支持 Tailwind CSS v4 和 React 19。这次更新为开发者带来了诸多新特性和改进，标志着该项目正式进入下一代前端技术栈。

核心更新内容

shadcn-ui 现在提供了对 Tailwind v4 和 React 19 的完整支持。项目团队推出了 canary 版本的 CLI 工具，开发者可以通过以下命令体验最新功能：

npx shadcn@canary init

主要技术革新

1. Tailwind v4 深度集成

   • 全面支持新的 @theme 指令和 @theme inline 选项
   • 优化了 CSS 变量处理方式，简化了主题配置
   • 引入了 size-* 工具类替代传统的 w-* h-* 组合

2. React 19 适配

   • 移除了 forwardRefs 并调整了类型系统
   • 每个基础组件都添加了 data-slot 属性便于样式定制
   • 组件样式进行了全面清理和优化

3. 组件库改进

   • 弃用了 toast 组件，推荐使用 sonner 替代
   • 按钮组件现在使用默认光标样式
   • 弃用了 default 样式，新项目将默认使用 new-york 风格

项目初始化指南

Next.js 项目设置

1. 创建基础项目结构：

pnpm create next-app@canary --tailwind --eslint --typescript --app --no-src-dir

2. 初始化 shadcn-ui 配置：

pnpm dlx shadcn@canary init

3. 添加组件：

pnpm dlx shadcn@canary add button

Vite 项目配置

1. 创建 React 19 项目：

pnpm create vite --template=react-ts

2. 配置路径别名和类型支持
3. 修改 vite.config.ts 添加解析配置
4. 初始化 shadcn-ui 并添加组件

现有项目升级策略

Tailwind v4 迁移要点

1. 遵循官方升级指南进行基础迁移
2. 使用 @tailwindcss/upgrade@next 代码修改工具处理废弃类
3. 调整 CSS 变量结构：
   • 将 :root 和 .dark 移出 @layer base
   • 使用 hsl() 包装颜色值
   • 应用 @theme inline 指令简化变量引用

React 19 适配方案

1. 移除 forwardRef 用法
2. 使用 React.ComponentProps 类型定义组件属性
3. 为每个基础组件添加 data-slot 属性
4. 可考虑转换为命名函数并移除 displayName

样式系统优化

shadcn-ui 对样式系统进行了重大调整：

1. 图表颜色配置简化，直接使用 CSS 变量
2. 全面拥抱 size-* 工具类，提升代码简洁性
3. 主题系统重构，默认使用 new-york 风格
4. 动画效果正在持续改进中

开发者注意事项

1. 目前 canary 版本可能存在一些已知问题，如主题切换和组件样式重复
2. 某些组件如抽屉(Drawer)的图标颜色可能需要手动调整
3. 使用 Remix + Vite 组合时需要特别注意 Tailwind 配置
4. 建议开发者在升级前充分测试关键功能

这次更新标志着 shadcn-ui 项目正式进入现代化前端技术栈，为开发者提供了更强大、更灵活的工具集。项目团队将持续优化这些新特性，并欢迎社区反馈以进一步完善功能。