PJCHENder 未整理筆記

[Guide] 發佈 npm 套件 - 從手動到自動(1):發佈前所需的設定檔(package.json)

2020-02-02

[Guide] 發佈 npm 套件 - 從手動到自動(1):發佈前所需的設定檔(package.json)

keywords: deploy, publish, release, CLI, npm, package.json

Imgur

前一篇的文章中我們已經建立好了一個簡單的套件。現在要來說明 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:當使用者發現問題是可以到哪裡回報,可以提供 urlemail
  • license:版權,主要指該套件能否商業使用、私人使用、修改再用等等。預設是 ISC,這裡我使用較多人採用的 MIT,基本上這兩者都算是開源許可的授權,但我並沒有深入理解內部差異,其他授權種類可以參考 Choose an open source license七種開源許可證
  • author / contributors:作者,可以提供作者的 name, email, url;若有多個開發者,則可以寫成 contributors
  • files:當使用者安裝此套件時,實際會下載的檔案。預設使用者安裝時會把整個發布到 npm 上的專案都下載下來,但專案中通常包含有未打包過的檔案(例如,src 資料夾)和打包後的部分(例如,dist 資料夾),透過此設定可以讓使用者安裝時只下載 dist 資料夾內的檔案,不必下載額外用不到的檔案。也可以透過 .npmignore 達到相同的作用(當 .npmignore 放在根目錄時,無法覆蓋 files 欄位的設定,但若放在子目錄時則可以)。
  • main:其他使用者安裝套件後,使用該專案時的載入點,通常會取名為 index.jsmain.js
  • repository:套件程式碼放置的位置,若放置於 github 上的話,則可以填入 github 的網址,將會顯示在 npm 的套件說明頁。
  • engines:套件安裝時建議的 node 和 npm 版本
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
// 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": "dist/index.min.js",
"scripts": {
"dev": "rollup -c -w",
"build": "rm -rf dist/ && rollup -c",
"test": "jest"
},
"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"
],
"devDependencies": {
"jest": "^25.1.0",
"rollup": "^1.31.0",
"rollup-plugin-terser": "^5.2.0"
}
}

其他檔案

除了 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

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

範例程式碼

本篇完整的範例程式碼放到 Github 可供參考:fix:config package.json (9ec80a88)

參考

掃描二維條碼,分享此文章