在2018年如何優雅的開發一個typescript語言的npm包？

騰訊雲加社群發表於2019-01-19
TypeScriptNPM

歡迎大家前往騰訊雲+社群，獲取更多騰訊海量技術實踐乾貨哦~

本文由小明plus發表

很多時候，我們可能想要用 typescript 語言來建立一些模組，並提交到 npm 供別人使用，

那麼在 2018 年，如果我想要初始化這樣的一個模組，我需要做哪些步驟呢？：

答案是：建立一個優雅的，對開發者友好的模組，至少需要以下 15 個步驟

  1. 初始化資料夾，初始化 git 倉庫，初始化 npm，初始化 tsc
  2. 修改 tsconfig.js 配置
  3. 新增 npm 指令碼
  4. 新增 tslint 校驗程式碼規則以及 editorconfig,prettier 統一程式碼風格
  5. 設定 git 提交的校驗鉤子
  6. 開始編寫程式碼
  7. watch 模式開發
  8. 忽略 ts 編譯生成的資料夾
  9. 新增單元測試
  10. 寫一個單元測試示例
  11. 設定一些有用的 npm 指令碼
  12. 完善 package.json 的描述資訊
  13. 提交程式碼到 git 倉庫
  14. 釋出包到 npm

本篇文章裡，我會列出每個步驟的詳細說明。

實際開發中，如果每個包都去走一遍這些步驟，步驟好像確實有點多。所以如果你需要實際建立專案的時候，你可以選擇 clone 我提供的樣板專案 來開始一個新的 ts 模組的開發，主要步驟如下：

git clone https://github.com/xiaomingplus/npm-typescript-boilerplate.git your-project-name
cd your-project-name
# 安裝依賴
npm i
# 開始開發
npm start
# 修改 package.json 裡面的專案名和簡介
# 修改 README.md 檔案內容
# 修改 遠端倉庫的地址
git remote set-url origin your-git-url

下面就是常規步驟了，學習目的的話，建議按照下面的步驟全部跑一遍：

1. 初始化資料夾，初始化 npm，初始化 tsc

mkdir project-name
cd project-name
# 初始化git專案
git init
# 新增gitignore檔案
touch .gitignore
# 複製這個地址的ignore內容到.gitignore <https://github.com/github/gitignore/blob/master/Node.gitignore>

# 新增readme檔案
echo "# My Awesome Typescript Project" >> README.md
# 安裝typescript
npm install --save-dev typescript
# 初始化npm包
npm init --y
# 初始化tsconfig
tsc --init

2. 修改 tsconfig.js 配置

修改以下預設配置：

{
    "compilerOptions": {
        "declaration": true,
        "outDir": "./lib",
     },
    "include": ["src"],
    "exclude": ["node_modules", "**/__tests__/*"]
}

最終的 tsconfig 配置如下：

{
    "compilerOptions": {
        "target": "es5",
        "module": "commonjs",
        "declaration": true,
        "strict": true,
        "outDir": "./lib",
        "esModuleInterop": true
    },
    "include": ["src"],
    "exclude": ["node_modules", "**/__tests__/*"]
}

3. 新增 npm 指令碼

在 package.json 裡編輯 scripts 欄位:

{
  "scripts": {
    "start": "tsc -w",
    "build": "tsc"
  }
}

4. 新增 tslint 校驗程式碼規則以及 editorconfig,prettier 統一程式碼風格

npm install --save-dev prettier tslint tslint-config-prettier

新建tslint.json檔案

{
  "extends": ["tslint:recommended", "tslint-config-prettier"],
  "rules": {
    "no-console": false,
    "object-literal-sort-keys": false,
    "member-access": false,
    "ordered-imports": false
  },
  "linterOptions": {
    "exclude": ["**/*.json", "node_modules"]
  }
}

新建 .prettierrc 檔案

{
  "trailingComma": "all",
  "tabWidth": 4,
  "semi": false,
  "singleQuote": true,
  "endOfLine": "lf",
  "printWidth": 120,
  "overrides": [
    {
      "files": ["*.md", "*.json", "*.yml", "*.yaml"],
      "options": {
        "tabWidth": 2
      }
    }
  ]
}

新建 .editorconfig

# EditorConfig is awesome: https://EditorConfig.org

