前端工程化之项目搭建初始化指南

目录
文章目录隐藏
  1. 一、项目初始化及配置
  2. 二、规范代码与提交

本系列是一个从 0 到 1 的实现过程,如果您有耐心跟着实现,您可以实现一个完整的react18 + ts5 + webpack5 + 代码质量&代码风格检测&自动修复 + storybook8 + rollup + git action实现的一个完整的组件库模板项目。

在你阅读完本文后你将会学到:

  • 一个标准化的项目初始化、代码规范、提交规范的配置流程;
  • eslint、stylelint 及 prettier 的配置&自动保存修复;
  • 代码提交规范的第三方工具强制约束方式实现;
  • 自定义可视化的代码提交规范。

一、项目初始化及配置

package.json

package.json 是基于 Node.js 生态系统的任何项目(尤其是前端项目)的核心文件之一。它在项目中扮演了多个重要角色:

  • 项目元数据(Metadata): 它包含了项目的元数据,如项目名称、版本、描述、作者、许可证等。
  • 依赖管理(Dependency Management): 它列出了项目所依赖的 npm 包及其版本,这包括 dependencies 和 devDependencies 等。
  • 脚本(Scripts): scripts 字段允许定义可以通过 npm run 命令执行的脚本,使得启动、构建、测试和部署等操作可以自动化。
  • 版本控制(Version control): 通过 version 字段指定,可以帮助管理项目的发布和版本控制。
  • 配置平台(Platform Config): 它可以指明项目运行所需的 Node.js 或 npm 版本,有助于确保一致的开发环境。
yarn init -y
{
  "name": "lint_demo",
  "version": "1.0.0",
  "description": "a lint demo ",
  "main": "dist/boundle.js",
  "author": "xxx",
  "license": "MIT",
  "private": false
}

LICENSE

LICENSE 文件是指软件项目中包含的许可证文件,用于规定该软件在何种条件下可以被使用、复制、修改和分发。LICENSE 文件通常包含了开源许可证的全文或摘要,以及适用该许可证的条款和条件。在开源软件项目中,LICENSE 文件是非常重要的,它定义了开发者和用户之间的权利和责任,确保了代码的合法使用和共享。

常见的开源许可证包括 MIT 许可证、GNU 通用公共许可证(GPL)、Apache 许可证等。每种许可证都有不同的要求和限制,开发者在选择和使用许可证时需要仔细考虑项目的需求和目标。

可以在choosealicense网站选择一个合适的

.gitignore

.gitignore文件是用来指定哪些文件或目录不应该被 Git 版本控制系统跟踪的配置文件。在项目中,有些文件(如编译生成的文件、日志文件、临时文件等)不应该被包含在版本控制中,因为它们可能包含敏感信息、过时的内容或者不必要的文件。通过.gitignore 文件,可以告诉 Git 哪些文件应该被忽略,不会被提交到代码仓库中。

使用 vscode 的 gitignore 插件,下载安装该插件之后, ctrl+shift+p 召唤命令面板,输入 Add gitignore 命令,即可在输入框输入系统或编辑器名字,来自动添加需要忽略的文件或文件夹至 .gitignore 中。

.npmrc | .yarnrc

npmrcyarnrc 是两个配置文件,用于配置 npm 和 Yarn 包管理器的行为和设置。它们分别用于配置 npm 和 Yarn 的命令行工具的行为,例如设置镜像源、代理、缓存路径等。

npmrc

npmrc 是 npm 的配置文件,通常是 .npmrc 文件。你可以在项目级别或全局级别创建 .npmrc 文件来配置 npm 的行为。

配置方式:

  1. 项目级别配置: 在项目根目录下创建 .npmrc 文件,并添加所需配置。
  2. 全局级别配置: 使用命令 npm config edit 打开全局配置文件,并添加所需配置。

常见配置项:

  • registry:设置包的下载源。
  • proxyhttps-proxy:设置代理服务器。
  • cache:设置包的缓存路径。
  • prefix:设置全局安装包的路径。
  • strict-ssl:是否强制使用 SSL。

示例:

# .npmrc

# 设置下载源为淘宝镜像,淘宝证书到期了,换了
registry=https://registry.npm.taobao.org/

# 设置代理服务器
proxy=http://proxy.example.com:8080
https-proxy=http://proxy.example.com:8080

# 设置包的缓存路径
cache=/path/to/npm-cache

# 设置全局安装包的路径
prefix=/path/to/npm-global

yarnrc

yarnrc 是 Yarn 的配置文件,通常是 .yarnrc.yarnrc.yml 文件。你可以在项目级别或全局级别创建 .yarnrc 文件来配置 Yarn 的行为。

配置方式:

  1. 项目级别配置: 在项目根目录下创建 .yarnrc 文件,并添加所需配置。
  2. 全局级别配置: 使用命令 yarn config set 添加全局配置。

常见配置项:

  • registry:设置包的下载源。
  • proxyhttps-proxy:设置代理服务器。
  • cache-folder:设置包的缓存路径。
  • preferred-cache-folder:设置首选缓存路径。
  • nodeLinker:设置 Node 模块链接器。

示例:

# .yarnrc

# 设置下载源为淘宝镜像,淘宝证书到期了,换了
registry "https://registry.npm.taobao.org/"

# 设置代理服务器
proxy "http://proxy.example.com:8080"
https-proxy "http://proxy.example.com:8080"

# 设置包的缓存路径
cache-folder "/path/to/yarn-cache"

