在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

shadcn-ui/ui

菜单

框架集成

相关源文件

本文档提供了将 shadcn/ui 组件与各种 React 框架和构建工具集成的全面指南。它涵盖了框架特定的设置过程、配置要求以及支持平台之间 CLI 的行为差异。

有关不使用 CLI 手动安装组件的信息，请参阅 手动安装。有关 CLI 配置系统的详细信息，请参阅 配置。

支持的框架

shadcn/ui CLI 支持对多种基于 React 的框架和构建工具进行自动框架检测和配置。每个框架对 TypeScript 配置、路径别名和构建工具设置都有特定要求。

框架检测矩阵

框架CLI 支持自动检测Tailwind v4React 19
Next.js完整版✅✅✅
Vite完整版✅✅✅
Remix完整版✅✅✅
Astro完整版✅✅✅
Laravel完整版✅✅✅
React Router完整版✅✅✅
TanStack Start完整版✅✅✅
TanStack Router完整版✅✅✅
Gatsby部分✅⚠️⚠️

来源：apps/www/config/docs.ts118-165

CLI 框架检测过程

在 init 命令期间，CLI 会自动检测您的框架并应用适当的配置设置。

来源：apps/www/content/docs/installation/next.mdx15-19 apps/www/content/docs/installation/vite.mdx105-111

组件安装流程

每个框架在组件安装和文件结构方面都有不同的要求。

来源：apps/www/content/docs/installation/remix.mdx53-56 apps/www/content/docs/installation/laravel.mdx28-32

Next.js 集成

Next.js 提供了最简单的集成路径，具有自动框架检测和最低的配置要求。

设置过程

  1. 项目创建或检测：CLI 可以创建新的 Next.js 项目或检测现有项目
  2. 自动配置：框架特定的设置会自动应用
  3. 组件安装：使用标准的 @/ 导入别名

CLI 自动配置

  • TypeScript 路径别名（在 tsconfig.json 中）
  • Tailwind CSS 集成
  • 组件目录结构
  • 导入别名解析

来源：apps/www/content/docs/installation/next.mdx11-46

Vite 集成

Vite 需要额外的 TypeScript 路径解析和 Tailwind CSS 集成配置。

必需的配置步骤

  1. Tailwind CSS 安装：手动安装 tailwindcss 和 @tailwindcss/vite
  2. TypeScript 配置：更新 tsconfig.json 和 tsconfig.app.json
  3. Vite 配置：在 vite.config.ts 中进行路径别名解析

关键配置文件

来源：apps/www/content/docs/installation/vite.mdx78-101 apps/www/content/docs/installation/vite.mdx86-100

Remix 集成

Remix 需要特定的 PostCSS 配置，并使用不同的导入别名约定。

框架特定要求

  1. PostCSS 配置：独立的 postcss.config.js 文件
  2. Remix 配置更新：在 remix.config.js 中启用 Tailwind 和 PostCSS
  3. 导入别名：使用 ~/ 前缀而不是 @/

目录结构建议

  • UI 组件：app/components/ui/
  • 自定义组件：app/components/
  • 实用工具：app/lib/
  • 全局 CSS：app/tailwind.css

来源：apps/www/content/docs/installation/remix.mdx53-57 apps/www/content/docs/installation/remix.mdx64-85

Astro 集成

Astro 集成需要 React 模板设置和 TypeScript 路径配置。

设置要求

  1. 项目模板：使用 --template with-tailwindcss --add react 标志
  2. TypeScript 配置：手动进行 tsconfig.json 路径设置
  3. 组件用法：组件可以在具有正确导入的 .astro 文件中使用

来源：apps/www/content/docs/installation/astro.mdx15-19 apps/www/content/docs/installation/astro.mdx22-38

Laravel 集成

Laravel 集成利用 Inertia.js 和 React，并遵循 Laravel 的目录约定。

Laravel 特定模式

  1. 项目设置：使用 laravel new --react 进行 Inertia.js 设置
  2. 组件位置：组件安装到 resources/js/components/ui/
  3. 导入别名：使用指向 resources/js/ 的 @/ 别名

示例组件用法

来源：apps/www/content/docs/installation/laravel.mdx15-19 apps/www/content/docs/installation/laravel.mdx28-44

Gatsby 集成

Gatsby 支持包括用于路径解析的其他 webpack 配置。

其他要求

  1. Webpack 配置：用于路径别名的自定义 gatsby-node.ts 文件
  2. TypeScript 设置：手动进行 tsconfig.json 配置
  3. 全局 CSS 路径：使用 ./src/styles/globals.css 约定

Webpack 别名配置

来源：apps/www/content/docs/installation/gatsby.mdx61-78

React Router 集成

React Router 提供了与新的 React Router 框架的简化集成。

简单的设置过程

  1. 项目创建：npx create-react-router@latest
  2. CLI 集成：标准的 shadcn init 过程
  3. 路由集成：组件可直接在路由文件中使用

来源：apps/www/content/docs/installation/react-router.mdx8-12 apps/www/content/docs/installation/react-router.mdx32-51

配置文件模式

根据其约定，不同框架会生成不同的 components.json 配置。

框架特定的配置差异

框架UI 路径Utils 路径别名前缀CSS 路径
Next.js@/components/ui@/lib/utils@/app/globals.css
Vite@/components/ui@/lib/utils@/src/index.css
Remix~/components/ui~/lib/utils~/app/tailwind.css
Laravel@/components/ui@/lib/utils@/resources/css/app.css
Astro@/components/ui@/lib/utils@/src/styles/globals.css

来源： apps/www/content/docs/installation/remix.mdx38-43 apps/www/content/docs/installation/gatsby.mdx88-102

Tailwind 版本兼容性

所有框架都支持 Tailwind v3 和 v4，但需要不同的 CLI 版本。

版本要求

  • Tailwind v4：使用 shadcn@latest（新项目默认）
  • Tailwind v3：使用 shadcn@2.3.0 以支持旧版本

特定于框架的 Tailwind v4 功能包括

  • @import "tailwindcss" 语法
  • @tailwindcss/vite Vite 插件
  • 增强的 CSS 变量支持

来源： apps/www/content/docs/installation/next.mdx6-9 apps/www/content/docs/installation/vite.mdx6-9 apps/www/content/docs/tailwind-v4.mdx19-32