2020年2月2日

發佈 npm 套件 - 從手動到自動（1）：發佈前所需的設定檔 package.json

      , , ,  
keywords: deploy, publish, release, CLI, npm, package.json
在前一篇的文章中我們已經建立好了一個簡單的套件。現在要來說明 npm 套件中最重要的一支檔案 - package.json。
⚠️ 撰寫文章時使用的 npm 版本為 6.13.7

package.json

每一個 npm 專案中，一定會包含一支 package.json，這支檔案就像是這個套件的「身分證」，裡面說明了和這個套件有關的各種訊息，其中像是套件名稱（name）、作者（author）、套件版本（version）等等。因此當你想要了解別人的套件時，可以先從 package.json 這隻檔案入手，同樣的，別人要認識你的專案時，一樣也會從這支檔案開始。
這裡我們就先來撰寫 function-benchmarker 這個套件的 package.json 吧！
下面列出一個 npm 套件中 package.json 會常用到的欄位，完整的說明可以參考 npm 官方文件：
  • name, version：套件名稱與版本，如果要發布到 npm 的話，名稱和版本會形成一個識別碼，這必須不能與他人重複。npm 使用語意化版本的規範（semver），版本號中會包含 主版號.次版號.修訂號（major.minor.patch），不同版號的更新代表不同的意義，簡單的說明可以參考 [npm] 套件版本的意義 semver。
  • description, keywords：套件描述與關鍵字，用來幫助他人找到這個套件。
  • homepage：如果套件有獨立的介紹網站可以寫在這，否則可填寫 github 的網址，會顯示在 npm 官網說明上。
  • bugs：當使用者發現問題是可以到哪裡回報，可以提供 url 或 email。
  • license：版權，主要指該套件能否商業使用、私人使用、修改再用等等。預設是 ISC，這裡我使用較多人採用的 MIT，基本上這兩者都算是開源許可的授權，但我並沒有深入理解內部差異，其他授權種類可以參考 Choose an open source license、七種開源許可證。
  • author / contributors：作者，可以提供作者的 name, email, url；若有多個開發者，則可以寫成 contributors。
  • files：當使用者安裝此套件時，實際會下載的檔案。預設使用者安裝時會把整個發布到 npm 上的專案都下載下來，但專案中通常包含有未打包過的檔案（例如，src 資料夾）和打包後的部分（例如，dist 資料夾），透過此設定可以讓使用者安裝時只下載 dist 資料夾內的檔案，不必下載額外用不到的檔案。也可以透過 .npmignore 達到相同的作用（當 .npmignore 放在根目錄時，無法覆蓋 files 欄位的設定，但若放在子目錄時則可以）。
  • main：其他使用者安裝套件後，使用該專案時的載入點，通常會取名為 index.js 或 main.js。
  • repository：套件程式碼放置的位置，若放置於 github 上的話，則可以填入 github 的網址，將會顯示在 npm 的套件說明頁。
  • engines：套件安裝時建議的 node 和 npm 版本
// package.json
{
  "name": "@pjchender/function-benchmarker",
  "version": "1.0.0",
  "description": "A simple benchmark for testing function performance",
  "license": "MIT",
  "author": "PJCHENder <pjchender@gmail.com> (https://pjchender.blogspot.com)",
  // 若有多個開發者
  // "contributors": [
  //   "PJCHENder <pjchender@gmail.com> (https://pjchender.blogspot.com)",
  //   "Andyyou <andyyu0920@gmail.com> (https://andyyou.github.io/)"
  // ],
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "engines": {
    "node": ">=8",
    "npm": ">=5"
  },
  "files": [
    "dist"
  ],
  "repository": {
    "type": "git",
    "url": "https://github.com/pjchender/function-benchmarker.git"
  },
  "homepage": "https://github.com/pjchender/function-benchmarker",
  "bugs": {
    "url": "https://github.com/pjchender/function-benchmarker/issues"
  },
  "keywords": [
    "performance",
    "benchmark",
    "evaluation",
    "speed",
    "timer"
  ]
}

其他檔案

除了 package.json 外，套件當中經常還會包含其他設定檔，下面舉幾個常見的設定檔：
其他設定檔可能會依據開發套件時所用的工具而有不同的設定檔，例如 .eslintrc, .eslintignore, .babelrc, .prettierrc 等等。

.gitignore

一些不需要被 git 追蹤的檔案，例如 node_modules 或一些私人的密鑰（token）。在 GitHub 上有整理了各程式語言或專案可以參考的 .gitignore 檔，可以複製一份當作基底在加入其他不想被 git 追蹤或公開到 github 的檔案。其中針對 Node.js 的 .gitignore 檔可以參考這裡 Node.gitignore。

README.md

當專案發佈到 Github 上時預設會顯示的說明頁。

LICENSE

放入與此專案對應的授權說明，一般有通用格式的文件。

CHANGELOG.md

讓其他開發者可以很快地知道此套件每個版本有哪些變更。後需我們以自動化的方式產更新檔案。

範例程式碼

本篇完整的範例程式碼可以參考 fix:config package.json ([b4978ac7]) @ Github。

參考

0 意見:

張貼留言