贡献

Nuxt 是一个社区项目——因此我们欢迎各种形式的贡献!❤️

你可以通过多种不同的方式为 Nuxt 生态系统做出贡献。

生态系统

Nuxt 生态系统包含许多不同的项目和组织:

  • nuxt/ - Nuxt 框架本身的核心仓库。nuxt/nuxt 包含 Nuxt 框架的版本 2 和 3。
  • nuxt-modules/ - 社区贡献和维护的模块与库。这里有一个模块迁移流程nuxt-modules。虽然这些模块由各自的维护者负责,但它们不依赖单一人员。
  • unjs/ - 许多库在 Nuxt 生态系统中被广泛使用。它们设计为通用库,独立于框架和环境。我们欢迎其他框架和项目的贡献与使用。

如何贡献

分类问题并参与讨论

查看你想帮助的项目的问题(issues)和讨论(discussions)。例如,以下是 Nuxt 的问题列表讨论区。帮助其他用户、分享解决方案、创建复现示例,或者稍微研究一下 bug 并分享你的发现,都会带来巨大的影响。

创建问题(Issues)

感谢你花时间创建问题!❤️

  • 报告 Bug:请查看我们的指南,了解在提 issue 前需要做的一些准备工作。
  • 功能请求:请确认是否已有相关 issue 或讨论涵盖你想要的功能范围。如果功能属于 Nuxt 生态系统的其他部分(如某个模块),请优先在那里提出功能请求。如果你的功能需求较为通用或 API 不够明确,建议先在 Ideas 区域开启讨论,与社区沟通交流。

我们会尽力依据我们的内部问题决策流程图来响应问题。

提交 Pull Request

我们始终欢迎 Pull Requests!❤️

开始前的准备

在修复 Bug 之前,建议先确认是否已有相关 issue,因为可能是文档错误或存在有用的上下文信息。

如果你在开发新功能,请先开启一个功能请求 issue,与维护者讨论该功能是否被需要以及设计细节。这可以节省维护者和贡献者双方的时间,并帮助功能更快发布。该 issue 必须由框架团队成员确认,才可开始在 PR 中实现功能。

对拼写错误的修正建议集中在一个 PR 中提交,以保持提交历史整洁。

对 Nuxt 本身进行较大改动时,建议先创建一个 Nuxt 模块实现功能原型,再以讨论形式创建 RFC。用户采用并反馈后,功能可以完善并合入 Nuxt 核心或继续作为独立模块。

提交规范

提交信息采用 Conventional Commits 规范,可自动生成变更日志。如果你不熟悉,请务必阅读相关指南。

注意,fix:feat: 用于实际的代码变更(可能影响逻辑)。拼写或文档修改应使用 docs:chore:

  • fix: typo -> docs: fix typo

如果你在类似 nuxt/nuxt 这种 monorepo 项目中工作,提交信息中请标明主要作用域,如:feat(kit): add 'addMagicStuff' utility

如何提交 Pull Request

如果你不知道如何发起 PR,推荐阅读官方指南

发起 PR 时,请确保标题也遵守提交规范

PR 解决或修复了已有 issues,请务必在 PR 描述中提及它们。

一个 PR 中可以包含多个提交;你无需对提交进行 rebase 或强制推送,我们会使用“Squash and Merge”方式合并成一个提交。

我们不会配置任何提交钩子以支持快速提交,但发起 PR 前,请确保所有 lint 和测试脚本通过。

一般请确保 PR 中不包含与主改动无关的变更。例如编辑器自动调整的空白或格式变动请还原,避免干扰审核。且避免在一个 PR 中包含多项无关功能或修复,最好分开成多个 PR 分别审查合并。原则上,一个 PR 仅做“单一事项”。

发起 PR 后

发起 PR 后,我们会尽快进行审查。

如果我们给 PR 指派了维护者,说明该维护者将特别关注其审查和改动。

