Nuxt UI 贡献指南：组件开发、主题定制、测试与文档全流程

contributing by nuxt/ui

334 周安装量

6,400 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/nuxt/ui --skill contributing

UI组件库 JavaScript 框架开源项目

🇨🇳中文介绍

Nuxt UI 开发

为 Nuxt UI 组件库贡献的指南。

项目结构

src/
├── runtime/
│   ├── components/     # Vue 组件 (PascalCase.vue)
│   ├── composables/    # 组合式函数 (use*.ts)
│   ├── types/          # TypeScript 类型定义
│   └── utils/          # 工具函数
├── theme/              # Tailwind Variants 主题 (kebab-case.ts)
└── module.ts
test/
├── components/         # 组件测试 (*.spec.ts)
│   └── __snapshots__/  # 自动生成的快照
└── component-render.ts
docs/
└── content/docs/2.components/  # 文档 (*.md)
playgrounds/
└── nuxt/app/pages/components/  # 演练场页面

脚手架 CLI

首先链接 CLI（一次性设置）：

npm link

然后使用它来创建新组件：

nuxt-ui make component <name> [options]

选项：

--primitive - 基础组件（使用 Reka UI Primitive）
--prose - 排版/文本组件

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

Next.js 16+ 缓存组件指南：实现部分预渲染（PPR）与混合内容缓存

13,200 周安装

Node.js后端模式指南：构建可扩展REST API、微服务与实时应用

12,900 周安装

Vue 3 调试指南：解决响应式、计算属性与监听器常见错误

9,900 周安装

Vue.js测试最佳实践：Vue 3组件、组合式函数、Pinia与异步测试完整指南

3,700 周安装

--content - 内容组件

--template - 仅生成特定模板 (playground, docs, test, theme, component)

文件	主题
references/component-structure.md	Vue 组件文件模式、props/slots/emits 接口、script setup
references/theme-structure.md	Tailwind Variants 主题文件、插槽、变体、复合变体
references/testing.md	Vitest 模式、快照测试、无障碍测试
references/documentation.md	组件文档结构、MDC 语法、示例

根据你的任务加载参考文件：

references/component-structure.md - 如果创建/修改 Vue 组件
references/theme-structure.md - 如果处理组件主题
references/testing.md - 如果编写或审查测试
references/documentation.md - 如果编写组件文档

请勿一次性加载所有文件。 仅加载相关文件。

创建新组件时，复制此清单并跟踪进度：

组件: [name]
进度:
- [ ] 1. 使用 CLI 搭建脚手架: nuxt-ui make component <name>
- [ ] 2. 在 src/runtime/components/ 中实现组件
- [ ] 3. 在 src/theme/ 中创建主题
- [ ] 4. 从 src/runtime/types/index.ts 导出类型
- [ ] 5. 在 test/components/ 中编写测试
- [ ] 6. 在 docs/content/docs/2.components/ 中创建文档
- [ ] 7. 添加演练场页面
- [ ] 8. 运行 pnpm run lint
- [ ] 9. 运行 pnpm run typecheck
- [ ] 10. 运行 pnpm run test

审查组件 PR 时，请验证：

PR 审查:
- [ ] 组件遵循现有模式（参见 references/）
- [ ] 主题使用语义化颜色，而非 Tailwind 调色板
- [ ] 测试覆盖了 props、slots 和无障碍性
- [ ] 文档包含用法、示例和 API 部分
- [ ] 符合约定式提交消息格式
- [ ] 所有检查通过（lint, typecheck, test）

约定	描述
类型导入	始终分开：`import type { X }` 单独一行
Props 默认值	运行时使用 `withDefaults()`，文档使用 JSDoc `@defaultValue`
模板插槽	在所有元素上添加 `data-slot="name"` 属性
计算 UI	始终使用 `computed(() => tv(...))` 进行响应式主题化
主题支持	使用 `useComponentUI(name, props)` 将主题上下文与组件的 `ui` prop 合并
语义化颜色	使用 `text-default`、`bg-elevated` 等 - 切勿使用 Tailwind 调色板
Reka UI props	使用 `reactivePick` + `useForwardPropsEmits` 来转发 props
表单组件	使用 `useFormField` 和 `useFieldGroup` 组合式函数

