Radix Vuereka-uiVue 3 Playground 搭建指南Vite TypeScript 环境、.vue类型支持与组件联调实战【免费下载链接】radix-vueAn open-source UI component library for building high-quality, accessible design systems and web apps for Vue. Previously Radix Vue项目地址: https://gitcode.com/GitHub_Trending/ra/radix-vue本指南以仓库playground/vue3目录的 README 为骨架讲解如何在 Radix Vue现 reka-ui仓库中搭建并运行一个基于 Vue 3 TypeScript Vite 的组件 Playground包括模板结构、VS Code Volar 的推荐 IDE 配置、.vue文件在 TypeScript 下的类型支持方案vue-tsc与 Take Over Mode以及 Playground 如何与仓库内核心包 reka-ui、文档示例组件进行工程级联调。读完本文你将能够独立配置并运行该 Playground理解vue-tsc类型检查、unplugin-vue-components 自动按需注册与 Tailwind 主题扩展在本仓库中的实际落地方式。一、仓库中的 Vue 3 Playground定位与目录结构该仓库采用 pnpm 管理根目录 package.json 声明了workspaces: [packages/*]与packageManager: pnpm10.13.1。playground/vue3是仓库内置的 Vue 3 演示工程独立于文档站docs与 Nuxt 版 Playgroundplayground/nuxt用于在浏览器中直接预览 reka-ui 各组件Accordion、Dialog、Select、Tooltip 等的实际渲染效果。从 playground/vue3/package.json 可以看到它的核心依赖关系{ name: playground-vue, type: module, version: 0.0.0, private: true, scripts: { dev: vite, build: vue-tsc vite build, preview: vite preview, lint: eslint ., lint:fix: eslint . --fix }, dependencies: { reka-ui: link:../../packages/core, vue: 3.5.7 }, devDependencies: { iconify/vue: ^4.3.0, radix-ui/colors: ^3.0.0, rollup/plugin-alias: ^5.1.1, vitejs/plugin-vue: ^5.1.4, autoprefixer: ^10.4.20, postcss: ^8.5.23, tailwindcss: ^3.4.17, unplugin-vue-components: ^29.0.0, vite: ^5.4.19, vue-tsc: ^2.1.6 } }几个关键点reka-ui: link:../../packages/core通过 pnpm 的link:协议将核心包packages/core/package.json版本 2.10.4软链到 Playground 的node_modules中。这意味着 Playground 直接消费仓库源码构建产物修改核心包代码后无需发布即可在本地演示是组件库开发的标准联调模式。核心包reka-ui声明peerDependencies: { vue: 3.4.0 }与本工程锁定的vue3.5.7兼容。build脚本为vue-tsc vite build这正是 README 中用vue-tsc替代tsc做类型检查的落地证据——先对.vue文件做类型检查通过后再交给 Vite 打包。Playground 自带独立的 pnpm-lock.yaml与根工作区互不影响可单独安装依赖。二、模板核心Vue 3script setup单文件组件README 开头说明该模板基于 Vue 3 TypeScript Vite并使用 Vue 3 的script setup语法编写 SFC单文件组件。所谓script setup是指在一个.vue文件的script标签上添加setup属性编译器会在每次使用组件实例时自动执行该脚本块顶层绑定直接暴露给模板从而以更少的样板代码实现组合式 API。Playground 的入口链路如下index.html 挂载div idapp并通过script typemodule src/src/main.ts引入入口模块src/main.ts 创建应用实例并挂载import { createApp } from vue import App from ./App.vue import ./style.css createApp(App).mount(#app)src/App.vue 是 Playground 的主界面采用script setup langts空脚本块模板中以Card容器包裹各组件演示template div classw-full flex flex-col items-center div classmax-w-6xl w-full grid grid-cols-3 gap-4 pt-40 pb-40 Card Accordion / /Card Card AlertDialog / /Card !-- ... Select、Slider、Switch、Tabs、Tooltip 等 -- /div /div /template style body { apply bg-black text-white; } /style注意模板中的Accordion、Dialog、Select等标签并没有显式 import——它们由unplugin-vue-components在构建期自动解析并注册详见第六节这正是script setup 自动导入生态下的典型写法。三、推荐 IDE 配置VS Code VolarREADME 给出的推荐编辑器组合是VS CodeVolar并禁用 VeturTypeScript Vue Plugin (Volar)。由于 Vue 3 的 SFC尤其script setup语法需要专门的编译器与语言服务才能获得完整的语法高亮、跳转定义、重构和诊断能力因此必须安装并启用 Volar它为 Vue 3 提供语言工具链必须禁用 VeturVetur 面向 Vue 2 时代设计与 Vue 3 的 SFC 编译模型不兼容两者同时启用会冲突额外安装TypeScript Vue Plugin (Volar)让 TypeScript 语言服务能够理解.vue文件中的类型信息详见第四节。这一组合在本仓库中已被实际采用Playground 的 tsconfig.node.json 专门用于让vite.config.ts获得独立的 TS 工程配置composite: true、moduleResolution: bundler而根目录 eslint.config.mjs 与lint脚本保证了编辑器内的代码风格检查与 CLI 一致。四、.vue导入的 TypeScript 类型支持README 解释了模板中的核心工程决策TypeScript 默认无法处理.vue导入的类型信息因此用vue-tsc替换tscCLI 做类型检查在编辑器里则需要 TypeScript Vue Plugin (Volar) 让 TypeScript 语言服务感知.vue类型。在 Playground 的 tsconfig.json 中可以看到配套的严格配置{ compilerOptions: { target: ES2020, lib: [ES2020, DOM, DOM.Iterable], module: ESNext, moduleResolution: bundler, resolveJsonModule: true, allowImportingTsExtensions: true, strict: true, noFallthroughCasesInSwitch: true, noUnusedLocals: true, noUnusedParameters: true, noEmit: true, isolatedModules: true, skipLibCheck: true }, references: [{ path: ./tsconfig.node.json }], include: [ env.d.ts, src/**/*.ts, src/**/*.d.ts, src/**/*.tsx, src/**/*.vue, components.d.ts ] }要点moduleResolution: bundler适配 Vite 的打包器解析模式strict: true打开全部严格检查项保证组件演示代码的类型安全noEmit: true表示该工程只做类型检查产物完全交给 Vite/esbuild 产出include同时覆盖src/**/*.vue与components.d.ts——后者由unplugin-vue-components自动生成见第六节把自动注册的全局组件声明进 TS 全局类型因此模板里无需 import 也能获得类型提示通过references引用tsconfig.node.json把vite.config.ts的类型检查隔离到独立的 Node 工程中。这就是构建时vue-tsc vite build、编辑器内靠 Volar 插件这套双重类型保障在本仓库中的完整实现。五、Take Over Mode接管 TypeScript 语言服务README 进一步给出性能优化选项如果独立的 TypeScript 插件TypeScript Vue Plugin响应不够快Volar 提供了性能更优的Take Over Mode让 Volar 直接接管 TypeScript 语言服务。启用步骤如下打开 VS Code 命令面板CtrlShiftP/CmdShiftP运行Extensions: Show Built-in Extensions列出内置扩展找到TypeScript and JavaScript Language Features内置扩展右键选择Disable (Workspace)仅在当前工作区禁用不影响全局运行Developer: Reload Window重载 VS Code 窗口使配置生效。启用后.vue文件的类型检查、跳转与重构全部由 Volar 统一处理避免两个语言服务重复解析导致的卡顿。对 playground/vue3 这样同时打开App.vue、components.d.ts与docs/components/demo下大量演示组件的场景Take Over Mode 能明显提升编辑体验。六、Playground 与 reka-ui 的工程级联调细节除 README 模板内容外仓库中还沉淀了几处值得参考的工程配置它们共同决定了 Playground 如何自动组装出满屏组件。6.1 自动组件注册unplugin-vue-componentsvite.config.ts 中配置了unplugin-vue-components的 Vite 插件import vue from vitejs/plugin-vue import Component from unplugin-vue-components/vite import { defineConfig } from vite export default defineConfig({ plugins: [ vue(), Component({ dirs: [../../docs/components/demo, ./src/components], dts: true, deep: true, directoryAsNamespace: true, exclude: [/\.md$/], }), ], })dirs同时扫描两层目录仓库文档站的演示组件目录../../docs/components/demo如 Accordion、Dialog 等与文档站共用一份演示源码与 Playground 本地组件./src/components即 Card.vuedts: true自动生成 components.d.ts把Accordion、AlertDialog、Select、Card等全部声明为 Vue 全局组件类型这也是模板中无需手动 import 即可使用它们的原因deep: true递归扫描子目录directoryAsNamespace: true支持按目录命名空间组织组件exclude: [/\.md$/]排除文档中的 Markdown 文件。生成的 components.d.ts 中可以看到每个组件声明都指向../../docs/components/demo/Name/index.vue例如Accordion: typeof import(./../../docs/components/demo/Accordion/index.vue)[default] Card: typeof import(./src/components/Card.vue)[default]6.2 Tailwind 主题与 reka-ui 动画变量Playground 使用 Tailwind CSS 构建演示样式tailwind.config.js 中的关键设计content显式包含../../docs/components/**/*.{vue,ts}确保文档演示组件的类名被正确扫描进产物theme.extend.colors通过...展开radix-ui/colors提供的色板blackA、mauve、violet、green、red、indigo、purple、grass、teal演示组件可直接使用bg-violet9这类语义色预置了大量与 reka-ui 组件交互配套的keyframes与animation例如overlayShow/contentShowDialog 遮罩与内容入场、slideDownAndFade等Popover/Tooltip 弹层、slideDown/slideUpAccordion 展开折叠动画高度直接读取var(--reka-accordion-content-height)这一 reka-ui 暴露的 CSS 变量通过tailwindcss/plugin的matchUtilities注册了perspective工具类供 3D 旋转类动画如scaleIn/scaleOut使用。样式入口 src/style.css 仅三行注入 Tailwind 的base/components/utilities三层postcss.config.js 挂载tailwindcss与autoprefixer两个插件。6.3 演示容器组件 Cardsrc/components/Card.vue 是 Playground 的通用容器为每个组件演示提供渐变背景卡片与插槽template div classrelative flex min-h-[300px] div classh-full from-teal9 to-green9 bg-gradient-to-br w-full rounded-xl flex relative items-center justify-center resize div classw-full max-w-[700px] flex flex-col items-center justify-center slot / /div /div /div /templateApp.vue中每个Card内放置一个组件演示形成 3 列网格的组件墙一眼即可预览 Accordion、NavigationMenu、ContextMenu、Dialog、Select、Slider、Tooltip 等近 30 个组件的默认交互效果。七、运行与验证在仓库根目录或playground/vue3目录下执行以下命令即可启动# 安装依赖Playground 有独立 pnpm-lock.yaml也可在根目录统一安装后配合 link 协议使用 pnpm install # 启动开发服务器 pnpm dev # 类型检查 生产构建等价于 README 推荐的 vue-tsc 流程 pnpm build # 预览生产构建产物 pnpm preview # ESLint 检查与自动修复 pnpm lint pnpm lint:fix验证要点pnpm dev启动后打开控制台输出的本地地址应看到深色背景的组件网格任意修改 packages/core/src 下的组件源码如 Accordion、Dialog开发服务器会热更新到 Playground验证link:../../packages/core的本地联调是否生效执行pnpm build时若vue-tsc报类型错误说明.vue文件或components.d.ts中的类型声明不一致需修复后再构建——这正是build: vue-tsc vite build双阶段保障的意义删除 components.d.ts 后重新pnpm dev插件会自动重新生成该文件模板中的组件仍能正常解析。八、从 Playground 到文档站演示组件复用值得强调的是Playground 的组件演示与文档站共用同一份源码unplugin-vue-components的dirs指向../../docs/components/demo而文档站docs/package.json同样渲染这些演示。因此在 docs/components/demo 下新增或修改某个组件的index.vue演示Playground 与文档站会同步生效Playground 作为轻量、无文档壳的裸环境非常适合快速验证 reka-ui 组件在 Vite Vue 3 TS 标准工程中的真实表现也是理解组件在无框架加持下的最小依赖面的最佳入口。结语playground/vue3既是仓库内置的组件演示场也是一份可直接复用的 Vue 3 TypeScript Vite 工程样板。它完整实践了 README 描述的技术选型script setupSFC、VS Code Volar 工具链、vue-tsc替代tsc的类型检查以及可选的 Take Over Mode 性能优化同时通过link:协议、unplugin-vue-components 与 Tailwind 主题扩展把仓库内的核心包、演示组件与样式体系无缝串联。相关文件均可直接在仓库中继续研读模板说明playground/vue3/README.md依赖与脚本playground/vue3/package.jsonVite 与自动组件注册playground/vue3/vite.config.tsTS 类型检查配置playground/vue3/tsconfig.json、playground/vue3/tsconfig.node.json入口与界面playground/vue3/src/main.ts、playground/vue3/src/App.vue自动生成的组件类型声明playground/vue3/components.d.tsTailwind 主题与动画playground/vue3/tailwind.config.js核心包被 link 引用的 reka-uipackages/core/package.json【免费下载链接】radix-vueAn open-source UI component library for building high-quality, accessible design systems and web apps for Vue. Previously Radix Vue项目地址: https://gitcode.com/GitHub_Trending/ra/radix-vue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考