# top-most EditorConfig file
root = true

# Unix-style newlines with a newline ending every file
[*]
end_of_line = lf
insert_final_newline = true
charset = utf-8
indent_style = space
indent_size = 4

[{*.json,*.md,*.yml,*.*rc}]
indent_style = space
indent_size = 2

新增一個便捷的 scripts 指令碼：

{
  "scripts": {
    "format": "prettier --write "src/**/*.ts" "src/**/*.js"",
    "lint": "tslint -p tsconfig.json"
  }
}

5. 設定 git 提交的校驗鉤子

設定 git 提交的鉤子校驗規範

npm install --save-dev husky @commitlint/config-conventional @commitlint/cli commitizen cz-conventional-changelog

新建 commitlint.config.js 檔案

touch commitlint.config.js

寫入：

module.exports = {
  extends: ["@commitlint/config-conventional"]
};

新建 .huskyrc 檔案

touch .huskyrc

寫入:

{
    "hooks": {
        "pre-commit": "npm run format && npm run lint && npm test",
        "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
}

新建配置檔案：

touch .czrc

寫入配置：

{ "path": "cz-conventional-changelog" }

package.json 新增 scripts 配置：

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

6. 開始編寫程式碼

cd project-name
mkdir src
cd src
touch index.ts

寫下你的第一行 ts 程式碼：

export const Greeter = (name: string) => `Hello ${name}`;

7. watch 模式下開發

npm start

8. 忽略 ts 編譯生成的資料夾

把/lib資料夾新增到.gitignore

/lib

9. 新增單元測試

npm install --save-dev jest ts-jest @types/jest

建立 jestconfig.json檔案：

{
  "transform": {
    "^.+\.(t|j)sx?$": "ts-jest"
  },
  "testRegex": "(/__tests__/.*|(\.|/)(test|spec))\.(jsx?|tsx?)$",
  "moduleFileExtensions": ["ts", "tsx", "js", "jsx", "json", "node"]
}

修改 package.json 裡的 scripts 下的 test :

{
  "scripts": {
    "test": "jest --config jestconfig.json"
  }
}

10. 寫一個單元測試示例

在 src 資料夾下新建一個 __tests__的資料夾來存放測試用例檔案，新建一個 Greeter.test.ts檔案,寫入：

import { Greeter } from "../index";
test("My Greeter", () => {
  expect(Greeter("Carl")).toBe("Hello Carl");
});

執行測試用例：

npm test

結果應該是通過的。

11. 設定一些有用的 npm 指令碼

prepare: 釋出前和使用者安裝前執行

prepublishOnly: 釋出前執行

preversion: 新建一個版本前執行

version: 新建一個版本後執行

postversion: 新建版本後執行

{
  "scripts": {
    "prepare": "npm run build",
    "prepublishOnly": "npm test && npm run lint",
    "preversion": "npm run lint",
    "version": "npm run format && git add -A src",
    "postversion": "git push && git push --tags"
  }
}

12. 完善 package.json 的描述資訊

name 完善包名，描述，包入口檔案 main 欄位，typescript 型別檔案 types 欄位定義

{
    "name": "project-name"
    "description": "A nice greeter",
    "main": "lib/index.js",
    "types": "lib/index.d.ts"
}

13. 完善文件資訊

新建 doc 資料夾，在裡面可以寫一些模組詳細的文件:

mkdir doc

完善 readme.md的資訊，格式可以參考 這裡

14. 提交程式碼到 git 倉庫

釋出之後就把程式碼提交到 git 倉庫吧

git add .
git commit -m "feat: init"
# 關聯到遠端倉庫不屬於本教程的內容，就不寫push了

15. 釋出包到 npm

如果你還沒註冊 npm 的使用者的話，需要先註冊。

npm adduser

註冊好之後就可以釋出到 npm 了:

# 自動修改package.json檔案版本號+1
npm version patch
npm publish

釋出之後，你可以去 https://www.npmjs.com/ 上找到你的包

參考

Step by step: Building and publishing an NPM Typescript package.

此文已由作者授權騰訊雲+社群釋出，更多原文請點選

搜尋關注公眾號「雲加社群」，第一時間獲取技術乾貨，關注後回覆1024 送你一份技術課程大禮包！

相關文章