# 设置首选缓存路径
preferred-cache-folder "/path/to/preferred-cache"

配置文件中的每一行都应该是一个配置项,以 key value 的格式表示。你可以根据需要添加或修改这些配置项来定制 npm 和 Yarn 的行为。

README.md

README.md 文件通常是一个项目的说明文档,用于向其他开发者或用户介绍项目的内容、使用方法、贡献指南等信息。.md 代表 Markdown 格式,Markdown 是一种轻量级的标记语言,用于简单地排版文档。

README.md 文件通常包含以下内容:

  • 项目名称和简介:简要介绍项目的名称、功能和用途。
  • 安装说明:指导用户如何安装项目的依赖或部署项目。
  • 使用方法:说明如何使用项目,包括配置、运行命令等。
  • 示例:提供一些示例代码或截图,展示项目的功能。
  • 贡献指南:说明如何贡献代码或报告问题。
  • 版本历史:列出项目的版本历史和更新内容。
  • 许可证信息:说明项目的许可证类型和使用限制。

二、规范代码与提交

代码规范

EditorConfig

EditorConfig

.editorconfig 文件是用来帮助开发人员在不同的编辑器和 IDE 中保持一致的代码风格和格式的配置文件。它可以定义一些基本的编辑器设置,如缩进风格、换行符类型、字符编码等,以确保团队成员在不同的编辑器中编写的代码具有一致的风格。

.editorconfig 文件的语法很简单,通常由一系列键值对组成,每个键值对表示一项编辑器配置。以下是一个示例.editorconfig 文件的内容:

# EditorConfig 文件示例

# 表示这是项目根目录下的顶级 .editorconfig 文件,编辑器在查找配置时会停止向上查找
root = true

# 匹配所有文件
[*]
# 使用 Unix 风格的换行符
end_of_line = lf
# 文件末尾会插入一个空行
insert_final_newline = true

# 匹配 JavaScript 文件
[*.js]
# 使用空格缩进
indent_style = space
# 缩进大小为 4
indent_size = 4

# 匹配 Markdown 文件
[*.md]
# 使用制表符缩进
indent_style = tab

常见配置项 .editorconfig 文件支持的配置项有很多,常见的包括:

  • root:是否是项目根目录下的顶级 .editorconfig 文件。
  • indent_style:缩进风格,可以是 tab(制表符)或 space(空格)。
  • indent_size:缩进大小,对于 tab 缩进风格无效。
  • tab_width:制表符宽度,用于 tab 缩进风格。
  • end_of_line:换行符类型,可以是 lf(Unix 风格)、crlf(Windows 风格)或 cr(旧版 Mac 风格)。
  • charset:字符编码,通常设置为 utf-8。
  • trim_trailing_whitespace:是否去除行末多余的空格。
  • insert_final_newline:文件末尾是否插入空行。 以上是一些常见的配置项,具体可以根据项目需要进行配置。详细的配置项列表和说明可以参考 EditorConfig 官方文档。

这里解释下空格为什么需要统一,为什么有几种风格? 换行符类型的不同风格主要是由于不同操作系统对换行符的处理方式不同所导致的。

LF(Line Feed):在 Unix 和类 Unix 系统(如 Linux、macOS、FreeBSD 等)中使用的换行符。在文本文件中,每行结尾只有 LF 字符。

CRLF(Carriage Return + Line Feed):在 Windows 系统中使用的换行符。在文本文件中,每行结尾有 CR 和 LF 两个字符组成。

CR(Carriage Return):在旧版 Mac 系统中使用的换行符。在文本文件中,每行结尾只有 CR 字符。

这些不同的换行符类型源于早期计算机系统中不同的文本处理方式,如今在不同的操作系统和文本编辑器中仍然会存在这些差异。因此,.editorconfig 文件中的 end_of_line 配置选项允许你指定在项目中使用的换行符类型,以便在不同的环境中保持一致的换行符风格。

如果在一个项目中不同的文件使用了不同的换行符类型,可能会导致一些问题,主要包括:

  • 跨平台兼容性问题:不同的操作系统对换行符的处理方式不同,如果文件中混合使用了不同的换行符类型,可能会导致在不同操作系统下的编辑器或工具处理文件时出现问题,如显示异常或解析错误。
  • 版本控制问题:版本控制系统(如 Git)可能会在提交和比较文件时将换行符转换为统一的格式,如果文件中混合使用了不同的换行符类型,可能会导致版本控制系统不正确地处理换行符,导致代码冲突或历史记录混乱。
  • 可读性问题:混合使用不同的换行符类型会使代码在不同的编辑器或工具中显示不一致,降低代码的可读性和维护性。

Prettier

Prettier

Prettier 是一个代码格式化工具,可以帮助开发人员自动格式化代码,使代码风格保持一致。它支持多种编程语言,包括 JavaScript、TypeScript、CSS、HTML、JSON 等。Prettier 的主要目标是通过提供一致的代码格式化规则来减少团队成员之间的代码格式争论,并提高代码的可读性和可维护性。

