贡献指南

一份关于如何为 Nuxt UI 贡献的全面指南，涵盖项目结构、开发流程和最佳实践。

Nuxt UI 的蓬勃发展离不开其卓越的社区 ❤️。我们欢迎所有通过错误报告、拉取请求和反馈形式的贡献，以帮助使此库变得更好。

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

项目结构

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

文档

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

├── 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)

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

如果没有，请开启一个新议题来讨论问题或功能。

本地开发

要开始本地开发，请遵循以下步骤

克隆 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
  • 要使用**演示环境**测试 Nuxt 组件，请运行
pnpm run dev
  • 要使用**演示环境**测试 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作为提交信息规范，它允许根据提交自动生成变更日志。如果您还不熟悉它，请阅读指南。

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

创建拉取请求

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

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

感谢

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