项目检测与管理

相关源文件

• apps/www/content/docs/installation/tanstack-router.mdx
• apps/www/content/docs/installation/tanstack.mdx
• packages/shadcn/src/utils/frameworks.ts
• packages/shadcn/src/utils/get-project-info.ts
• packages/shadcn/src/utils/transformers/transform-import.ts
• packages/shadcn/src/utils/updaters/update-files.ts
• packages/shadcn/test/utils/updaters/update-files.test.ts

本文档介绍了 shadcn CLI 如何自动检测和管理不同项目类型及配置。该系统会识别所使用的框架、项目结构和配置细节，以便正确地安装组件和管理文件。

有关组件安装和文件转换的信息，请参阅 组件管理。有关配置模式和设置的详细信息，请参阅 配置。

框架检测系统

CLI 包含一个全面的框架检测系统，可自动识别项目类型并相应地进行配置。

来源： packages/shadcn/src/utils/get-project-info.ts42-151 packages/shadcn/src/utils/frameworks.ts1-86

项目检测流程

getProjectInfo 函数并行检测多个项目特征，以构建完整的 ProjectInfo 对象。

检测流程

来源： packages/shadcn/src/utils/get-project-info.ts42-68

框架分类逻辑

系统遵循特定的框架检测优先级顺序

优先级	框架	检测方法	条件
1	Next.js App Router	配置文件 + app 目录	next.config.* + app/ 目录
2	Next.js Pages Router	仅配置文件	next.config.*，但不包含 app/ 目录
3	Astro	配置文件	astro.config.*
4	Gatsby	配置文件	gatsby-config.*
5	Laravel	配置文件	composer.json
6	Remix	包依赖项	依赖项中包含 @remix-run/*
7	TanStack Start	配置 + 依赖项	app.config.* + @tanstack/start
8	React Router	配置文件	react-router.config.*
9	Vite	配置文件	vite.config.*
10	手动	回退	以上皆不匹配

来源： packages/shadcn/src/utils/get-project-info.ts85-150

项目配置解析

getProjectConfig 函数结合项目检测和现有配置，创建一个完整的配置对象。

配置解析流程

来源： packages/shadcn/src/utils/get-project-info.ts292-339

默认配置生成

当未找到现有配置时，系统会根据检测到的项目特征生成默认配置

来源： packages/shadcn/src/utils/get-project-info.ts316-336

Tailwind 检测与配置

版本检测

该系统支持 Tailwind CSS v3 和 v4，具有不同的检测策略

来源： packages/shadcn/src/utils/get-project-info.ts153-184

CSS 文件检测

该系统通过扫描特定的导入模式来定位 Tailwind CSS 文件

• Tailwind v4： @import "tailwindcss"
• Tailwind v3： @tailwind base

来源： packages/shadcn/src/utils/get-project-info.ts186-214

TypeScript 配置分析

别名前缀检测

getTsConfigAliasPrefix 函数从 TypeScript 配置中提取路径别名

检测到的常见别名模式

• @/* → @
• ~/* → ~
• @shadcn/* → @shadcn
• ~cn/* → ~cn

来源： packages/shadcn/src/utils/get-project-info.ts230-254

与文件管理集成

项目检测直接通过更新系统影响文件放置和转换。

文件路径解析

resolveFilePath 函数使用 ProjectInfo 来确定正确的文件放置位置

来源： packages/shadcn/src/utils/updaters/update-files.ts237-392

框架特定转换

不同的框架需要不同的文件放置策略

框架	页面转换	示例
next-app	无变化	app/login/page.tsx
next-pages	app/ → pages/，移除 /page	app/login/page.tsx → pages/login.tsx
react-router	app/ → app/routes/，移除 /page	app/login/page.tsx → app/routes/login.tsx
laravel	app/ → resources/js/pages/，移除 /page	app/login/page.tsx → resources/js/pages/login.tsx

来源： packages/shadcn/src/utils/updaters/update-files.ts357-391