技能包

Nuxt UI:在 v4 里接入组件库,并让 Agent 按 AGENTS.md 工作

适合要在 Nuxt 项目接入这套 Vue UI、或让编码 Agent 按仓库规范改组件的人,但当前页面是 v4 分支,不要和 v3/v2 混用。

官方来源 · Nuxt UI

安装

pnpm add @nuxt/ui tailwindcss

适合谁

如果你在做 Nuxt 界面,希望用现成的 Vue UI,而不是从零拼无障碍组件,这个仓库更合适。它把 Reka UI、Tailwind CSS 和 Tailwind Variants 合在一起,用来做复杂、可访问、高性能的界面。相关上游分别是

https://reka-ui.com/

https://tailwindcss.com/

https://www.tailwind-variants.org/

你需要一个能改 nuxt.config 的 Nuxt 项目,并接受用 pnpm 安装依赖。只想让编码 Agent 帮忙改组件、主题或测试的人,应先读仓库提供的 AGENTS.md。它没有把某一家 Agent 产品写成唯一支持对象,只说会被所有 AI coding agents 自动拾取。

3 分钟完成第一次尝试

官方安装命令按页面写成这一条:

pnpm add @nuxt/ui tailwindcss

这会改项目依赖,不是只读查看。先确认当前目录就是你的 Nuxt 应用、本机有 pnpm,再执行。装完后把模块写进配置,摘录给出的是:

export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css']
})

它要求存在 ~/assets/css/main.css 这条 CSS 入口,但没有写出该文件内容。不要自行补 @import 或组件用法。成功信号是:依赖已装上,modules 里能看到 @nuxt/ui,应用能按你现有方式启动且没有因为缺这个模块而报错。若 Agent 开始添加未在摘录中出现的按钮示例或改主题 token,先停下来。

更低风险的核对:打开

https://github.com/nuxt/ui/blob/v4/AGENTS.md

让 Agent 只解释组件结构或主题约定,先不改文件。

使用案例

案例一:在 Nuxt 应用接入 v4。按上面的 pnpm 命令安装 @nuxt/ui 和 tailwindcss,再注册 @nuxt/ui 模块并指向 ~/assets/css/main.css。页面没有写 npm/yarn 等价命令,也没有写 Vue 单文件里第一个组件该怎么引。因此你能确认的只有:依赖和模块注册这两步。CSS 文件里要写什么、页面上要放哪个组件,都超出这份摘录,必须另查你本地已有文档或源码,不能假装这里已经给过。

案例二:让编码 Agent 按仓库规范做事。AGENTS.md 为 AI 助手提供贡献指南,覆盖组件结构、主题模式、测试约定和文档指引,并且会被自动拾取。任务应是只读对照,例如「按 AGENTS.md 检查这个组件的结构/主题/测试是否偏离」。它没有写具体测试命令,也没有写文档站点的发布方式。所以第一次不要让 Agent 批量重写文档或补测试文件;先让它指出依据段落和将改路径。

使用边界

你现在看的是 v4 分支。Nuxt UI v3 在

https://github.com/nuxt/ui/tree/v3

v2 在

https://github.com/nuxt/ui/tree/v2

不要把旧分支的模块名、目录或主题写法套到 v4。页面没有写 v4 与 v3 的迁移表。

安装路径就是 pnpm add @nuxt/ui tailwindcss。不要并列另一套包管理器命令。Reka UI 和 Tailwind Variants 被写成能力来源,不是第二条安装器。

第一次停在装依赖、注册模块,或只读 AGENTS.md。任何改组件源码、补测试、改主题或重写 CSS 入口的动作,都要先让 Agent 复述将改的文件,你确认后再继续。