alibaba / f2e-spec

Alibaba Front-end Coding Guidelines and Relevant Tools

阿里巴巴前端规约及配套工具

简介

「阿里巴巴前端规约」是在阿里经济体内广泛使用的一套前端编码和工程规范，致力于通过统一编码风格、普及最佳实践和代码缺陷检查帮助团队降低协作成本、提升前端项目的可维护性和稳定性。

本项目主要包括「规约文档」和「配套工具」两部分。你可以通过阅读规约文档了解各前端语言、框架及工程规范，并使用 F2ELint 等配套工具来为项目接入规约检查。

规约文档

规约文档分为编码规约和工程规约两大类，包括：

• 编码规约
  • HTML 编码规约
  • CSS 编码规约
  • JavaScript 编码规约
  • React 编码规约
  • Node.js 开发规约
  • TypeScript 编码规约
  • Rax 编码规约
• 工程规约
  • Git 规约
  • 文档通用规约
  • 更新日志规约

配套工具

我们引入了多个业界流行的 Linter 作为规约文档的配套工具，并根据规约内容定制了对应的规则包，它们包括：

规约	Lint 工具	规则包
《JavaScript 编码规约》 《TypeScript 编码规约》 《React 编码规约》 《Rax 编码规约》 《Node.js 开发规约》	ESLint	eslint-config-ali
《CSS 编码规约》	stylelint	stylelint-config-ali
《Git 规约》	commitlint	commitlint-config-ali
《文档通用规约》	markdownlint	markdownlint-config-ali

可以看到这些 Linter 和规则包众多且零散，全部安装它们会给项目增加十几个依赖，接入及后续升级成本都比较高。

因此我们封装了 F2ELint 这个 npm 包，它收敛屏蔽了这些依赖和配置细节，提供简单的 CLI 和 Node.js API，让项目能够一键接入、一键扫描、一键修复、一键升级，并为项目配置 git commit 卡口，降低项目接入规约的成本。

你可以使用 F2ELint 方便地为项目接入全套规约 Lint，也可以根据需求单独安装 xx-config-ali 和相关 Linter。

如何参与

非常欢迎大家通过 Issues 反馈问题和需求，或者通过 PRs 参与贡献，请参考 CONTRIBUTING.md。

贡献者信息

文档撰写人员（排名不分先后）：邦彦、尘弦、迟帆、大果、氐宿、法海、姬无、倞羽、连木、林熠、零弌、墨止、牧曈、霂之、年翼、清锐、萨波、释然、双龙、苏青、阎罗、扬炀、洋风、云谦、载天、梓骞

文档审阅人员（排名不分先后）：大貘、九十、狼叔、龙归、秦粤、上坡、死月、苏千、吞吞、潕量、艺璇、游鹿、裕波、张挺、知忧

工具编写人员（排名不分先后）：尘弦、鹤仙、连木、牧曈、年翼、秦粤、萨波、双龙、扬炀、洋风

引用信息及鸣谢

本项目的文档部分参考或引用了许多优秀的业界开源规范、标准化文档和技术官网，它们主要包括：

• Airbnb Style Guide
• Google Style Guide
• Code Guide by @mdo
• ecomfe/spec
• Conventional Commits
• Conventional Changelog
• MDN Web 开发者文档
• React 官方文档
• 谷歌 Web 开发者文档

更详细的引用说明请参见各规约文档的「参考资料」章节。

本项目的配套工具使用了多个优秀的 Linter、Formatter 及社区生态，主要包括：

• ESLint 及多个 plugin 和 parser
• stylelint 及 stylelint-scss
• commitlint 及 conventional-changelog-conventionalcommits
• markdownlint

在此表示感谢，如有侵权行为，敬请联系我们 :-)

f2e-spec's Issues

f2elint.scan 中 outputReport 参数无效

文档中 outputReport 为 是否输出扫描出的规约问题日志 的配置。
但经过测试，无论这个值是 true 还是 false ,执行过程中都会输出检测的详情。

  const tempLint = await f2elint.scan({
    cwd: projectPath,
    include: "./src",
    fix: false,
    quiet: false,
    outputReport: true,
  });

版本： "f2elint": "^2.2.1"

能不能升级eslint-plugin-vue ，支持 vue3 script setup写法

Does not work well with <script setup>
The variables used in the are warned by no-unused-vars rule

能不能升级eslint-plugin-vue ，支持 vue3 script setup写法

babel-eslint is deprecated using @babel/eslint-parser instead.

禁用 @typescript-eslint/indent 规则

目前 typescript 的 eslint 配置中包含 @typescript-eslint/indent：

f2e-spec/packages/eslint-config-ali/rules/typescript.js

Line 169 in 3eef290