使用 Prettier 的优点包括:

  • 一致的代码风格:Prettier 提供了一套默认的代码格式化规则,确保团队成员的代码风格保持一致,避免了手动调整代码格式的工作。
  • 易于集成:Prettier 可以与大多数编辑器、集成开发环境(IDE)、代码编辑器和版本控制系统(如 VS Code、Atom、Sublime Text、WebStorm、Git 等)无缝集成,方便开发人员在编写代码时自动格式化。
  • 广泛的支持:Prettier 支持多种编程语言和文件格式,包括 JavaScript、TypeScript、CSS、HTML、JSON、Markdown 等,可以统一管理项目中不同类型文件的代码格式。
  • 易于配置:Prettier 提供了一些配置选项,可以根据项目的需要进行定制,例如缩进大小、换行符类型等。
  • 强大的格式化功能:Prettier 能够处理复杂的代码结构,并根据配置规则自动调整代码格式,确保生成的代码符合一致的风格。
  • 使用 Prettier 可以提高团队的开发效率,减少代码格式化方面的工作量,使开发人员可以更专注于编写高质量的代码。

安装

yarn add prettier@3.2.5 -D

安装成功之后在根目录新建文件 .prettierrc,在prettier playground尝试配置然后复制到文件中即可

新建文件 .prettierrc

{
  // 箭头函数参数周围加上括号
  "arrowParens": "always",
  // 大括号与代码在同一行
  "bracketSameLine": true,
  // 大括号内部不加空格
  "bracketSpacing": false,
  // 分号结尾
  "semi": true,
  // 不使用实验性三元表达式
  "experimentalTernaries": false,
  // 使用单引号
  "singleQuote": true,
  // JSX 属性值使用单引号
  "jsxSingleQuote": true,
  // 保留引号样式
  "quoteProps": "preserve",
  // 尾随逗号保留
  "trailingComma": "all",
  // 不强制单个属性换行
  "singleAttributePerLine": false,
  // HTML 空格敏感性为 css
  "htmlWhitespaceSensitivity": "css",
  // Vue 脚本和样式不缩进
  "vueIndentScriptAndStyle": false,
  // 文本不换行
  "proseWrap": "never",
  // 不插入格式化标记
  "insertPragma": false,
  // 打印宽度为 80 个字符
  "printWidth": 80,
  // 不要求格式化标记
  "requirePragma": false,
  // 使用 Tab 缩进
  "useTabs": true,
  // 嵌入语言格式自动
  "embeddedLanguageFormatting": "auto",
  // Tab 宽度为 4 个空格
  "tabWidth": 4
}

配置保存自动格式化

先安装 vscode 的插件,然后再创建一个.vscode 文件夹。 .vscode 文件夹是用来存放 Visual Studio Code (VS Code)编辑器的工作区配置文件的目录。这些配置文件包含了与项目相关的编辑器设置,例如调试配置、任务配置、工作区设置等。这些设置可以使得多个开发人员在同一个项目中使用相同的编辑器配置,以确保项目的一致性和可维护性。该文件的配置优先于 vscode 全局的 settings.json ,这样别人下载了你的项目进行开发,也不会因为全局 setting.json 的配置不同而导致 Prettier 或之后会说到的 ESLint 、 StyleLint 失效,接下来在该文件内输入以下代码:

{
	// =======================下面是配置 prettier 格式化的 setting===================
	// 指定哪些文件不参与搜索
	"search.exclude": {
	  "**/node_modules": true,
	  "dist": true,
	  "build": true,
	  "yarn.lock": true
	},
	// 保存自动格式化
	"editor.formatOnSave": true,
	"[javascript]": {
	  "editor.defaultFormatter": "esbenp.prettier-vscode"
	},
	"[javascriptreact]": {
	  "editor.defaultFormatter": "esbenp.prettier-vscode"
	},
	"[typescript]": {
	  "editor.defaultFormatter": "esbenp.prettier-vscode"
	},
	"[typescriptreact]": {
	  "editor.defaultFormatter": "esbenp.prettier-vscode"
	},
	"[json]": {
	  "editor.defaultFormatter": "esbenp.prettier-vscode"
	},
	"[html]": {
	  "editor.defaultFormatter": "esbenp.prettier-vscode"
	},
	"[markdown]": {
	  "editor.defaultFormatter": "esbenp.prettier-vscode"
	},
	"[css]": {
	  "editor.defaultFormatter": "esbenp.prettier-vscode"
	},
	"[less]": {
	  "editor.defaultFormatter": "esbenp.prettier-vscode"
	},
	"[scss]": {
	  "editor.defaultFormatter": "esbenp.prettier-vscode"
	},
  
	// ==========================prettier===============================
  }

“editor.formatOnSave” 的作用是在我们保存时,会自动执行一次代码格式化,而我们该使用什么格式化器?接下来的代码便是设置默认的格式化器,看名字大家也能看得出来了吧!

在遇到 .js 、 .jsx 、.ts 、.tsx 、.json 、.html 、.md 、 .css 、 .less 、 .scss 为后缀的文件时,都会去使用 Prettier 去格式化代码,而格式化的规则就是我们配置的 .prettierrc 决定的!

prettier&editorConfig 的区别

EditorConfig 的配置项都是一些不涉及具体语法的,比如 缩进大小、文移除多余空格等。

而 Prettier 是一个格式化工具,要根据具体语法格式化,对于不同的语法用单引号还是双引号,加不加分号,哪里换行等,当然,肯定也有缩进大小。

即使缩进大小这些共同都有的设置,两者也是不冲突的,设置 EditorConfig 的 indent_size 为 4 , Prettier 的 tabWidth 为 2 。

.prettierignore

忽略格式化的文件

代码质量

ESLint

