[!警告] 本代码仓库已被归档并停止维护。现有的配置仍将公开供参考。

Vercel 风格指南

引言

本代码仓库是 Vercel 风格指南的存放地，其中包含了流行代码检查和样式工具的配置。

以下配置可供使用，且设计为协同使用。

• Prettier
• ESLint
• TypeScript

贡献指南

在创建拉取请求前，请阅读我们的贡献指南。

安装

我们的所有配置都包含在一个包中，@vercel/style-guide。安装方法如下：

# If you use npm
npm i --save-dev @vercel/style-guide

# If you use pnpm
pnpm i --save-dev @vercel/style-guide

# If you use Yarn
yarn add --dev @vercel/style-guide

部分 ESLint 配置需要同行依赖。我们会在 ESLint 部分旁注记这些配置。

Prettier

注意：Prettier 是本软件包的同行依赖，应当在项目根目录进行安装。

参阅：https://prettier.io/docs/en/install.html

要使用共享的 Prettier 配置，请在 package.json 中设置如下内容。

{
  "prettier": "@vercel/style-guide/prettier"
}

ESLint

注意：ESLint 是此包的同伴依赖项，应安装在您的项目根目录。

查看：ESLint 安装与使用

此 ESLint 配置旨在支持组合使用。

以下基础配置可用。您可以选择使用其中一个或两个配置，但它们应该始终位于 extends 的首位：

• @vercel/style-guide/eslint/browser
• @vercel/style-guide/eslint/node

请注意，您可以限定配置范围，使配置仅针对特定文件。更多信息，请参见：使用 overrides 进行范围配置。

以下为可用的额外配置：

• @vercel/style-guide/eslint/jest
• @vercel/style-guide/eslint/jest-react（包含 @testing-library/react 规则）
• @vercel/style-guide/eslint/next（需要与 next 相同版本的 @next/eslint-plugin-next 已安装）
• @vercel/style-guide/eslint/playwright-test
• @vercel/style-guide/eslint/react
• @vercel/style-guide/eslint/typescript（需要安装 typescript 以及进行额外配置）
• @vercel/style-guide/eslint/vitest

由于 ESLint 配置解析的问题，您需要使用 require.resolve 为 ESLint 提供绝对路径（参见 eslint/eslint#9188)。

例如，在 Next.js 项目中使用共享 ESLint 配置，请在 .eslintrc.js 中设置以下内容。

module.exports = {
  extends: [
    require.resolve('@vercel/style-guide/eslint/browser'),
    require.resolve('@vercel/style-guide/eslint/react'),
    require.resolve('@vercel/style-guide/eslint/next'),
  ],
};

为 TypeScript 配置 ESLint

TypeScript 配置中启用的某些规则需要额外的类型信息，您需要提供 tsconfig.json 文件的路径。

更多信息请参阅：https://typescript-eslint.io/docs/linting/type-linting

const { resolve } = require('node:path');

const project = resolve(__dirname, 'tsconfig.json');

module.exports = {
  root: true,
  extends: [
    require.resolve('@vercel/style-guide/eslint/node'),
    require.resolve('@vercel/style-guide/eslint/typescript'),
  ],
  parserOptions: {
    project,
  },
  settings: {
    'import/resolver': {
      typescript: {
        project,
      },
    },
  },
};

为 jsx-a11y 配置自定义组件

在 React 应用程序中，通常会使用如 Button 这样的共享组件，这些组件封装了原生元素。您可以通过 components 设置将此类信息传递给 jsx-a11y。

以下列表并不全面。

module.exports = {
  root: true,
  extends: [require.resolve('@vercel/style-guide/eslint/react')],
  settings: {
    'jsx-a11y': {
      components: {
        Article: 'article',
        Button: 'button',
        Image: 'img',
        Input: 'input',
        Link: 'a',
        Video: 'video',
      },
    },
  },
};

使用 overrides 实现作用域配置

ESLint 配置可以设定作用域以包含或排除特定路径。这样可以确保规则不会“泄露”到不适用这些规则的地方。

在以下示例中，Jest 规则仅应用于符合 Jest 默认测试匹配模式的文件。

module.exports = {
  extends: [require.resolve('@vercel/style-guide/eslint/node')],
  overrides: [
    {
      files: ['**/__tests__/**/*.[jt]s?(x)', '**/?(*.)+(spec|test).[jt]s?(x)'],
      extends: [require.resolve('@vercel/style-guide/eslint/jest')],
    },
  ],
};

关于文件扩展名的说明

默认情况下，所有TypeScript规则仅适用于以.ts和.tsx结尾的文件。

但是，在启用覆盖规则时，必须包含文件扩展名，否则ESLint将只会包含.js文件。

module.exports = {
  overrides: [
    { files: [`directory/**/*.[jt]s?(x)`], rules: { 'my-rule': 'off' } },
  ],
};

TypeScript

本指南提供了多种 TypeScript 配置选项。这些配置与 LTS 版本的 Node.js 相对应，为每个版本提供了恰当的 lib、module、target 以及 moduleResolution 设置。以下为可用的配置：

Node.js 版本	TypeScript 配置
v16	@vercel/style-guide/typescript/node16
v18	@vercel/style-guide/typescript/node18
v20	@vercel/style-guide/typescript/node20

若要使用共享的 TypeScript 配置，请在 tsconfig.json 中进行如下设置。

{
  "extends": "@vercel/style-guide/typescript/node16"
}

基础 TypeScript 配置同样可以通过 @vercel/style-guide/typescript 获得，该配置仅定义了一套通用规则。在设置自定义 lib、module、target 和 moduleResolution 配置时，您应该继承此文件。