贡献指南

Nuxt UI 贡献指南，包含项目结构、开发流程和最佳实践。

Nuxt UI 的繁荣离不开其卓越的社区支持 ❤️。我们欢迎通过错误报告、拉取请求和反馈等方式进行所有贡献，以帮助让这个库变得更好。

在报告错误或提出功能请求之前，请确保您已阅读我们的文档以及现有问题.

项目结构

以下是 Nuxt UI 项目结构中关键目录和文件的概览

文档

文档位于 docs 文件夹中，它是一个使用 @nuxt/content v3 从 Markdown 文件生成页面的 Nuxt 应用。请参阅Content v3 文档以了解其工作原理的详细信息。以下是其结构的细分

├── app/
│   ├── assets/
│   ├── components/
│   │   └── content/
│   │       └── examples   # Components used in documentation as examples
│   ├── composables/
│   └── ...
├── content/
│   ├── 1.getting-started
│   ├── 2.composables
│   └── 3.components       # Components documentation

模块

模块代码位于 src 文件夹中。以下是其结构的细分

├── plugins/
├── runtime/
│   ├── components/        # Where all the components are located
│   │   ├── Accordion.vue
│   │   ├── Alert.vue
│   │   └── ...
│   ├── composables/
│   ├── locale/
│   ├── plugins/
│   ├── types/
│   ├── utils/
│   └── vue/
│       ├── components/
│       └── plugins/
├── theme/                 # This where the theme for each component is located
│   ├── accordion.ts       # Theme for Accordion component
│   ├── alert.ts
│   └── ...
└── module.ts

CLI

为了让开发更容易，我们创建了一个 CLI，您可以使用它来生成组件和语言环境。您可以通过 nuxt-ui make 命令访问它。

首先，您需要将 CLI 链接到您的全局环境

npm link

组件

您可以使用以下命令创建新组件

nuxt-ui make component <name> [options]

可用选项

  • --primitive 创建一个基础组件
  • --pro 创建一个 pro 组件
  • --prose 创建一个 prose 组件（需要 --pro）
  • --content 创建一个内容组件（需要 --pro）
  • --template 仅生成特定模板（可用模板：playground, docs, test, theme, component）

示例

# Create a basic component
nuxt-ui make component my-component

# Create a pro component
nuxt-ui make component page-section --pro

# Create a pro prose component
nuxt-ui make component heading --pro --prose

# Create a pro content component
nuxt-ui make component block --pro --content

# Generate only documentation template
nuxt-ui make component my-component --template=docs
创建新组件时，CLI 会自动生成所有必要的文件，例如组件本身、主题、测试和文档。

语言环境

您可以使用以下命令创建新的语言环境

nuxt-ui make locale --code <code> --name <name>
在文档中了解更多关于 i18n 的信息。

提交拉取请求 (PR)

在开始之前，请检查是否存在描述您正在处理的问题或功能请求的现有问题。如果存在，请在该问题下留言，告知我们您正在处理它。

如果不存在，请开启一个新问题来讨论该问题或功能。

本地开发

要开始本地开发，请按照以下步骤操作

将 nuxt/ui 仓库克隆到您的本地机器上

git clone -b v3 https://github.com/nuxt/ui.git

启用 Corepack

corepack enable

安装依赖

pnpm install

生成类型存根

pnpm run dev:prepare

启动开发

  • 要处理位于 docs 文件夹中的文档，请运行
pnpm run docs
  • 要使用playground测试 Nuxt 组件，请运行
pnpm run dev
  • 要使用playground测试 Vue 组件，请运行
pnpm run dev:vue
如果您正在实现新组件，请查看CLI部分以启动该过程。

IDE 设置

我们建议使用 VSCode 并搭配ESLint 扩展。您可以启用代码保存时的自动修复和格式化。方法如下

{
  "editor.codeActionsOnSave": {
    "source.fixAll": false,
    "source.fixAll.eslint": true
  }
}
由于 ESLint 已配置为格式化代码，因此无需与 Prettier 重复功能。如果您的编辑器中安装了它，我们建议禁用它以避免冲突。

代码检查

您可以使用 lint 命令检查代码检查错误

pnpm run lint # check for linting errors
pnpm run lint:fix # fix linting errors

类型检查

我们使用 TypeScript 进行类型检查。您可以使用 typecheck 命令检查类型错误

pnpm run typecheck

测试

在提交 PR 之前，请确保您已运行 nuxt 和 vue 的测试

pnpm run test # for Nuxt
pnpm run test:vue # for Vue
如果需要更新快照，请在运行测试时按 u。

提交规范

我们使用Conventional Commits来规范提交消息，这使得可以根据提交自动生成一份 changelog。请阅读指南如果您还不熟悉，请仔细阅读。

  • 对于影响功能或逻辑的代码更改，请使用 fix 和 feat
  • 对于文档更改，请使用 docs；对于维护任务，请使用 chore

创建拉取请求

  • 请按照说明在创建 PR 时提供的
  • 确保您的 PR 标题符合Conventional Commits因为它将在代码合并后使用。
  • 多次提交没有问题；无需 rebase 或 force push。合并时我们将使用 Squash and Merge。
  • 在提交 PR 之前，确保 lint、typecheck 和 tests 通过。避免进行不相关的更改。

我们会尽快进行审核。如果分配给维护者，他们会仔细审核。忽略红色文本；那是用于跟踪目的的。

感谢

再次感谢您对本项目感兴趣！您非常棒！❤️