首页

翻译自：Starting a TypeScript Project in 2021;

译文来源：2021年如何从零创建一个TypeScript项目

本文通过以下工具从零创建一个TypeScript项目。

基础配置

基础配置有以下四步：

  1. 创建项目目录和源码目录
  2. 创建package.json
  3. 配置.gitignore, tsconfig.json, .eslintrc.js
  4. 安装TypeScript等相关依赖

本文示例使用yarn，如果你常用npm的话也有对应类似的命令。

# 创建项目目录
mkdir my-project
cd my-project

# 创建源码文件
mkdir src
touch src/main.ts src/main.test.ts src/cli.ts

# 创建package.json
yarn init

# 安装TypeScript, linter,  Jest
yarn add -D typescript @types/node ts-node
yarn add -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin
yarn add -D jest ts-jest @types/jest

# 获取.gitignore
wget https://raw.githubusercontent.com/metachris/typescript-boilerplate/master/.gitignore

# 获取tsconfig.json
wget https://raw.githubusercontent.com/metachris/typescript-boilerplate/master/tsconfig.json

# 也可以自己生成一个tsconfig.json
tsc --init

# 获取.eslintrc.js
wget https://raw.githubusercontent.com/metachris/typescript-boilerplate/master/.eslintrc.js

# 获取jest.config.json, 可提供给ts-jest在不需要单独对typescript编译的情况下做测试
wget https://raw.githubusercontent.com/metachris/typescript-boilerplate/master/jest.config.js

# 初始化git并提交
git init
git add .
git commit -am "initial commit"

在package.json中扩展script字段：

{
  "scripts": {
    "cli": "ts-node src/cli.ts",
    "test": "jest",
    "lint": "tslint -c tslint.json 'src/**/*.ts'",
    "build": "tsc -p tsconfig.json",
    "clean": "rm -rf dist build",
    "ts-node": "ts-node"
  }
}

现在，已经可以在项目中执行 yarn cli, yarn test, yarn lint, yarn build, yarn ts-node <filename>。

通过Jest做测试

添加Jest测试代码，例如：

import {greet} from './main'

test('the data is peanut butter', () => {
    expect(1).toBe(1)
});

test('greeting', () => {
    expect(greet('Foo')).toBe('Hello Foo')
});

可以通过yarn test执行测试，而不需要再单独的编译步骤。

esbuild

esbuild 是一个执行贼快的JavaScript打包工具，它主打性能这块，也可用于编译TypeScript代码， 为不同运行环境(浏览器/Node)进行打包。esbuild现在还比较年轻而且还在积极开发中，可以到 esbuild on GitHub 详细了解。

为什么要用esbuild而不直接用tsc？是因为esbuild不能很好的为浏览器环境做打包(所以常借助额外的打包工具，例如webpack,parcel,rollup)，而且tsc特别慢。

安装esbuild:

yarn add -D esbuild

Node.js环境打包

除了tsc，还可以使用esbuild为目标环境为Node.js做打包，例如：

# 打包
yarn esbuild src/cli.ts --bundle --platform=node --outfile=dist/esbuild/cli.js

# 打包&minify&sourcemap
yarn esbuild src/cli.ts --bundle --platform=node --minify --sourcemap=external --outfile=dist/esbuild/cli.js

# 执行&输出
node dist/esbuild/cli.js

esbuild的更多参数可以到esbuild的文档中查看。

注意：

构建兼容浏览器环境的模块

可以通过esbuild, webpack, parcel等打包工具打包成兼容浏览器环境的模块。

本文示例使用esbuild:

# 打包
yarn esbuild src/browser.ts --bundle --outfile=dist/esbuild/browser.js

# 并且 minify&sourcemap
yarn esbuild src/browser.ts --bundle --minify --sourcemap=external --outfile=dist/esbuild/browser.js

生成的browser.ts，可用于在浏览器中加载并执行。

访问Dom属性

在浏览器环境中代码可以访问window或document对象，以及可能需要挂载一些值到window对象上。

在tsconfig.json中，添加Dom相关的预定义声明：

{
  "lib": [
    "ES6",
    "DOM"
  ]
}

添加src/browser.ts文件，用于浏览器环境打包的入口。文件中代码在window添加了新的属性。

// file: src/browser.ts
import {greet} from './main'

(window as any).greet = greet

执行打包：

yarn esbuild src/browser.ts --bundle --outfile=dist/esbuild/browser.js

可通过该示例仓库进行测试: browser-test.html

发布到npm

接下来将代码发布到npm，然后在Node.js和浏览器环境下使用它。

npm和yarn会忽略.gitignore中的文件，如果有想版本控制但是不发布的文件，可以通过.npmignore重写文件忽略的设置。
wget https://raw.githubusercontent.com/metachris/micropython-ctl/master/.npmignore

执行build-all以及发布:

# Build with tsc and esbuild
yarn build-all

# Update the version and publish to npm
yarn publish

build-all命令会执行tsc获取声明文件，以及执行esbuild用于构建Node.js和浏览器环境的代码。

执行yarn publish之后项目就发布到npm了，例如：typescript-boilerplate-2021。

在Node环境中使用

下载包：

npm install typescript-boilerplate-2021

# or with yarn
yarn add typescript-boilerplate-2021

在代码中调用：

import {greet} from 'typescript-boilerplate-2021'

greet("World")

在浏览器环境使用

npm项目文件会自动分发到一些CDN中，例如：jsDelivr, cdnjs, unpkg.com, skypack。从而可以如下链接获取：

在html中引入链接，查看示例：browser-test.html

<script src="https://cdn.jsdelivr.net/npm/typescript-boilerplate-2021@0.3.0"></script>

持续继承

你可能会希望每次将代码push到远程仓库的时候自动执行测试、构建、部署等操作。

GitHub Actions

详细文档查看GitHub Actions docs。新建文件.github/workflows/lint-and-test.yml：

name: Lint and test

on: [ push, pull_request ]

jobs:
  lint_and_test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        nodejs: [ 10, 12, 14 ]

    steps:
      - uses: actions/checkout@v2

      # https://github.com/actions/setup-node
      - uses: actions/setup-node@v2-beta
        with:
          node-version: ${{ matrix.nodejs }}

      - run: yarn install
      - run: yarn test
      - run: yarn lint
      - run: yarn build-all

在多操作系统中测试

通过创建matrix功能，可以在不同系统中(Windows,Linux,macOS)进行打包和测试。

jobs:
  default-version:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ macos-latest, windows-latest, ubuntu-latest ]

    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2-beta
        with:
          node-version: 12
    ...

GitLab CI

详细文档查看GitLab CI docs。新建文件.gitlab-ci.yml：

image: node:12

cache:
  paths:
    - node_modules/

stages:
  - test

lint-and-test:
  stage: test
  script:
    - yarn install
    - yarn test
    - yarn lint
    - yarn build-all

生成API文档

基于TypeScript和JSDoc语法，可以通过TypeDoc自动生成html文件的API文档。

从而可以通过CI自动生成文档，例如：

例如，https://metachris.github.io/typescript-boilerplate/是当前示例仓库生成的API文档。

总结

当前我们就创建了一个完整的TypeScript项目，具备测试、esbuild、Node环境和浏览器环境的打包、发布到npm、持续集成、自动生成文档。 完整示例代码：typescript-boilerplate。

其他