'@typescript-eslint/indent': [

然而，该规则存在许多难以解决的问题，作者也表示目前没有资源维护，不建议使用：

https://typescript-eslint.io/rules/indent/
typescript-eslint/typescript-eslint#1824

实践中，该规则经常会对 prettier 输出的缩进报错，比如：

type Foo =
  | {
      a: 'b';
    }
  | {
      c: 'd';
    }

升级 Stylelint 到 14.x

目前内置的 stylelint 是 13.x，而 vscode-stylelint 不再支持 stylelint 13 了，应当升级到 stylelint 14

Stylelint 规则的 error 和 warning 级别

color-hex-length 被 stylelint 判断为 error 了。

stylelint-config-ali 0.4.2 修复了这个问题，但是好像没有发布。

fix 指令不支持指定文件和目录

指定了 -i --include 后，还是全局扫的，这个文件一多，电脑就卡主了，希望修复一下或者提供一下正确使用的姿势，谢谢。

多包检测项目慢建议

    parserOptions: {
        // !跟lint速度关联,加上这个可以解决
        project: './tsconfig.*?.json', 
        createDefaultProgram: true,
        extraFileExtensions: ['.vue'],
    },

f2elint执行scan命令时，无法扫描style文件

使用f2elint init命令之后，选择了styleLint，f2elint.config.js的内容如下：

module.exports = {
  enableStylelint: true,
  enableMarkdownlint: false,
  enablePrettier: true,
};

.stylelintrc.js的内容如下：

module.exports = {
  extends: 'stylelint-config-ali',
};

.stylelintignore的内容如下：

node_modules/
build/
dist/
coverage/
es/
lib/
**/*.min.css
**/*-min.css
**/*.bundle.css

这些都是自动生成的。

项目使用Less，有很多.less文件，但是只执行f2elint scan命令之后，查看输出没有一个跟less文件有关的输出。

后面使用stylelint **/*.less缺有很多less文件的错误。

经过查看源码，发现原因如下：
ESLint的参数是需要传入文件或者目录（ you can run ESLint on any file or directory ）；
StyleLint的参数是传输文件或者pattern（Files(s), glob(s)）；
但是在f2elint的源码里，给ESLint和StyleLint传入的默认参数是一样的（都是加了绝对路径的parttern），比如：
对ESLint的参数是：C:\Users\abc**.{js,jsx,ts,tsx,vue}
对StyleLint的参数是：C:\Users\abc**.{css,scss,less,acss}

这样的参数传给StyleLint之后，StyleLint使用Globy就无法匹配到任何Less文件，所以就无法对其进行扫描。

HUSKY_GIT_PARAMS is removed

HUSKY_GIT_PARAMS is removed

At https://github.com/alibaba/f2e-spec/blob/main/packages/f2elint/src/cli.ts#L102

From https://github.com/typicode/husky/blob/840c4164d06d3c412caf63a9c9d7ca1af15f2165/docs/README.md#breaking-changes

可否增加一个配置项，跳过自动安装依赖的步骤

背景是初始化项目时，脚手架调用了f2elint的初始化，开始安装f2elint的依赖，后面又需要安装项目本身依赖。建议增加一个跳过项如：disableAutoInstall，统一进行项目依赖的安装:

 await f2elint.init({
      cwd: cwd,
      eslintType: `typescript/${dsl}`,
      enableStylelint: true,
      enableMarkdownlint: false,
      enablePrettier: true,
      disableAutoInstall: true
    });

immerjs

目前业务项目中大量使用了 immerjs：

import produce from "immer"

const nextState = produce(baseState, draft => {
    draft[1].done = true
    draft.push({title: "Tweet about it"})
})

这种直接修改入参的代码，在 eslint-config-ali 之下，会显示警告。而 immer 就是被设计成这样使用的，这个规则是不是可以为 immer 开个白名单？（不确定技术上是否可行）。

[f2elint]暴露 prettierr 配置项

希望有 eslint 和 stylelint 对应的配置项包，希望增加暴露 prettierr 的配置项。

commitlint报错

按照文档安装好f2elint后，git commit或f2elint commit-msg-scan报错“node_modules\f2elint\node_modules.bin\commitlint”不是内部或外部命令，也不是可运行的程序或批处理文件，打开对应目录也并没有相应的文件。

出现错误：Cannot read properties of undefined (reading 'type')。需要更新下最新的配置信息，否则ESLint将报错失效。

导致出现问题的配置行：

f2e-spec/packages/eslint-config-ali/rules/typescript.js

Line 193 in 3eef290

ignoredNodes: [

目前测试下来，发现的出现问题的地方是 ignoredNodes 下的 JSXElement > * 会导致ESLint 无法进行 lint 操作。

可以考虑更新到版本： https://github.com/benjamn/ast-types/blob/master/src/def/jsx.ts，内容如下：

       ignoredNodes: [
          "JSXElement",
          "JSXAttribute",
          "JSXIdentifier",
          "JSXNamespacedName",
          "JSXMemberExpression",
          "JSXSpreadAttribute",
          "JSXExpressionContainer",
          "JSXOpeningElement",
          "JSXClosingElement",
          "JSXFragment",
          "JSXOpeningFragment",
          "JSXClosingFragment",
          "JSXText",
          "JSXEmptyExpression",
          "JSXSpreadChild",
        ],

• @vue/cli 版本 5.0.8

• 安装的项目是vue 2.0 +typescript 的运行环境。

• ESLint 继承的是 eslint-config-ali/typescript/vue

• ESLint 版本：7.32.0

• ESLint 运行时错误提示如下：

[Info  - 18:22:37] ESLint server is starting.
[Info  - 18:22:37] ESLint server running in node v16.13.2
[Info  - 18:22:37] ESLint server is running.
[Info  - 18:22:39] ESLint library loaded from: E:\Yancy\Documents\Visual Studio 2022\Workspaces\路甫\OfficialWebsite\lufu.tools.line_phone_call.app_ui\node_modules\_[email protected]@eslint\lib\api.js
[Error - 18:22:45] An unexpected error occurred:
[Error - 18:22:45] TypeError: Cannot read properties of undefined (reading 'type')
……

不应该硬编码其他npm包的路径

f2e-spec/packages/f2elint/src/lints/markdownlint.ts

Line 25 in 5787d0d

path.resolve(__dirname, '../../node_modules/markdownlint-config-ali/index.json'),

上面这段代码假设了 npm 安装结构为：

└── node_modules
    └── f2elint
        └── node_modules
            └── markdownlint-config-ali

但实际的安装结构可能是：

└── node_modules
    ├── f2elint
    └── markdownlint-config-ali

f2elint fix 无法修复 eslint 问题

比如以下代码，在 vs code 中保存并格式化，eslint 是能够将 let 修正为 const 的，但是运行 f2elint fix 命令却不会修复这个问题：

export function foo() {
  let bar = 'bar';
  return bar;
}

为什么import { type } 会提示@typescript-eslint/no-unused-vars?

.eslintrc.js

common.interface.ts

Header.tsx

错误提示：

我的其他文件中 也会报相同的问题，只要我import type 都会被提示 @typescript-eslint/no-unused-vars

.js 格式的 rc 配置文件在 type: module 的 Node.js ESM 中解析出错

只要 package.json 中添加了 type: module，Prettier，Stylelint 和 ESLint 就会全部失效。因为它们的 rc 文件全部是 JS 格式，且用的是 CJS 的 module.exports。一旦这个包被标记为 ESM，就无法解析这种用法了。

考虑到 Node.js 的 ESM 正逐渐普及，这种情况可能会越来越多。

而目前的配置中，并没有需要用 JS 进行运算的地方，JSON 完全可以满足需求。

调整 react/display-name 规则为 warn

有人反馈了这么一个问题
https://yuque.antfin.com/junyu.junyujiang/tqm89a/dxyevf#ded12232

TL;DR
eslint 的 react hooks rule 只会对大驼峰和 useXxx 命名的函数生效，不会检测匿名函数。所以考虑是否推荐用户使用命名函数，开启 react/display-name 规则

笔误

2.7.12【参考】模块开发者选择EMS和CJS时

这里EMS应该是想写ESM吧

"import/named" 为什么关闭

"import/named" 这条规则我认为是有必要开的，可以避免 import 不存在的模块

建议提供其他包管理工具选项

如题，目前f2elint 仅支持 tnpm和npm，能否提供命令支持使用 yarn 或 pnpm

react 规约和 ts react 规约同一个文件规则不一致

使用版本： "f2elint": "^0.4.2"

ts react 规约配置如下：

// .eslintrc.js
module.exports = {
  extends: 'eslint-config-ali/typescript/react',
};

ts react 规约会提示 lint 规则如下：

但是 react 规约的不会提示，配置如下

// .eslintrc.js
module.exports = {
  extends: 'eslint-config-ali/react',
};

f2elint commit scan与pnpm好像存在冲突

我不清楚你们还需要我提供什么信息？如果需要请及时告知~

husky 不执行

规范合约文档有开源的计划吗？

RT,如很多人期望的那样。

考虑支持vue3吗

作者们好
请问考虑支持vue3吗？

JavaScript 规约疑似存在非法字符

例如：

f2e-spec/docs/coding/3.javascript-style-guide.md

Line 2837 in a497e5e

- 5.2【强制】对于逗号分隔的多行结构，不要加上最后一个�行末逗号。eslint: [comma-dangle](https://eslint.org/docs/rules/comma-dangle)

我不知道这样的字符是否是特意加上的，因此没有提交 PR.

f2elint init 时清理 @ali/kyle 相关包和文件

@ali/kyle 是一个已经不再维护的前端代码风格检查套件，可以完全被 f2elint 替代。

f2elint init 需要移除的包依赖

• @ali/kyle
• @ali/kyle-config-saga
• @ali/kyle-config-next
• @ali/kyle-config-mext

需要移除的文件

• .kylerc
• .kylerc.json
• .kylerc.js

需要移除的 scripts：

• lint
• lint:ci

lerna 项目该如何使用 f2elint 统一管理多个子项目呢？

ignorePath is not set correctly

lintConfig.ignorePath = path.resolve(__dirname, '../config/_eslintignore.ejs');
must change to
lintConfig.ignorePath = path.resolve(__dirname, '../../config/_eslintignore.ejs');

in file: getESLintConfig.ts
line 43

lint 规则细则没有开源出来 ~

RT ~
目前只能通过触发错误，或翻看 lint 配置，才知道有哪些规则。

typescript 规约在使用 yarn 作为包管理工具时不可用

写了个简单的复现仓库 https://github.com/LucasIcarus/f2elint_test

内网环境下使用 tnpm 是正常的.

但是会影响到使用 yarn workspace 功能的项目

猜测是 eslint-config-egg 依赖了旧版本的 @typescript-eslint/* 系列包导致的.

非阿里 个人项目可以用这个工具吗

非阿里 个人项目可以用这个工具吗？
个人项目使用这个东西 然后提交push仓库的时候提交不上去 显示ip访问不到 个人项目可以使用吗

f2elint 工具对前后端一体化应用的支持

前后端同一个 git 仓库，目录如下，f2e lint commit-file-scan 在不同目录执行时会遇到问题。

1. 根目录执行会拿不到 f2elint 或 eslint 的配置
2. client、server 目录执行，会遇到 commit file 相对路径不正确的问题

目前是用 patch-package 在项目中修正了相对路径。非常期待官方能支持下这种使用场景

.
├── .git
├── client
│   └── .eslintrc.js
└── server
    └── .eslintrc.js

希望可以加入import自动排序

"editor.codeActionsOnSave": {
"source.sortImports": true
},

这样就可以不用关心import的顺序了~

执行f2elint scan报错

TypeError: Cannot read properties of undefined (reading 'getTokens')

f2elint init 后无法 npm install

TypeScript paths 映射导致循环引用检查失效

ICE 默认配置了把 src/* 映射到 @/* ，但是这样循环引用检查就不生效了：

如果改成相对路径 ../ 又可以了：

[f2elint] 可通过函数调用使用

目前是直接对目录下的文件进行格式化操作和检查，希望增加函数调用的方式。

使用场景：
在低代码引擎转代码时，需要对生成的文件字符串进行格式化和 fix。

f2elint init 失败

步骤如下

f2elint version: 2.2.1
node version : v16.14.2
npm version : 8.5.5
platform： mac 12.3.1

markdownlint 不支持 ignore?

看 eslint 和 stylelint 都已经有了
但这里没有。。
https://github.com/alibaba/f2e-spec/blob/main/packages/f2elint/src/lints/markdownlint.ts#L28

f2elint scan 失败，但是f2elint commit-file-scan成功

我制造了个is not defined 错误，运行 f2elint scan 命令时可以发现错误。提交代码使用"pre-commit": "f2elint commit-file-scan", 时缺通过了校验。详情看图

反引号的处理

实际行为：在 JS/TS 中（启用了 Prettier），字符串的双引号会被自动修正为单引号，但是一些不必要的反引号则不会被处理：

预期行为：不必要的反引号，也会被自动修正为单引号：

ESLint 的 quotes 规则似乎存在实现问题 eslint/eslint#12156

bundleDependencies 需要替换为 bundledDependencies

因为 bundleDependencies 已经被标记为 DEPRECATED，需要替换为 bundledDependencies。

目前 f2elint init 的时候会默认将 bundledDependencies 转换为 bundleDependencies，这是不对的

f2elint scan 没有报错但是命令行返回码是失败

如下图，只有 4 个 warning 但是命令状态那里却有个❌，不知道是什么问题。

Vue项目执行 f2elint fix 时报的错误

commitlint 无正常生效

项目 f2elint init 后，git commit -m 1，可以正常提交。lint 未拦截

npm包缺少markdownlint-config-ali 文件

1. 安装f2eslint 并初始化项目，然后运行f2eslint fix
2. 报错未找到 node_modules\f2elint\node_modules\markdownlint-config-ali\index.json
3. 目前只能单独安装markdownlint-config-ali