创建TypeScript代码模板(NVS+Yarn+ESLint+Prettier+Husky)

创建TypeScript代码模板(NVS+Yarn+ESLint+Prettier+Husky) Cui, Richard Chikun
本文笔者将带你在Github代码仓库创建TypeScript代码模板,并集成最新的代码开发工具,如:Node.js版本管理工具NVM for Windows、包管理器Yarn、静态代码检查工具ESLint、代码格式化工具Prettier、Git钩子(Hook)工具Husky等。
安装Visual Studio Code 在开始进行TypeScript开发之前,我们首先需要一个用于TypeScript开发的代码编辑器,类似的产品有VS Code、Atom、Sublime Text、Notepad++等等。我个人还是比较喜欢Visual Studio Code代码编辑器,有很强的代码编辑能力,支持丰富的插件功能。
可以通过以下步骤安装VS Code:

  • 打开浏览器,导航到Visual Studio Code - Code Editing. Redefined
  • 下载最新的稳定版本(Stable)的VS Code编辑器
  • 执行下载的安装文件进入安装导航,整个安装过程简单直接。
  • 启动VS Code编辑器,如果是在命令行状态下,进入你要开发的工程或项目文件夹,通过命令code .就可以加载工程内的所有文件。
创建Github代码仓库 首先我们通过Web页面创建Github代码仓库。
创建GitHub代码仓库(Repository)并:
  • 填写仓库名字(Repository Name),如typescript
  • 填写描述(Description,可选项),如TypeScript source template with modern tools
  • 选择访问级别公开(Public)或私有(Private),如选择Public
  • 勾选添加README.md说明文档
  • 勾选添加.gitignore忽略提交文件列表,并选择Node模板
  • 勾选添加许可,并选择MIT许可(MIT License)。关于如何选择许可类型可参考如何选择开源许可证? - 阮一峰的网络日志,文中决策图可以帮助你快速选择合适的许可类型。
点击创建仓库(Create repository)之后,我们的Github代码仓库就创建出来了。
安装Git for Windows 接下来我们要安装Git将代码仓库克隆(clone)到本地进行开发工作,我们需要到Git for Windows网站,点击页面Download按钮,下载最新的Git for Windows安装程序,如Git-2.35.1.2-64-bit.exe。
双击下载的安装程序执行安装:
  • 勾选Only show new options,并点击Install按钮。
  • 取消勾选View Release Notes并点击Finish按钮结束安装。
通过命令行命令git --version显示安装的Git版本并检查Git是否成功安装,成功安装后控制台会返回Git的版本号,如:
git version 2.35.1.windows.2

克隆代码仓库到本地
  1. 打开浏览器跳转到我们刚刚创建的代码仓库页面,如: https://github.com/richardcuick/typescript。
  2. 点击Code按钮,复制HTTPS标签下面的代码仓库地址,如:https://github.com/richardcuick/typescript.git。
  3. 打开命令行,进入我们要创建代码仓库的目录,如@richardcuick
  4. 使用命令git clone <代码仓库地址>复制代码仓库到本地
  5. 进入复制的代码仓库目录,会看到如下文件:
  • .gitignore
  • LICENSE
  • README.md
安装Node.js TypeScript语言是运行于Node.js框架之上的,所以我们需要安装Node.js。但是Node.js版本演变非常快,而且一般会具有LTS版本和最新特性的Current两个版本,所以我们需要一个合适的Node版本管理器对Node.js的版本进行管理,Node版本管理器的作用就是可以在不同版本之间快速切换Node.js而不用频繁、麻烦地卸载再安装。
卸载已安装的Node.js
为了安装Node.js版本管理工具需要先将已安装的Node.js卸载,如果你的电脑未安装过Node.js可以跳过此步,直接浏览"安装Node.js版本管理器NVM for Windows"。
想要完全干净地卸载Node.js可以通过命令行执行以下命令:
  1. 清除Package缓存:npm cache clean --force
  2. 卸载Node.js:wmic product where caption="Node.js" call uninstall
  3. 删除相关目录:
