shadcn-vue 纯 JavaScript 使用指南：通过 components.json 关闭 TypeScript 的完整配置

• UI组件
• 前端

本指南讲解如何在 shadcn-vue 项目中完全脱离 TypeScript、以纯 JavaScript 方式使用官方组件。shadcn-vue 的源码与全部组件默认以 TypeScript 编写，但官方 CLI 提供了完整的 JavaScript 支持路径：只需在components.json中将typescript置为false，CLI 便会自动把组件源码中的类型注解剔除、将.ts文件改写为.js。读完本文，你将掌握纯 JS 项目的初始化方式、components.json与jsconfig.json的完整配置方法，以及 CLI 底层去类型化（detype）的实现原理。

项目背景：TypeScript 是一等公民，但 JavaScript 受官方支持

shadcn-vue 是 shadcn-ui 的 Vue 移植版（见 README.md），其文档站点、组件仓库以及 CLI 工具链均以 TypeScript 编写。例如本仓库中 apps/v4/registry 下的新样式组件、reka-*系列 456 个组件文件全部是.vue+.ts组合。官方立场很明确：推荐你使用 TypeScript，理由包括类型安全、IDE 自动补全以及与组件源码形态一致。

但项目同样为 JavaScript 用户保留了官方通道——JavaScript 版本的组件通过 CLI（使用说明见 apps/v4/content/docs/06.cli.md） 提供。CLI 在安装组件时读取你的components.json，若检测到typescript: false，就会对拉取到的组件源码执行"去类型化"转换，产出可直接运行的.js组件。

第一步：在 components.json 中关闭 TypeScript

核心配置只有一个字段：typescript。在项目根目录的components.json中将其设置为false，即可显式选择 JavaScript 输出：

{ "style": "default", "tailwind": { "config": "tailwind.config.js", "css": "src/app/globals.css", "baseColor": "zinc", "cssVariables": true }, "typescript": false, "aliases": { "utils": "~/lib/utils", "components": "~/components" } }

关于该字段的几点权威说明，均可在仓库源码中找到直接证据：

• 默认值是true：CLI 的配置校验 schema 中写明了typescript: z.coerce.boolean().default(true)（见 packages/cli/src/registry/schema.ts），即不显式声明时按 TypeScript 项目处理，这符合官方"推荐 TypeScript"的立场。
• 初始化时会被询问：执行init命令时，CLI 会弹出交互式开关Would you like to use TypeScript (recommended)?，默认选中 yes（见 packages/cli/src/commands/init.ts），并最终把用户的选择写入rawConfigSchema.parse(...)的typescript字段（packages/cli/src/commands/init.ts）。
• schema 的其他字段保持通用：style、tailwind.config、tailwind.css、tailwind.baseColor、tailwind.cssVariables以及aliases均与 TypeScript 项目完全一致，切换语言不会影响这些配置的语义（完整字段定义见 packages/cli/src/registry/schema.ts）。

style字段在本仓库中取值如default、new-york、new-york-v4以及reka-nova、reka-vega等（见 packages/cli/src/commands/init.ts 的选择项），无论哪种视觉风格，JavaScript 模式都同样适用。

第二步：配置 jsconfig.json 完成导入别名

components.json里的aliases是模块导入别名，但要让编辑器（VSCode 等）与打包工具正确解析这些别名，纯 JavaScript 项目需要提供对应的路径映射配置。TypeScript 项目使用tsconfig.json的compilerOptions.paths，而 JS 项目对应的文件是jsconfig.json，语法同源：

{ "compilerOptions": { "paths": { "@/*": ["./*"] } } }

这段配置的作用是把@/开头的导入映射到项目根目录，例如import { cn } from "@/lib/utils"。它与components.json中aliases.utils: "~/lib/utils"、aliases.components: "~/components"配合使用。

CLI 在解析别名时对jsconfig.json有专门的逻辑支持，证据如下：

• 在 packages/cli/src/utils/get-config.ts 中，解析配置路径时会根据项目是否使用 TypeScript 选择读取tsconfig.json还是jsconfig.json：getTsconfig(tsConfigPath, isTypeScript ? undefined : 'jsconfig.json')。
• 在 packages/cli/src/utils/get-project-info.ts 中，isTypeScriptProject()通过扫描目录下是否存在tsconfig.*文件来判断语言；若无则被认定为 JS 项目。
• 同一个文件的 getFrameworkTsConfigPath() 在非 TypeScript 项目下会直接返回./jsconfig.json作为路径映射来源。

