贡献指南

关于如何贡献 Nuxt UI 的综合指南，包括项目结构、开发工作流程和最佳实践。

Nuxt UI 的蓬勃发展归功于其令人难以置信的社区 ❤️。我们欢迎通过错误报告、拉取请求和反馈意见进行的所有贡献，以帮助使这个库变得更好。

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

项目结构

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

文档

文档位于 docs 文件夹中，作为一个使用 @nuxt/content v3 的 Nuxt 应用程序，用于从 Markdown 文件生成页面。请参阅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 创建一个专业版组件
--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)

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

如果没有，请打开一个新的 issue 来讨论问题或功能。

本地开发

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

克隆 `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 重复功能。如果您的编辑器中安装了 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来编写提交消息，这允许基于提交自动生成变更日志。如果您尚不熟悉，请阅读指南。

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

创建拉取请求

在创建 PR 时，请遵循说明。
确保您的 PR 标题符合Conventional Commits，因为它将在代码合并后使用。
多个提交是可以的；无需变基或强制推送。合并时，我们将使用 Squash and Merge。
在提交 PR 之前，请确保 lint、typecheck 和 tests 工作正常。避免进行不相关的更改。

我们会及时审查。如果分配给维护者，他们会仔细审查。忽略红色文本；它用于跟踪目的。

感谢

再次感谢您对这个项目感兴趣！您太棒了！ ❤️