ESLint 是一个用于 JavaScript 代码的静态代码分析工具,它可以帮助开发人员发现和修复代码中的问题,确保代码的质量和一致性。ESLint 可以检查代码中的语法错误、代码风格问题以及可能的逻辑错误。

ESLint 的工作原理是通过解析 JavaScript 代码并应用一系列的规则来检查代码。这些规则可以根据项目的需要进行配置,以满足不同团队或项目的编码标准。

ESLint 的特点包括:

  • 可配置性:ESLint 的规则可以根据项目的需要进行配置,包括启用、禁用规则,以及设置规则的严格程度。
  • 插件化:ESLint 支持通过插件扩展其功能,可以选择性地添加额外的规则或功能。
  • 自动化:ESLint 可以集成到开发工具中,如编辑器或构建工具,以便在编写代码时自动进行检查。
  • 错误报告:ESLint 可以生成详细的错误报告,包括错误的位置、规则名称和修复建议,以帮助开发人员快速定位和解决问题。

在上面我们配置了 EditorConfig 和 Prettier 都是为了解决代码风格问题,而 ESLint 是主要为了解决代码质量问题,它能在我们编写代码时就检测出程序可能出现的隐性 BUG,通过 eslint –fix 还能自动修复一些代码写法问题,比如你定义了 var a = 3 ,自动修复后为 const a = 3 。还有许多类似的强制扭转代码最佳写法的规则,在无法自动修复时,会给出红线提示,强迫开发人员为其寻求更好的解决方案。

安装

yarn add eslint@8.0.1 -D

初始化配置文件

npx eslint --init

会问这几个问题:

ESLint 初始化配置问题

配置完成之后之前的 js 文件会报一个这样的错,这是因为我们创建的时候选择了使用typescript,接下来我们先配置下 ts。

配置下 ts

提前安装 ts 并配置文件

转到 ts 目录去看

生成的配置.eslintrc.js 文件,配置如下:

module.exports = {
    "env": {
        "browser": true,
        "es2021": true,
        "node": true
    },
    "extends": [
        "standard-with-typescript",
        "plugin:react/recommended"
    ],
    "overrides": [
        {
            "env": {
                "node": true
            },
            "files": [
                ".eslintrc.{js,cjs}"
            ],
            "parserOptions": {
                "sourceType": "script"
            }
        }
    ],
    "parserOptions": {
        "ecmaVersion": "latest",
        "sourceType": "module"
    },
    "plugins": [
        "react"
    ],
    "rules": {
    }
}

ESLint 8 中一些常用的配置选项包括:

  • extends:用于扩展已有的配置,可以继承一些已经存在的配置文件,如”eslint:recommended”、”airbnb”等。
  • parser:指定要使用的解析器,如 Babel、Typescript 等。
  • parserOptions:用于配置解析器的选项,例如 ecmaVersion、sourceType 等。
  • env:定义代码执行的环境,比如 browser、node 等。
  • plugins:插件列表,可以加入一些自定义规则。
  • rules:规则配置,用于设定规则的严格程度,如”error”、”warn”、”off”。
  • globals:定义全局变量。
  • ignorePatterns:指定要忽略的文件路径模式。
  • reportUnusedDisableDirectives:指定是否要报告未使用的 ESLint 禁用规则注释。
  • fixTypes:配置用于执行自动修复的文件类型。
  • supersededConfigs:用于指示配置文件是否被后续配置所取代。
  • noInlineConfig:指示是否允许内联配置。
  • allowInlineConfig:控制是否允许在注释内配置规则。 但是我们发现这个配置文件有一个报错,是因为 eslint 检测了 js 文件

安装一下:

yarn add @typescript-eslint/parser@7.2.0 -D
yarn add @typescript-eslint/eslint-plugin@6.4.0 -D
yarn add @typescript-eslint/parser@7.2.0 -D
yarn add @typescript-eslint/eslint-plugin@6.4.0 -D

我们来更改一下 eslint 的配置,更改后的配置如下:

const OFF = 0;
const WARN = 1;
const ERROR = 2;

module.exports = {
	env: {
		browser: true,
		es2021: true,
		node: true,
	},
	extends: ['standard-with-typescript', 'plugin:react/recommended'],
	settings: {
		'react': {
			'version': 'detect', // 自动检测 React 版本
		},
		// 这个配置是用于指定模块导入解析器的配置,主要用于告诉 ESLint 如何解析模块导入语句
		'import/resolver': {
			// node:指定了使用 Node.js 解析模块导入语句的配置。在这里,配置了支持的文件扩展名,包括 .tsx、.ts、.js 和 .json。
			node: {
				extensions: ['.tsx', '.ts', '.js', '.json'],
			},
			// typescript:指定了使用 TypeScript 解析模块导入语句的配置。这个配置为空对象,表示使用默认配置。
			typescript: {},
		},
	},
	overrides: [
		// 检测 ts 和 tsx,注意 files 要包括文件,否则会报错
		{
			files: ['./src/**/*.ts', './src/**/*.tsx'],
			parser: '@typescript-eslint/parser',
			parserOptions: {
				sourceType: 'module',
				project: './tsconfig.json', // 指定 TypeScript 配置文件
			},
		},
		// 不检测 js 文件的类型, 有 ignorePatterns 就不需要了
		{
			extends: ['plugin:@typescript-eslint/disable-type-checked'],
			files: ['./**/*.js'],
		},
	],
	plugins: ['react'],
	rules: {
		// 对象的最后一个可以增加【,】
		'@typescript-eslint/comma-dangle': OFF,
		// 单引号关闭
		'@typescript-eslint/quotes': OFF,
		// 需要分号
		'@typescript-eslint/semi': OFF,
		// 不允许使用 var
		'no-var': ERROR,
		// 函数不需要 ts 标注返回类型
		'@typescript-eslint/explicit-function-return-type': OFF,
		'no-tabs': OFF,
		'@typescript-eslint/indent': OFF,
	},
	// 忽略文件
	ignorePatterns: [
		'/lib/**/*', // Ignore built files.
		'**/*.js',
	],
};

