使用Yeoman開發一個自動化專案模板產生器

Always repeating yourself while setting up a new project? Perhaps try Yeoman — an awesome scaffolding and code generating tool.

8 min readJun 20, 2020

在過去的幾篇文章中曾提到以IaC工具Pulumi和CI/CD工具CircleCI來建構一個容易管理架構和自動部署的前端環境，也寫到如何使用Linter來提升團隊專案程式碼的一致性。隨著前端軟體工程趨勢的演進，許多開發團隊在設計系統架構時會考量將不同的Component打包成分開的專案(package)，用以確保獨立性。然而，若是在建立每一個新專案時都要重新設定一次同樣的Linter、CI/CD工具、IaC工具、檔案架構、測試環境、甚至是README，那就違反了軟體工程黃金準則之一的DRY (Don’t Repeat Yourself)原則了。

一個不錯的解決方案就是使用腳手架工具(Scaffolding Tool)/程式碼產生器(Code Generator)來簡化那些不斷重複的設定流程。在這篇文章中，我會介紹如何使用腳手架工具Yeoman.js和開發一個專屬於你和你團隊的專案樣板。雖然Yeoman本身是一個Node.js的專案（意即用Javascript來撰寫)，但卻不限定所產生之專案的語言（可以用Yeoman來創建如Python、Java等語言的專案。）

在這篇文章中，你將知道：

如何使用現成的Yeoman Generator
如何開發自己的Generator
如何部署Generator用以提供團隊成員使用

若需要程式碼參考，我的Github Repo有示範如何設定Linter、CI/CD以及IaC。

第一次使用Yeoman

Yeoman作為一個Code Generating Tool並不要求每個人都撰寫自己的模板。反之，多數人可以選擇使用既有的模板。時至今日，已經有超過九千個其他團隊或個人釋出免費的模板供社群使用。

那麼，該如何使用這些模板呢？首先，下載Yeoman(yo)在Terminal中執行：

$ npm install -g yo

接著，可以到Yeoman的網頁尋找你需要的產生器（Generator）。為了寫這篇文章，我也準備了一個提供 create-react-app + eslint + pulumi + circleci 的產生器：

$ npm install -g generator-react-ci-iac

下載好之後，可以新建一個資料夾並執行yo來選擇你要使用的產生器：

$ mkdir test-yeoman && cd test-yeoman 
$ yo 
// 或是 yo {name} 
$ yo react-ci-iac

在回答完一系列問題之後，產生器就會開始安裝專案。一陣耐心等待之後就會發現，Yeoman幫我們把專案建立起來了。

之後就可以照我們的流程，進到該專案開始開發，省去原本花費在設定許多如Linter等繁雜事物的時間。

如上所提，現在已經有超過九千個現成的產生器可以使用，你可以到Yeoman的Discovering Generators page去尋找你所需要的產生器。然而，若是真的找不到順手的，在下個段落，我會說明如何開發專屬於自己團隊的產生器。

開發自己的Code Generator

開發之初，建議從Yeoman提供的「產生器模板」產生器開始用起。先下載並執行：

$ npm install -g generator-generator 
$ yo generator

填入每個選項之後，同樣的，產生器就會幫你建立模板和安裝各個套件。

雖然這個產生器會幫你裝上許多如 .editorconfig 之類的東西，但構成一個能執行之產生器的核心檔案其實只有兩個檔案：package.json 和 generators/app/index.js

|- package.json 
|- generators/   
    |- app/     
        |- index.js

在 package.json 中需要留意必須具備的條件：

{
  "name": "generator-{{name}}",
  "description": "",
  "keywords": ["yeoman-generator"],
  "files": ["generators"],
  "dependencies": {
    "yeoman-generator": "^1.0.0"
  }
}

專案名稱 name需要有前綴(prefix) generator-
需要有 description欄位且 keywords中需要有 yeoman-generator 才能被搜尋到
files欄位中需要有 generators 才能讀到該資料夾中的內容
dependencies 需要有 yeoman-generator

作為示範，我們來嘗試開發一個能將字串寫入 dummyfile.txt 的模板產生器。

首先，打開 generators/app/templates/dummyfile.txt，並寫入：

接著，在 generators/app/templates中新增一個檔案 .editorconfig，並寫入：

做以上兩件事的目的是：(1) 示範如何在檔案中保留空間讓使用者寫入，(2) 示範如何將隱藏檔案（檔名前綴為.點）也寫進目的地。

下一步，打開 generators/app/index.js：

這裡我們看到Generator提供了三個階段(1) prompting, (2) writing, (3) install。

在prompting階段，我們可以讓使用者填寫一些需要的資料。在這段範例中，我們詢問使用者想要將哪些文字寫入 dummyfile.txt 中。
在writing階段中，generator就會開始將模板從來源路徑複製進目標路徑。 globOptions: { dot: true } 這句的意思就是，連同隱藏檔案（檔名前有.點的）一同複製，當我們需要複製 .gitignore, .editorconfig 等檔案時都用得到。
this.fs.copyTpl 中的 Tpl 意思是模板template，我們可以取得模板來源和模板目標路徑，並在第三個參數中放入要填入的內容。記得在 dummyfile.txt 中，我們寫了 <%= someText %> 嗎？在這裡，我們就設定了 someText 所要填入的內容。
在install階段，generator會執行 yarn install 或 npm install 在做的事：安裝相關套件。在我們的模板中，我們沒有定義 package.json ，所以這段會出現可預期的錯誤。

除了上述三個階段，Yeoman Documentation也有介紹其他階段。

測試剛開發的Code Generator

在真正將Code Generator上架到npm前，我們可以先在本地端測試。在你剛剛建立的generator root中：

$ npm link 
// 或 
$ yarn link

接著，就可以yo了

$ cd ../ && mkdir new-project && cd new-project 
$ yo

測試完沒問題之後就可以準備部署了。在那之前，先回到你的generator root directory：

$ npm unlink 
// 或 
$ yarn unlink

部署

最後也是最快樂的步驟就是部署。如果你還沒有註冊npm帳號，請到這裡註冊。接著，回到你的generator root：

$ npm login 
$ npm publish

若是沒有任何意外，當publish流程跑完，你的新code generator也上架了。新建一個資料夾然後將它下載下來測試吧！

$ npm install -g generator-{name} 
$ yo {name}

你的第一個Yeoman Code Generator就順利完成了。

當然，學會開發Code Generator的目的並不是只為了將資料寫進 dummyfile.txt 中，還有許多值得發揮想像力好使模板產生器的效果最大化。

我也分享一下在 generator-react-ci-iac 中所使用的repo: https://github.com/RainRush/generator-react-ci-iac 讓大家參考。

最後，謝謝你花時間閱讀，若是有更好的建議，也歡迎寄信 (daniel@skand.io) 和我討論：）

使用Yeoman開發一個自動化專案模板產生器

Always repeating yourself while setting up a new project? Perhaps try Yeoman — an awesome scaffolding and code generating tool.

第一次使用Yeoman

開發自己的Code Generator

測試剛開發的Code Generator

部署

Written by Daniel Hu