Back to Details

contributing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Nuxt UI Development

Nuxt UI 开发指南

Guidelines for contributing to the Nuxt UI component library.
Nuxt UI组件库贡献规范指南

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
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 for Scaffolding

脚手架CLI工具

Always use the CLI when creating new components:
bash
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
    )
创建新组件时请务必使用CLI工具：
bash
nuxt-ui make component <name> [options]
可选参数：
  • --primitive
    - 基础组件（基于Reka UI Primitive实现）
  • --prose
    - 排版/文本组件
  • --content
    - 内容组件
  • --template
    - 仅生成指定模板（可选值：
    playground
    、
    docs
    、
    test
    、
    theme
    、
    component
    ）

Available Guidance

可用参考指南

FileTopics
references/component-structure.mdVue component file patterns, props/slots/emits interfaces, script setup
references/theme-structure.mdTailwind Variants theme files, slots, variants, compoundVariants
references/testing.mdVitest patterns, snapshot testing, accessibility testing
references/documentation.mdComponent docs structure, MDC syntax, examples
文件主题
references/component-structure.mdVue组件文件格式、props/插槽/事件接口、script setup语法
references/theme-structure.mdTailwind Variants主题文件、插槽、变体样式、复合变体配置
references/testing.mdVitest测试模式、快照测试、可访问性测试
references/documentation.md组件文档结构、MDC语法、示例编写

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.
根据你的任务加载对应参考文件：
  • references/component-structure.md - 当你需要创建/修改Vue组件时
  • references/theme-structure.md - 当你需要处理组件主题配置时
  • references/testing.md - 当你需要编写或审核测试用例时
  • references/documentation.md - 当你需要编写组件文档时
请勿一次性加载所有文件，仅加载与当前任务相关的内容。

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
复制以下检查清单，在创建新组件时跟踪进度：
组件名称: [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 Review Checklist

PR审核检查清单

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)
审核组件PR时，请验证以下内容：
PR审核:
- [ ] 组件遵循现有代码模式（参考references/目录下的指南）
- [ ] 主题使用语义化颜色，而非直接使用Tailwind调色板
- [ ] 测试用例覆盖props、插槽和可访问性
- [ ] 文档包含使用方法、示例和API说明部分
- [ ] 提交信息符合约定式提交格式
- [ ] 所有检查项通过（代码规范、类型检查、测试）

Code Conventions

代码规范

ConventionDescription
Type importsAlways separate: 
import type { X }
on its own line
Props defaultsUse 
withDefaults()
for runtime, JSDoc 
@defaultValue
for docs
Template slotsAdd 
data-slot="name"
attributes on all elements
Computed uiAlways use 
computed(() => tv(...))
for reactive theming
Theme supportUse 
useComponentUI(name, props)
to merge Theme context with component 
ui
prop
Semantic colorsUse 
text-default
, 
bg-elevated
, etc. - never Tailwind palette
Reka UI propsUse 
reactivePick
+ 
useForwardPropsEmits
to forward props
Form componentsUse 
useFormField
and 
useFieldGroup
composables
规范说明
类型导入单独导入类型：
import type { X }
单独占一行
Props默认值运行时使用
withDefaults()
，文档中使用JSDoc 
@defaultValue
标注
模板插槽所有插槽元素添加
data-slot="name"
属性
响应式UI计算始终使用
computed(() => tv(...))
实现响应式主题
主题支持使用
useComponentUI(name, props)
将主题上下文与组件
ui
属性合并
语义化颜色使用
text-default
、
bg-elevated
等语义化类名，切勿直接使用Tailwind调色板类
Reka UI属性使用
reactivePick
+ 
useForwardPropsEmits
转发属性
表单组件使用
useFormField
和
useFieldGroup
组合式函数

Commands

常用命令

bash
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
bash
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         # 运行测试用例

Resources

参考资源