從 0 到 1 做一個 npm module

我做的第一個 npm module

前陣子在公司做專案的時候，和主管討論到要加上一個常用的功能，主管說那不如就包成一個 module 如何，雖然只是一個簡單的功能，幾行程式碼就可以解決，但就當作練習也未嘗不可，畢竟知名的 left-pad 就是一個很好的例子（如果不知道這個事件可以看這裡），也趁還記憶猶新的時候紀錄一下。

- 目錄
所以什麼是 npm module？
製作你的第一個 npm module
發布到 npm 上
語意化版本（SemVer）
版本控制
module 的說明文件（README）
單元測試

所以什麼是 npm module？

當我們在寫程式的時候，常常會需要處理許多不同的功能，例如畫圖、框架、滾動等，我們不太可能每次都一個一個寫出來，這樣太麻煩了也不切實際，秉持著盡量不重複打造輪子的原則，我們會去找前人已經做好的 module 來用，這些 module 下載下來之後會自動放在 node_modules 裡面，我們就可以在需要的地方引用了，輕鬆又方便。

製作你的第一個 npm module

建立 npm 帳號

我們現在要做的就是要將我們的程式碼，發布成一個 npm module 可以供大家下載使用，那既然是要發佈在 npm 上面，第一步當然就是要創立一個 npm 帳號。

建立 npm 專案

建立好帳號之後，就要開始來寫專案。首先，開一個資料夾，進到資料夾之後 npm init，先建立這個專案的 package.json 。

接著就是寫你 npm module 的程式碼了，預設的檔名是 index.js，像是如果你想要寫一個兩數相加的功能，可以寫成以下：

// index.js

function add(a, b) {
  return a + b
}

export { add }

因為我們這邊想用 ES6 的 export & import 寫法，所以在 package.json 的配置裡面要加上

// package.json

{ 
  "type": "module"
}

然後就完成了。

沒錯，最簡單的 npm module 只要有 index.js 和 package.json 就可以發布

發布到 npm 上

在發布到 npm 前，我們要確認本機的 npm 是登入的，可以用 npm whoami 來確認。如果之前都沒登入過，可以下 npm login 這行來登入。

接著我們還要檢查幾件事

// package.json

{ 
  "name": "check-deadline",   // 不能和現有的 npm module 重複     
  "version": "1.0.0",         // 除了第一次外，之後每次發布版本都要+1
  "main": "index.js"          // 確認入口點的名稱是正確的
}

都確認無誤之後，我們只要 npm publish 就可以發布摟！

語意化版本（SemVer）

剛剛我們在 package.json 裡看到的版本號（version），又被稱為語意化版本（semantic versioning，簡稱 SemVer）。

在 npm 的文件中已經寫得很清楚了，這邊就不另外贅述，簡單來說我們可以透過版本號的變化來得知這個專案的變動程度。

1.0.0 這三個數字分別代表：主版號（major）、次版號（minor）、修訂號（patch），除了手動去改之外，我們更常會使用 npm 內建的 npm-version 去修改。使用方法很簡單，假設我想讓版本號從 1.0.0 變成 1.0.1，我只要 npm version patch 就可以了，以此類推。

版本控制

除了版本號之外，通常我們也會搭配 git 一起進行版本控制，使用上應該還算滿簡單的，但在我們打版本號的時候，有可能會出現下面這個錯誤訊息：

npm version patch
npm ERR! Git working directory not clean.
...

這代表你需要把所有變動都 commit 過後才能打版本號，解決方法很簡單

git add .
git commit -m "publish to npm"
npm version patch

這樣應該就沒問題了！

module 的說明文件（README）

一個成功的 npm module，除了你寫的功能很有價值外，通常也需要一份好的說明文件（不然你當使用者是會通靈逆？）。

怎麼樣可以寫得好，相信大家可以多找幾份套件來參考，應該就可以寫出一份像樣的了，不過可以確定的是最好是寫成英文的，畢竟目前國際主流就是英文，這樣才能保證你的文件可以被最多人讀懂。

單元測試

然後我覺得 npm module 的測試是很重要的，除了可以在發布前找到一些預期外的漏洞之外，也可以在你程式規模越來越大的時候，確保每次的改動不會影響到其他地方，不過要怎麼寫測試網路上有很多資源，這裡就不贅述了。

總結

當初會想把程式包成一個 npm module，單純是因為主管的一句建議，然後自己也覺得滿有趣就下去弄了，在這之中也玩了許多自己以前想做但沒機會研究的東西。

例如說為了避免使用者格式輸入錯誤，產生的錯誤訊息看不懂，而寫了一些驗證格式的判斷，然後也順勢做了 unit test。

在推上 github、打版本號、跑測試、發布到 npm 的過程中覺得步驟過於繁瑣，所以也用 github action 做了 CI / CD，這部分就留到下一篇再來說。

不過最有成就感的部分，還是在看到自己寫的東西真的有人下載來用的時候，看著 Weekly Downloads 的數字往上的時候，真的會覺得很有趣。

Reference

製作一個標準的NPM模組 如何做出一個好的 NodeJS 模組？ [npm] 套件版本的意義 semver