pnpm run dev:prepare  # 生成类型存根（安装后运行）
pnpm run dev          # Nuxt 演练场
pnpm run dev:vue      # Vue 演练场
pnpm run docs         # 文档站点
pnpm run lint         # 检查代码规范
pnpm run lint:fix     # 修复代码规范
pnpm run typecheck    # 类型检查
pnpm run test         # 运行测试

🇺🇸English

Nuxt UI Development

Guidelines for contributing to the Nuxt UI component library.

Project Structure

src/
├── runtime/
│   ├── components/     # Vue components (PascalCase.vue)
│   ├── composables/    # Composables (use*.ts)
│   ├── types/          # TypeScript types
│   └── utils/          # Utility functions
├── theme/              # Tailwind Variants themes (kebab-case.ts)
└── module.ts
test/
├── components/         # Component tests (*.spec.ts)
│   └── __snapshots__/  # Auto-generated snapshots
└── component-render.ts
docs/
└── content/docs/2.components/  # Documentation (*.md)
playgrounds/
└── nuxt/app/pages/components/  # Playground pages

CLI for Scaffolding

Link the CLI first (one-time setup):

npm link

Then use it to create new components:

nuxt-ui make component <name> [options]

Options:

--primitive - Primitive component (uses Reka UI Primitive)
--prose - Prose/typography component
--content - Content component
--template - Generate specific template only (playground, docs, test, theme, component)

Available Guidance

File	Topics
references/component-structure.md	Vue component file patterns, props/slots/emits interfaces, script setup
references/theme-structure.md	Tailwind Variants theme files, slots, variants, compoundVariants
references/testing.md	Vitest patterns, snapshot testing, accessibility testing
references/documentation.md	Component docs structure, MDC syntax, examples

Loading Files

Load reference files based on your task:

references/component-structure.md - if creating/modifying Vue components
references/theme-structure.md - if working on component theming
references/testing.md - if writing or reviewing tests
references/documentation.md - if writing component docs

DO NOT load all files at once. Load only what's relevant.

Component Creation Workflow

Copy this checklist and track progress when creating a new component:

Component: [name]
Progress:
- [ ] 1. Scaffold with CLI: nuxt-ui make component <name>
- [ ] 2. Implement component in src/runtime/components/
- [ ] 3. Create theme in src/theme/
- [ ] 4. Export types from src/runtime/types/index.ts
- [ ] 5. Write tests in test/components/
- [ ] 6. Create docs in docs/content/docs/2.components/
- [ ] 7. Add playground page
- [ ] 8. Run pnpm run lint
- [ ] 9. Run pnpm run typecheck
- [ ] 10. Run pnpm run test

PR Review Checklist

When reviewing component PRs, verify:

PR Review:
- [ ] Component follows existing patterns (see references/)
- [ ] Theme uses semantic colors, not Tailwind palette
- [ ] Tests cover props, slots, and accessibility
- [ ] Documentation includes Usage, Examples, and API sections
- [ ] Conventional commit message format
- [ ] All checks pass (lint, typecheck, test)

Code Conventions

Convention	Description
Type imports	Always separate: `import type { X }` on its own line
Props defaults	Use `withDefaults()` for runtime, JSDoc `@defaultValue` for docs
Template slots	Add `data-slot="name"` attributes on all elements
Computed ui	Always use `computed(() => tv(...))` for reactive theming
Theme support	Use `useComponentUI(name, props)` to merge Theme context with component prop

Commands

pnpm run dev:prepare  # Generate type stubs (run after install)
pnpm run dev          # Nuxt playground
pnpm run dev:vue      # Vue playground
pnpm run docs         # Documentation site
pnpm run lint         # Check linting
pnpm run lint:fix     # Fix linting
pnpm run typecheck    # Type checking
pnpm run test         # Run tests

Resources

Weekly Installs

334

Repository

nuxt/ui

GitHub Stars

6.4K

First Seen

Feb 1, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

codex243

cursor241

claude-code239

opencode234

gemini-cli233

github-copilot232

Flutter应用架构设计指南：分层结构、数据层实现与最佳实践

3,000 周安装