Module Seed: 一套優雅的 Github 工做流

Motivation

平時喜歡寫一些 NPM 模塊，寫得多了，整理出一套工做流，解放一些重複的搭建工做。
若是你喜歡，請直接拿去用，也能夠參照該項目的一些 Feature ，給你一些提示與幫助。html

Feature

支持 Typescript
支持單元測試，與測試覆蓋率
快速生成文檔站點
接入 Circle CLI，構建、發包、文檔站點一條龍服務
規範 ESLint + Prettier
快速生成 Change Log
生成同時支持 CommonJS 和 ES Module 的 NPM 包

Download

git clone git@github.com:JerryC8080/module-seed.git
複製代碼

Usage

1. Architecture

.
├── .circleci // CircleCI 腳本
│   ├── config.yml
├── coverage // 自動生成的測試覆蓋率報告
├── docs  // 自動生成的文檔
├── build  // 構建代碼
│   ├── main  // 兼容 CommonJS
│   │   ├── index.d.ts
│   │   ├── index.js
│   │   └── lib
│   └── module  // 兼容 ES Module
│       ├── index.d.ts
│       ├── index.js
│       └── lib
├── src  // 源碼
│   ├── index.ts
│   └── lib
│       ├── hello-world.spec.ts // 單元測試
│       └── hello-world.ts
├── CHANGELOG.md
├── LICENSE
├── README.md
├── package.json
├── tsconfig.json
└── tsconfig.module.json
複製代碼

2. Npm Script

Script	Description
build	構建代碼，生成 ./build 文件夾
fix	快速格式化代碼
test	構建單元測試
watch:build	動態構建代碼，用於開發模式
watch:test	動態構建單元測試，用於開發模式
cov	構建單元測試覆蓋率，生成 ./coverage 文件夾
doc	構建文檔站點，生成 ./docs 文件夾
doc:publish	發佈文檔站點到 github pages
version	強制以 patch 模式更新 version，如：v0.0.1 → v0.0.2

3. Coverage

經過運行 npm run cov，命令會構建單元測試，而且輸出網頁版本的測試報告：node

open coverage/index.html
複製代碼

4. Docs

經過運行 npm run doc，會構建 TS API 文檔，而且輸出網頁版本：git

open docs/index.html
複製代碼

5. CircleCI Config

本項目選擇 CircleCI 來完成項目構建、發佈 NPM、發佈文檔站點等自動化構建工做。github

1. Add Repo to CircleCI

2. Test Coverage to Coveralls

若是想擁有一個這樣的 Status: shell

須要把你的 repo 添加到 coveralls.ionpm

而後，在 CircleCI 添加環境變量 COVERALLS_REPO_TOKENjson

那麼，每次 CircleCI 發生構建的時候，就會上報單元測試覆蓋率到 coveralls 去。markdown

參考 .circleci/config.yml 相關腳本:併發

...
upload-coveralls:
  <<: *defaults
  steps:
    - attach_workspace:
        at: ~/repo
    - run:
        name: Test Coverage
        command: npm run cov
    - run:
        name: Report for coveralls
        command: | npm install coveralls --save-dev ./node_modules/.bin/nyc report --reporter=text-lcov | ./node_modules/.bin/coveralls     - store_artifacts:
        path: coverage
...
複製代碼

3. Doc Site to Github Pages

本地能夠經過命令來構建和發佈文檔站點到 Github Pagesssh

npm run doc
npm run doc:publish
複製代碼

若是這個動做交給 CircleCI 來完成，則須要爲 Repo 添加一個 Read/Write 權限的 User Key

那麼，每次 CircleCI 發生構建的時候，就會構建文檔，併發布到 Github Pages 中去。

例如本項目，就能夠經過如下地址訪問：

jerryc8080.github.io/module-seed

參考 .circleci/config.yml 相關腳本:

...
 deploy-docs:
    <<: *defaults
    steps:
      - attach_workspace:
          at: ~/repo
      - run:
          name: Avoid hosts unknown for github
          command: mkdir ~/.ssh/ && echo -e "Host github.com\n\tStrictHostKeyChecking no\n" > ~/.ssh/config
      - run:
          name: Set github email and user
          command: | git config --global user.email "huangjerryc@gmail.com" git config --global user.name "CircleCI-Robot"       - run:
          name: Show coverage
          command: ls coverage
      - run:
          name: Show docs
          command: ls docs
      - run:
          name: Copy to docs folder
          command: | mkdir docs/coverage cp -rf coverage/* docs/coverage       - run:
          name: Show docs
          command: ls docs
      - run:
          name: Publish to gh-pages
          command: npm run doc:publish
...
複製代碼

4. Coverage site

在 CircleCI 的 deploy-docs 任務中，會構建 Coverage Site ，而後一塊兒發佈到 Github Pages 的 /coverage 目錄中。

例如本項目，就能夠經過如下地址訪問：

jerryc8080.github.io/module-seed…

5. NPM Deploy

自動化腳本會以 patch 的形式升級版本號，例如：v0.0.1 → v0.0.2。
而後發佈到 npmjs.com 去。

若是須要啓用這一功能，須要爲 CircleCI Repo 添加 npm token。

首先，獲取 npm token

而後，爲 CircleCI Repo 添加環境變量：npm_TOKEN

那麼，每次 CircleCI 發生構建的時候，就會構建和發佈 NPM 包。

參考 .circleci/config.yml 相關腳本:

...
deploy:
  <<: *defaults
  steps:
    - attach_workspace:
        at: ~/repo
    - run:
        name: Set github email and user
        command: | # You should change email to yours. git config --global user.email "huangjerryc@gmail.com" git config --global user.name "CircleCI-Robot"     - run:
        name: Authenticate with registry
        command: echo "//registry.npmjs.org/:_authToken=$npm_TOKEN" > ~/repo/.npmrc
    - run:
        name: Update version as patch
        command: npm run version
    - run:
        name: Publish package
        command: npm publish
...
複製代碼