因此，纯 JS 项目的标准配置组合是：components.json中typescript: false+ 项目根目录的jsconfig.json提供paths映射，两者缺一不可。若使用 Nuxt 框架，其自动生成的jsconfig.json同样适用（Nuxt 会自行生成该文件），无需手动维护。

第三步：CLI 如何把 TypeScript 组件变成 JavaScript

理解底层转换机制有助于排查 JS 模式下的异常。CLI 对组件文件的"去类型化"发生在两个层面：

1. 文件扩展名改写：.ts → .js

在 packages/cli/src/utils/updaters/update-files.ts 中，当config.typescript为假时，CLI 会把待写入文件的扩展名从.ts替换为.js：

if (!config.typescript) { filePath = filePath.replace(/\.ts?$/, match => '.js') }

这意味着utils.ts会以utils.js落盘，组件目录下的辅助脚本同样如此，而.vue单文件组件不受影响（其内部<script lang="ts">的处理见下）。

2. 单文件组件内容转换：借助 @unovue/detypes 剔除类型

对.vue单文件组件，转换逻辑位于 packages/cli/src/utils/transformers/transform-sfc.ts：

export async function transformSFC(opts: TransformOpts) { if (opts.config?.typescript) return opts.raw return await transformByDetype(opts.raw, opts.filename).then(res => res as string) } export async function transformByDetype(content: string, filename: string) { return await transform(content, filename, { removeTsComments: true, prettierOptions: { proseWrap: 'never', }, }) }

要点解读：

• typescript: true时原样返回：组件源码不做任何改写，这正是"推荐 TypeScript"在实现层面的体现。
• typescript: false时调用@unovue/detypes：该工具会解析 SFC 中的<script lang="ts">，剥离类型注解、接口、泛型与类型导入，同时removeTsComments: true会移除仅用于类型层面的注释；proseWrap: 'never'则保证转换过程中不破坏原有代码换行结构。
• 转换是纯文本级的：不会改变组件的 props 默认值、事件逻辑等运行时行为，因此 JS 模式下组件的 API 与 TS 模式完全一致。

整体调用链为：CLI 安装组件 → 读取 registry 文件 →transformSFC（依据components.json.typescript决定是否 detype）→ 扩展名改写 → 写入项目。相关转换器统一注册在 packages/cli/src/utils/transformers/index.ts，同一管线中的transform-import.ts、transform-css-vars.ts等转换器在 JS 模式下照常生效。

常见问题与注意事项

• components.json 不写 typescript 会怎样？会按true处理（schema 默认值），CLI 不会产出.js文件。若要使用 JS，必须显式写"typescript": false。
• jsconfig.json 可以省略吗？在init初始化时 CLI 会引导填写别名；若省略jsconfig.json的paths，编辑器无法解析@/或~/别名，导入会报错，建议始终配置。
• Nuxt 用户：Nuxt 3/4 会自动生成.nuxt/tsconfig.json或jsconfig.json，CLI 会优先读取框架生成的配置来解析别名（见 getFrameworkTsConfigPath()），无需手动维护路径映射。
• 别名前缀并不强制为@：components.json中aliases的键值可以自定义（如~/），只需与jsconfig.json的paths一一对应即可。CLI 在 resolveConfigPaths() 中会通过resolveImport()依据路径映射把别名解析为绝对路径。
• 运行时表现：由于转换只剥离类型、不改业务逻辑，TS 与 JS 模式产出的组件在浏览器中的行为一致；差异仅在于 JS 模式失去了静态类型检查与编辑器类型提示。

总结

使用纯 JavaScript 接入 shadcn-vue 只需要三件事：在components.json中显式声明"typescript": false、提供jsconfig.json的paths路径映射、然后照常通过 CLI 安装组件。CLI 会在安装时自动完成.ts扩展名改写与 SFC 内部类型剥离，全程无需手动改写组件代码。虽然官方推荐 TypeScript，但 JavaScript 通道是官方一等支持的能力，其实现细节（schema 默认值、jsconfig 读取、detype 转换器）都封装在packages/cli/src中，可随时查阅源码验证行为。

• UI组件
• 前端