rmdir /s /q %appdata%\npm rmdir /s /q %appdata%\npm-cache rmdir /s /q %programfiles%\Nodejs rmdir /s /q %programfiles(x86)%\Nodejs rmdir /s /q %homepath%\.npmrc rmdir /s /q %homepath%\AppData\Local\Temp\npm-cache

安装Node.js版本管理器NVM for Windows
Node的版本管理工具有NVM for Windows、nvs和Volta三个,使用最多的是NVM for Windows。
  1. 到NVM for Windows发布页面下载最新版本的nvm-setup.zip文件,解压缩,执行nvm-setup.exe进行安装。
  2. NVM for Windows安装路径默认为C:\Users\\AppData\Roaming\nvm
  3. Node.js安装路径默认为C:\Program Files\nodejs
打开控制台,执行nvm ls查看已安装的Node.js版本命令检查是否已成功安装:
nvm lsNo installation recognized.

安装LTS版本的Node.js
Node.js版本包括历史版本、长期支持的LTS版本(这个版本是Node.js推荐大多用户使用的,也是各大云供应商在自己的云服务中支持的版本),以及当前最新特性版Current版本(这个版本会包含所有最新的功能,但多数情况下不受云服务运行时支持)。
我们使用NVM for Windows可以通过两个命令来查看和安装Node.js版本:
  • nvm list available命令列出所有可用(可安装)的Node.js版本。
  • nvm install 命令安装对应版本的Node.js,其中version可以是latest或lts来安装具有最新特性的版本或LTS版本。例如,当前LTS版本为16.14.2,推荐更多的用户使用;而具有最新特性的当前版本为17.8.0。
我们推荐安装LTS版本:
  • 推荐使用命令nvm install lts安装LTS版本的Node.js。
  • 安装后可使用nvm ls命令列出所有已经安装的版本。
  • 使用nvm use 命令指定Node.js版本,这里的version不能使用latest或tls,必须是nvm ls命令列出的指定的版本号。如16.14.2。
P.S: 如果在执行nvm use 命令时遇到如下错误,建议检查Node.js安装路径是否为空目录,大部分时候是由于残留了原来安装的Node.js下面的文件和目录,删除即可。
  • exit 145: The directory is not empty
  • exit 32: The process cannot access the file because it is being used by another process.
通过以下命令行命令检查Node.js和npm包管理器的版本来检查Node.js是否已被正确安装:
  • node --version
  • npm --version
激活yarn 2包管理器 对于16.10以上版本的Node.js已经通过Corepack内置了最新的yarn包管理器,yarn与npm一样都是包管理器,用来管理程序包的安装、卸载以及依赖关系,yarn从版本2开始对并行加载有了更好的支持,能快速进行包的更新,速度和效率上都远胜于npm,所以我们建议使用yarn取代npm来管理我们的程序包。
其中支持yarn的Corepack默认已在16.10以上版本的Node.js安装中,不过是禁用状态,所以需要我们激活它:
corepack enable

然后我们就可以使用版本2的yarn初始化我们的TypeScript工程项目了:
yarn init -2

此命令会生成如下文件/目录:
  • .editorconfig - 此文件定义了编辑器的缩进及文本转行格式
  • .yarn目录 - 此目录用来保管安装的程序包
  • package.json - 程序包的说明文件
  • .yarnrc.yml - 说明了程序包保管路径
  • yarn.lock
安装TypeScript
  • 本地开发安装TypeScript包:yarn add -D typescript
  • 使用命令yarn tsc -v检查安装TypeScript的版本。
  • 创建src目录:md src
  • 进入src目录:cd src
  • 创建index.ts,内容如下:
let message: string = 'Hello, World!'; console.log(message);

  • 运行TypeScript命令行:npm tsc index.ts ,生成index.js文件。
  • 运行node index.js,执行Javascript文件。
  • yarn tsc --init初始化tsconfig.json文件,默认配置为:
{ "compilerOptions": { "target": "es2016", "module": "commonjs", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true } }

参考标准项目目录结构如下:
project folder\ |---- dist\ |---- src\ |---- test\ |---- package.json |---- tsconfig.json

修改tsconfig,更新如下项目:
{ "compilerOptions": { "rootDir": "src", "sourceMap": true, "outDir": "dist", }, "include": ["src/**/*"], "exclude": [".yarn", "**/*.spec.ts"] }