这样配置完成之后就不会检测 js 文件了,但是这时候我们发现我们配置了不适用 var,但是 ts 文件中竟然没有报错:

ts 文件

这时候可以看一下 eslint 插件的输出,看看插件是否报错,对于其他的插件的配置也可以使用一样的方法去检测配置是否正确

eslint 插件的输出

我们看到一个报错,说的是,这里../错了,我们多输入了一个.,导致路劲不对,删除即可:

删除路径

更改后的配置:

更改后的配置

这样更改完成之后,ts 文件的报错就恢复了。

ts 文件的报错

配置保存自动修复

安装 eslint 插件

安装 eslint 插件

再到之前创建的 .vscode/settings.json 中添加以下代码:

// ========================eslint===================================
  "eslint.validate": ["javascript", "javascriptreact", "typescript", "typescriptreact"],
  "typescript.tsdk": "./node_modules/typescript/lib", // 代替 vscode 的 ts 语法智能提示
  // 保存自动修复
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit",
  },
  // =================================================================

配置完整之后最好重启一下 vscode,否自动修复不一定生效。

配置完整之后最好重启一下 vscode

这里还有一个报错是因为我们配置的 prettier 和 eslint 冲突了,我们使用 tabs 作为缩进风格,但是 eslint 中的导入配置中有 no-tabs,我们去配置一下,这样就 OK 了

配置的 prettier 和 eslint 冲突

配置忽略文件.eslintignore 和 .prettierignore

一般保持一致就行了。

/node_modules
/build
/dist

StyleLint

StyleLint 是一个强大的工具,用于在代码中发现并报告样式代码中的问题。它可以帮助团队保持一致的代码风格,并避免常见的错误。StyleLint 支持多种样式语言,包括 CSS、SCSS、Less 等,可以检查各种规则,如缩进、空格、命名约定等。它还支持自定义规则,以便根据团队的具体需求进行配置。

要开始使用 StyleLint,首先需要安装 StyleLint 包,然后在项目中配置一个 .stylelintrc 文件来指定检查规则。可以通过命令行工具或与构建过程集成来运行 StyleLint。当 StyleLint 检测到问题时,它会生成报告,其中包含有关问题的详细信息和建议的修复方法。

安装

yarn add stylelint@16.2.1 stylelint-config-standard@36.0.0 -D

增加.stylelintrc.js 配置文件