如果我们在 PR 上请求改动,请别在意红色文字!这并不代表 PR 不好,而是方便快速查看状态的方式。

如果标记为“pending”,说明可能还有其他任务待完成,是内部提醒,并非反映 PR 是否合理。我们会尽力在评论中说明“pending”原因。

我们会尽力遵照PR 决策流程图审查 PR。

创建模块

如果你用 Nuxt 做了很酷的东西,何不将其抽离成一个模块,方便共享?我们已经有很多优秀模块,但永远欢迎更多。

构建模块时若需帮助,欢迎随时联系我们

制定 RFC

我们强烈建议先创建模块验证大型新功能并获得社区采用。

如果你已经这么做了,或不适合创建新模块,请先开启新讨论。确保尽可能清晰地阐明你的想法,附上代码示例或新 API 的函数签名,引用相关问题和痛点实例。

如果我们认为应制定 RFC,会将讨论类别切换成 RFC 并广泛征求反馈。

RFC 将经历以下阶段:

  • rfc: active - 正开放征询意见
  • rfc: approved - 被 Nuxt 团队批准
  • rfc: ready to implement - 已创建并分配相应实现 issue
  • rfc: shipped - 已实现
  • rfc: archived - 未批准,但存档备查

生态系统中的规范

以下规范在 nuxt/ 组织内是_必须_遵守的,其他维护者也建议采纳。

模块规范

模块应遵循Nuxt 模块模板规范。详见module 指南

使用核心 unjs/

推荐使用下面这些贯穿生态系统的库:

  • pathe - 通用路径工具(取代 node 的 path
  • ufo - URL 解析和合并工具
  • unbuild - 基于 rollup 的构建系统
  • … 更多可查看unjs/ 组织其他仓库!

使用 ESM 语法并默认 type: module

大多数 Nuxt 生态系统都能直接消费 ESM。一般建议避免使用 CJS 特有的代码,如 __dirnamerequire。可阅读更多关于 ESM 的内容这里

什么是 Corepack

Corepack 能确保你运行命令时使用合适版本的包管理器。项目的 package.json 中可能包含 packageManager 字段。

在配置如下的项目中,Corepack 会安装 pnpmv7.5.0 版本(如果你尚未安装)并使用它执行命令。

package.json
{
  "packageManager": "pnpm@7.5.0"
}

使用 ESLint

我们使用 ESLint 做代码检查和格式化,配合使用@nuxt/eslint

IDE 设置

推荐使用 VS CodeESLint 扩展。如果愿意,可启用自动修复和格式化保存功能:

settings.json
{
  "editor.codeActionsOnSave": {
    "source.fixAll": "never",
    "source.fixAll.eslint": "explicit"
  }
}

不使用 Prettier

由于 ESLint 已配置代码格式化,无需再使用 Prettier 重复功能。你可以运行 yarn lint --fixpnpm lint --fix,或 bun run lint --fix 来格式化代码,或参考ESLint 章节进行 IDE 设置。

如果你的编辑器安装了 Prettier,建议在参与本项目时禁用它,以避免冲突。

包管理器

推荐在模块、库和应用中使用 pnpm 作为包管理器。

强烈建议启用 Corepack,确保你使用的包管理器版本与项目一致。Corepack 集成在较新的 Node 版本中,实现无缝的包管理器支持。

启用命令:

Terminal
corepack enable

该操作在电脑安装 Node.js 后只需执行一次。

文档风格指南

文档是 Nuxt 的重要组成部分。我们致力于打造直观易用的框架,其中很大一部分是确保开发者体验和生态系统内的文档都是完美的。👌

以下是一些可助你改进文档的建议:

  • 尽量避免使用 simplyjustobviously 等主观词汇。
    记住读者背景和经验不同,这些词不具实质含义,反而可能造成误解。
    Simply make sure the function returns a promise.
    Make sure the function returns a promise.
  • 优先使用主动语态
    An error will be thrown by Nuxt.
    Nuxt will throw an error.
了解如何贡献文档。