配置完,保存并运行yarn tsc,就可以看到自动生成了dist目录,并且在目录中生成了index.js和index.js.map文件。
安装ESLint ESLint是静态代码检查工具,配合TypeScript使用可以帮助检查TypeScript的语法和代码风格。
  • 添加ESLint到当前工程,yarn add -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin
通过命令行命令code .eslintrc或打开VS Code创建.eslintrc文件,增加内容如下:
{ "root": true, "parser": "@typescript-eslint/parser", "plugins": [ "@typescript-eslint" ], "extends": [ "eslint:recommended", "plugin:@typescript-eslint/eslint-recommended", "plugin:@typescript-eslint/recommended" ] }

通过命令行命令code .eslintignore或打开VS Code创建.eslintignore文件,增加内容如下:
# Ignore artifacts: .yarn dist

运行命令yarn eslint . --ext .ts执行代码静态检查,运行命令yarn eslint . --ext .ts --fix执行代码修复。
通过命令npm set-script lint "eslint . --ext .ts"向package.json添加lint(静态代码检查)脚本:
{ "scripts": { "lint": "eslint . --ext .ts", } }

  • 添加脚本后,可直接使用yarn lint命令进行静态代码检查。
安装Prettier Prettier是优化代码格式的工具,可优化JavaScript、TypeScript、JSON等代码及配置文件。
  • 使用命令yarn add -D --exact prettier安装Prettier。
  • 创建文件.prettierrc.json,内容如下:
{}

  • 创建文件.prettierignore,内容如下:
# Ignore artifacts: dist coverage

  • 执行命令优化文件格式:yarn prettier --write .
  • 执行命令检查文件格式:yarn prettier --check .
命令行输出如下:
C:\@richardcuick\ts>yarn prettier --write . yarn run v1.22.18 $ C:\@richardcuick\ts\node_modules\.bin\prettier --write . .eslintrc.json 111ms .prettierrc.json 2ms dist\index.js 9ms package-lock.json 98ms package.json 21ms src\index.ts 274ms tsconfig.json 9ms Done in 1.04s.C:\@richardcuick\ts>yarn prettier --check . yarn run v1.22.18 $ C:\@richardcuick\ts\node_modules\.bin\prettier --check . Checking formatting... All matched files use Prettier code style! Done in 0.69s.C:\@richardcuick\ts>

因为同时安装了ESLint和Prettier会导致静态代码检查和格式化之间的一些冲突,可以通过安装eslint-config-prettier程序包解决类似冲突。
  • 执行yarn add -D eslint-config-prettier安装此程序包
  • 运行code .eslintrc命令或编辑.eslintrc文件添加"prettier"到extends集合,如下:
{ "extends": [ "some-other-config-you-use", "prettier" ] }

安装Husky Husky是Git hooks程序包,帮助开发人员增加提交代码前的步骤,如进行静态代码检查或格式化文件。
  1. 通过命令yarn add -D husky lint-staged安装Husky和Lint-Staged
  2. 如果你的程序包不是私有的,还要发布到类似npmjs.com的注册中心,请安装pinst程序包。yarn add -D pinst
  3. 执行命令yarn husky install激活Git钩子(Hooks)
  4. 为了安装后能自动激活钩子,编辑package.json文件,如下:
// package.json { "private": true, // ← your package is private, you only need postinstall "scripts": { "postinstall": "husky install" } }

但是如果你的包不是私有的,你要发布到注册中心如npmjs.com,那么你需要使用pinst禁用postinstall。否则,postinstall将会在别人安装你的程序包的时候运行并报错。
// package.json { "private": false, // ← your package is public "scripts": { "postinstall": "husky install", "prepack": "pinst --disable", "postpack": "pinst --enable" } }

yarn husky add .husky/pre-commit "yarn lint-staged"
【创建TypeScript代码模板(NVS+Yarn+ESLint+Prettier+Husky)】编辑package.json文件如下,在提交代码前进行静态代码检查和格式优化:
{ "lint-staged": { "src\\**\\*.ts": ["eslint", "prettier --write"] } }

    推荐阅读