module.exports = {
	// 从标准配置中继承规则
	extends: ['stylelint-config-standard'],
  
	// 规则配置
	rules: {
	  // 禁用注释前的空行规则
	  'comment-empty-line-before': null,
	  // 禁用声明前的空行规则
	  'declaration-empty-line-before': null,
	  // 指定函数名的大小写为小写
	  'function-name-case': 'lower',
	  // 禁用选择器特异性递减规则
	  'no-descending-specificity': null,
	  // 禁用无效的双斜杠注释规则
	  'no-invalid-double-slash-comments': null,
	  // 指定规则前需要空行
	  'rule-empty-line-before': 'always',
	},
  
	// 忽略检查的文件或文件夹
	ignoreFiles: ['node_modules/**/*', 'build/**/*'],
  };
  • extends:可以从已有的 StyleLint 配置中继承规则。这样可以避免重复定义相同的规则集。例如,”extends”: “stylelint-config-standard” 将从标准配置中继承规则。
  • plugins:用于指定要使用的 StyleLint 插件。插件可以添加额外的规则或功能。例如,”plugins”: [“stylelint-scss”] 将启用 SCSS 相关的规则和功能。
  • rules:指定项目中的规则配置。可以根据项目需求启用、禁用或修改规则。例如,”rules”: { “indentation”: “tab”, “selector-pseudo-class-no-unknown”: [true, { “ignorePseudoClasses”: [“global”] }] } 将规定使用制表符缩进,并忽略全局伪类的未知类规则。
  • ignoreFiles:指定 StyleLint 忽略检查的文件或文件夹。可以使用 glob 模式匹配多个文件或文件夹。例如,”ignoreFiles”: [“node_modules/”, “**/*.min.css”] 将忽略 node_modules 文件夹和所有.min.css 文件。

配置保存自动修复

安装 stylelint 插件

安装 stylelint 插件

并且在 .vscode/settings.json 中增加以下代码:

// ========================stylelint==============================
  // 使用 stylelint 自身的校验即可, 关闭 vscode 验证
  "css.validate": false,
  "less.validate": false,
  "scss.validate": false,
  "stylelint.validate": ["css", "less", "sass", "scss"]
  // 在 editor.codeActionsOnSave 中增加 styleLint 修复
  
  // 保存自动修复
  "editor.codeActionsOnSave": {
    "source.fixAll.stylelint": "explicit"
  },
// ===============================================================

这时候新建一个 less 文件,就已经显示报错提示了。

less 文件

保存也可以自动修复了。

配置根据分组排序

就是配置这个总是不生效,我还以为配置出错了,重启 vscode!!!,重启 vscode!!!重启 vscode!!!,

yarn add stylelint-config-rational-order@0.1.2 -D

会按照如下属性进行分组排序:

1.Positioning   2.Box Model    3.Typography    4.Visual    5.Animation    6.Misc

提示我们写的矛盾样式

stylelint-declaration-block-no-ignored-properties 用于提示我们写的矛盾样式,比如下面的代码中 width 是会被浏览器忽略的,这可以避免我们犯一些低级错误~

yarn add stylelint-declaration-block-no-ignored-properties@2.8.0 -D

lint 文件中配置

// .stylelintrc
{
  "plugins": ["stylelint-declaration-block-no-ignored-properties"],
  "rules": {
    "plugin/declaration-block-no-ignored-properties": true
  }
}

重启、重启、重启!!!重要事情说三遍。

lint 文件中配置

ESLint、Stylelint 和 Prettier 的冲突

有时候 eslint 和 stylelint 的自定义规则和 prettier 定义的规则冲突了,比如在 .eslintrc.js 中某个 extends 的配置设置了缩进大小为 4 ,但是我 .prettierrc 中我设置的缩进为 2 ,那就会出现我们保存时,先是 eslint 的自动修复缩进大小为 4 ,但是保存的时候 prettier 又给他格式化回去了,eslint 就直接报错。在上面的时候我们遇到过一个使用 tab 的报错,但是我们是手动的去禁用掉这个规则,现在我们可以通过配置插件解决这个问题。

eslint 冲突

安装插件 eslint-config-prettier ,这个插件会禁用所有和 prettier 起冲突的规则:

yarn add eslint-config-prettier@9.1.0 -D

添加以下配置到 .eslintrc.js 的 extends 中:

extends: ['standard-with-typescript', 'plugin:react/recommended', 'prettier'],

这里需要注意, ‘prettier’ 及之后的配置要放到原来添加的配置的后面,这样才能让 prettier 禁用之后与其冲突的规则。

stylelint 冲突

stylelint 的冲突解决也是一样的,先安装插件 stylelint-config-prettier :

yarn add stylelint-config-prettier@9.0.5 -D
yarn add stylelint-prettier@5.0.0 -D

添加配置

// 从标准配置中继承规则
	extends: [
		'stylelint-config-standard',
		'stylelint-config-rational-order',
		'prettier',
	],
    
  plugins: [
    'stylelint-declaration-block-no-ignored-properties',
    'stylelint-prettier'
  ],

增加 lint 命令

"lint": "npm run lint-eslint && npm run lint-stylelint",
		"lint-eslint": "eslint -c .eslintrc.js --ext .ts,.tsx,.js src",
		"lint-stylelint": "stylelint --config .stylelintrc.js src/**/*.{less,css,scss}"

lint-staged&husky

lint-staged

lint-staged 是一个在提交代码之前运行 linter 或其他工具的工具。这意味着当开发人员尝试提交代码到版本控制系统(如 git)时,lint-staged 会只对暂存区(staged files)的文件运行配置的命令,这通常是代码风格检查器(如 ESLint、Prettier)、代码格式化工具或测试套件。

使用 lint-staged 可以确保只有符合项目规定代码质量标准的代码被提交,减少了不必要的错误和风格问题被引入代码库的可能性。

在一个项目中使用 lint-staged 通常包括以下步骤:

添加 lint-staged 到项目的依赖中。 在 package.json 中配置 lint-staged,指定哪些文件与相对应的校验命令。 提交代码时,lint-staged 会自动运行只对 staged 文件的检查。

husky

husky 是一个用于简化 Git 钩子(hooks)的设置的工具,允许开发者轻松地在各种 Git 事件触发时运行脚本。例如,在提交之前(pre-commit)、推送之前(pre-push)、或者在提交信息被写入后(commit-msg)等。

husky 的使用可以提高项目团队的工作效率,确保代码库中的代码符合特定的质量标准。它通常与 lint-staged 一起使用,以在提交前自动执行代码的静态检查。

使用 husky 包括以下简单步骤:

添加 husky 到项目依赖。 配置 Git 钩子,使用 husky 的配置。 当相应的 Git 事件被触发时,定义的脚本就会自动执行。

安装

yarn add husky@9.0.11 lint-staged@15.2.2 -D

启用 husky,执行如下命令会自动在 package 中增加命令:

npx husky install

husky prepare 命令,自动加入,有时候也没法自动加入,手动写也是可以的。

{
  "scripts": {
    "prepare": "husky install"
  }
}

在 package.json 中添加以下代码:

{
	"husky": {
    "hooks": {
      "pre-commit": "lint-staged",
    }
  },
  "lint-staged": {
    "*.{ts,tsx,js}": [
      "eslint --config .eslintrc.js"
    ],
    "*.{css,less,scss}": [
      "stylelint --config .stylelintrc.js"
    ],
    "*.{ts,tsx,js,json,html,yml,css,less,scss,md}": [
      "prettier --write"
    ]
  },
}

修改.husky/pre-commit 脚本的内容,将.husky/pre-commit 脚本的内容改为 npm run lint-staged。

npm run lint-staged
通过上面的步骤,就完成了 lint-staged 的配置,这个时候再进行 git 提交时,将只检查暂存区(staged)的文件,不会检查项目所有文件,加快了每次提交 lint 检查的速度,同时也不会被历史遗留问题影响。通过这样的约束让我们定义的规则规范大家都能去遵守,共同维护代码的质量。

lint-staged 的配置

commitlint

配置提交校验,commitlint 可以帮助我们进行 git commit 时的 message 格式是否符合规范。

yarn add @commitlint/cli@19.2.0 @commitlint/config-conventional@19.1.0 -D

@commitlint/config-conventional 这是一个规范配置,标识采用什么规范来执行消息校验, 这个默认是 Angular 的提交规范。

新增配置文件.commitlintrc.js:

module.exports = {
	extends: ['@commitlint/config-conventional'],
	rules: {
		'type-enum': [
			2,
			'always',
			[
				'build',
				'ci',
				'chore',
				'docs',
				'feat',
				'fix',
				'perf',
				'refactor',
				'revert',
				'style',
				'test',
				'addLog',
			],
		],
	},
};

随后回到 package.json 的 husky 配置,增加一个钩子,并且改写 husky 的 commit-msg 钩子:

commit-msg 钩子

"husky": {
		"hooks": {
			"pre-commit": "lint-staged",
			"commit-msg": "commitlint --config .commitlintrc.js -E HUSKY_GIT_PARAMS"
		}
	},

效果如下:

commitlint 配置后效果

配置可视化的提交提示

yarn add commitizen@4.3.0 cz-conventional-changelog@3.3.0 -D

在 pageage.json 中增加更改 commitizen 的配置,并增加脚本:

"config":{
    "commitizen":{
        "path":"node_modules/cz-conventional-changelog"
    }
}

"scripts":{
    commit:"git-cz"
}

配置可视化的提交提示

配置自定义提交规范

yarn add cz-customizable@7.0.0 commitlint-config-cz@0.13.3 -D

变更 commitlint.config.js 这里采用自己定义的规范,将会覆盖上面那个,所以上面那个可以不用安装。

module.exports = {
	extends: ['cz'],
	rules: {},
};

增加 .cz-config.js:

'use strict';
module.exports = {
	types: [
		{value: 'feat', name: '✨新增:    新的内容'},
		{value: 'fix', name: '🐛修复:    修复一个 Bug'},
		{value: 'docs', name: '📝文档:    变更的只有文档'},
		{value: 'style', name: '💄格式:    空格, 分号等格式修复'},
		{value: 'refactor', name: '️♻️重构:    代码重构,注意和特性、修复区分开'},
		{value: 'perf', name: '️️⚡️性能:    提升性能'},
		{value: 'test', name: '✅测试:    添加一个测试'},
		{value: 'build', name: '🔧工具:    开发工具变动(构建、脚手架工具等)'},
		{value: 'rollback', name: '⏪回滚:    代码回退'},
		{value: 'addLog', name: '👨🏻‍💻添加 log:    代码回退'},
	],
	scopes: [
		{name: 'leetcode'},
		{name: 'javascript'},
		{name: 'typescript'},
		{name: 'Vue'},
		{name: 'node'},
	],
	// it needs to match the value for field type. Eg.: 'fix'
	/*  scopeOverrides: {
	fix: [
	  {name: 'merge'},
	  {name: 'style'},
	  {name: 'e2eTest'},
	  {name: 'unitTest'}
	]
  },  */
	// override the messages, defaults are as follows
	messages: {
		type: '选择一种你的提交类型:',
		scope: '选择一个 scope (可选):',
		// used if allowCustomScopes is true
		customScope: 'Denote the SCOPE of this change:',
		subject: '短说明:\n',
		body: '长说明,使用"|"换行(可选):\n',
		breaking: '非兼容性说明 (可选):\n',
		footer: '关联关闭的 issue,例如:#31, #34(可选):\n',
		confirmCommit: '确定提交说明?(yes/no)',
	},
	allowCustomScopes: true,
	allowBreakingChanges: ['特性', '修复'],
	// limit subject length
	subjectLimit: 100,
};

package.json 中,将原来 commit 配置变更为自定义配置:

"config": {
		"commitizen": {
			"path": "node_modules/cz-customizable"
		}
	}

commit 配置

配置使用 git commit 走自定义配置

更改 husky 的 prepare-commit-msg 钩子,如下:

#!/bin/bash
exec < /dev/tty && node_modules/.bin/cz --hook || true

配置使用 git commit 走自定义配置

typescript

安装

yarn add typescript@5.4.2 -D

初始化配置文件

npx tsc --init

typescript 初始化配置

更改配置文件的内容如下,然后重启 vscode,因为有时候抽风,vscode 需要重新构建依赖树和缓存,所以重启之后这个报错就消失了。

{
  "compilerOptions": {
    // 基本配置
    "target": "ES5", // 编译成哪个版本的 es
    "module": "ESNext", // 指定生成哪个模块系统代码
    "lib": ["dom", "dom.iterable", "esnext"], // 编译过程中需要引入的库文件的列表
    "allowJs": true, // 允许编译 js 文件
    "jsx": "react", // 在 .tsx 文件里支持 JSX
    "isolatedModules": true,
    "strict": true, // 启用所有严格类型检查选项

    // 模块解析选项
    "moduleResolution": "node", // 指定模块解析策略
    "esModuleInterop": true, // 支持 CommonJS 和 ES 模块之间的互操作性
    "resolveJsonModule": true, // 支持导入 json 模块
    "baseUrl": "./", // 根路径
    "paths": {
      // 路径映射,与 baseUrl 关联,这个需要跟 webpack 一一对应,我们后面会讲解如何配置&使用
      "@src/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    },

    // 实验性选项
    "experimentalDecorators": true, // 启用实验性的 ES 装饰器
    "emitDecoratorMetadata": true, // 给源码里的装饰器声明加上设计类型元数据

    // 其他选项
    "forceConsistentCasingInFileNames": true, // 禁止对同一个文件的不一致的引用
    "skipLibCheck": true, // 忽略所有的声明文件( *.d.ts)的类型检查
    "allowSyntheticDefaultImports": true, // 允许从没有设置默认导出的模块中默认导入
    "noEmit": true // 只想使用 tsc 的类型检查作为函数时(当其他工具(例如 Babel 实际编译)时)使用它
  },
  "include": [
    "src/**/*" // 这将包括 src 目录下的所有文件
  ]
}

介绍下 tsconfig 常见的配置

在 TypeScript 5 中,tsconfig.json 文件仍然是用来配置 TypeScript 项目编译选项的主要方式。这个文件指定了编译器应遵守的规则和项目的编译上下文。以下是一些常见的配置选项和简短的描述:

compilerOptions: 该对象包含可以用来配置编译器行为的各种选项。

  • target: 设置目标 JavaScript 语言版本。例如,”ES5″, “ES6”, “ES2015”, “ES2020″等。
  • module: 指定生成的代码模块化的方式,如 “CommonJS”, “AMD”, “System”, “UMD”, “ES6”, “ES2015”, “ES2020″等。
  • lib: 指定编译过程中需要包含的库文件的列表,如 [“DOM”, “ES5”, “ScriptHost”, “WebWorker”]。
  • allowJs: 允许编译器编译 JavaScript 文件。
  • checkJs: 允许在 .js 文件中报告错误。
  • jsx: 在.tsx 文件中指定 JSX 代码的生成,常用值有 “React”, “Preserve”。
  • declaration: 生成相应的.d.ts 声明文件。
  • sourceMap: 生成相应的.map 文件,用于调试。
  • outFile: 将所有全局作用域的文件合并到一个输出文件中。
  • outDir: 指定输出文件夹。
  • strict: 启用所有严格类型检查选项。
  • noImplicitAny: 禁止隐含的 any 类型。
  • moduleResolution: 模块解析策略,”Node” 或 “Classic”。
  • baseUrl: 用于解析非相对模块名称的基目录。
  • paths: 一个映射列表,与 baseUrl 一起工作以进行模块重定向。
  • esModuleInterop: 改善了对非 ES 模块的默认导出的兼容。
  • resolveJsonModule: 允许导入.json 文件。
  • noEmit: 不生成输出文件。
  • noEmitOnError: 发生错误时不生成输出文件。
  • skipLibCheck: 跳过对.d.ts 文件的类型检查;对于包含大量声明文件的大型项目,这可以减少编译时间。
  • forceConsistentCasingInFileNames: 确保文件名的大小写一致,以避免在大小写不敏感的文件系统中产生问题。
  • strictNullChecks: 当设置为 true 时,在所有可能为 null 或 undefined 的地方显式检查。
  • strictFunctionTypes: 更严格地检查函数类型的赋值。
  • strictBindCallApply: 对 bind,call 和 apply 方法使用更严格的类型。
  • strictPropertyInitialization: 确保类的每个实例属性都显式初始化。
  • noImplicitThis: 当 this 表达式的值为 any 类型的时候,生成一个错误。
  • alwaysStrict: 在代码中每个文件都应用 JavaScript 的严格模式。
  • noUnusedLocals: 报告未使用的局部变量。
  • noUnusedParameters: 报告未使用的函数参数。
  • noImplicitReturns: 在函数中,如果不是所有路径都有返回值,将报告错误。
  • noFallthroughCasesInSwitch: 防止 switch 语句贯穿(未通过 break 中断)。
  • inlineSourceMap: 生成内联的.map 源映射文件,而不是单独的文件。
  • inlineSources: 将代码与 sourcemap 生成在同一文件中,仅当你设置了 inlineSourceMap 或 sourceMap 选项时才有效。
  • emitDecoratorMetadata: 当使用装饰器时,会为相关的设计类型添加元数据信息。
  • experimentalDecorators: 启用实验性的装饰器支持。
  • removeComments: 从输出文件中移除注释。
  • isolatedModules: 确保每个文件可以安全地独立编译。
  • downlevelIteration: 当目标为低于 ES6 环境时,提供对迭代器的全面支持。
  • preserveConstEnums: 即使使用了 const enum, 枚举也会被保留在生成的代码中。
  • suppressImplicitAnyIndexErrors: 当索引对象时忽略 noImplicitAny 的错误。 include: 这个属性定义了编译器应该包含在编译过程中的文件或文件夹。 exclude: 这个属性定义了编译器应该排除在编译过程之外的文件或文件夹。 extends: 允许配置继承自另一个配置文件。 files: 如果你想显式设置一组文件(而不是整个目录),可以使用此属性。 references: 用于配置项目间的依赖。

「点点赞赏,手留余香」

0

给作者打赏,鼓励TA抓紧创作!

微信微信 支付宝支付宝

还没有人赞赏,快来当第一个赞赏的人吧!

声明:本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系maynote@foxmail.com处理
码云笔记 » 前端工程化之项目搭建初始化指南

发表回复