创建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 WindowsnvsVolta三个,使用最多的是NVM for Windows。

  1. NVM for Windows发布页面下载最新版本的nvm-setup.zip文件,解压缩,执行nvm-setup.exe进行安装。

  2. NVM for Windows安装路径默认为C:\Users\<User Name>\AppData\Roaming\nvm

  3. Node.js安装路径默认为C:\Program Files\nodejs

打开控制台,执行nvm ls查看已安装的Node.js版本命令检查是否已成功安装:

nvm ls

No installation recognized.

安装LTS版本的Node.js

Node.js版本包括历史版本、长期支持的LTS版本(这个版本是Node.js推荐大多用户使用的,也是各大云供应商在自己的云服务中支持的版本),以及当前最新特性版Current版本(这个版本会包含所有最新的功能,但多数情况下不受云服务运行时支持)。

我们使用NVM for Windows可以通过两个命令来查看和安装Node.js版本:

  • nvm list available命令列出所有可用(可安装)的Node.js版本。
  • nvm install <version>命令安装对应版本的Node.js,其中version可以是latest或lts来安装具有最新特性的版本或LTS版本。例如,当前LTS版本为16.14.2,推荐更多的用户使用;而具有最新特性的当前版本为17.8.0。

我们推荐安装LTS版本:

  • 推荐使用命令nvm install lts安装LTS版本的Node.js。
  • 安装后可使用nvm ls命令列出所有已经安装的版本。
  • 使用nvm use <version>命令指定Node.js版本,这里的version不能使用latest或tls,必须是nvm ls命令列出的指定的版本号。如16.14.2。

P.S: 如果在执行nvm use <version>命令时遇到如下错误,建议检查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"

编辑package.json文件如下,在提交代码前进行静态代码检查和格式优化:

{ 
    "lint-staged": { 
        "src\\**\\*.ts": ["eslint", "prettier --write"]
    } 
}

参考文档: