Package.json 慣例
以下適用於 package.json
檔案的「scripts」區段。
名稱
npm 指令碼名稱必須僅包含小寫字母、:
分隔部分、-
分隔單字,以及 +
分隔副檔名。每個部分名稱應為完整的英文單字(例如 coverage
而非 cov
)或所有小寫的廣為人知的首字母縮寫(例如 wasm
)。
以下是 ABNF 中提案的摘要。
name = life-cycle / main target? option* ":watch"?
life-cycle = "prepare" / "preinstall" / "install" / "postinstall" / "prepublish" / "preprepare" / "prepare" / "postprepare" / "prepack" / "postpack" / "prepublishOnly"
main = "build" / "lint" ":fix"? / "release" / "start" / "test" / "fetch"
target = ":" word ("-" word)* / extension ("+" extension)*
option = ":" word ("-" word)*
word = ALPHA +
extension = ( ALPHA / DIGIT )+
順序
指令碼名稱必須依字母順序出現在 package.json 檔案中。本文件中概述的其他慣例確保字母順序將與邏輯分組一致。
主要指令碼名稱
除了 npm 生命周期指令碼 之外,所有指令碼名稱都必須以以下名稱之一開頭。
建置
從原始碼和/或資料產生一組檔案的指令碼,名稱必須以 build
開頭。
如果套件包含任何 build:*
指令碼,則可以有一個名為 build
的指令碼。如果是這樣,則應產生與個別執行每個 build
指令碼相同的輸出。它必須產生執行這些指令碼輸出的子集。
提取
從外部資料或資源產生一組檔案的指令碼,名稱必須以 fetch
開頭。
如果套件包含任何 fetch:*
指令碼,則可以有一個名為 fetch
的指令碼。如果是這樣,它應產生與個別執行每個 fetch
指令碼相同的輸出。它必須產生執行這些指令碼輸出的子集。
發布
具有公開副作用(發布網站、提交到 Git 等)的指令碼,必須以 release
開頭。
檢查
靜態分析檔案(主要是但不限於執行 eslint
本身)的指令碼,名稱必須以 lint
開頭。
如果套件包含任何 lint:*
指令碼,則應有一個名為 lint
的指令碼,並且它必須執行所有檢查,如果個別呼叫每個 lint:*
指令碼,則會執行這些檢查。
如果可以使用修正,則除非指令碼包含 :fix
修飾詞(請參閱下文),否則 linter 不得套用修正。
啟動
start
指令碼用於啟動伺服器。截至撰寫本文時,沒有 ESLint 套件有多個 start
指令碼,因此 start
不需要任何修飾詞。
測試
執行程式碼以確保實際行為與預期行為相符的指令碼,名稱必須以 test
開頭。
如果套件包含任何 test:*
指令碼,則應有一個名為 test
的指令碼,並且它必須執行所有測試,如果個別呼叫每個 test:*
指令碼,則會執行這些測試。
測試指令碼不應包含檢查。
測試指令碼應在可能的情況下報告測試覆蓋率。
修飾詞
以下一個或多個修飾詞可以附加到上述標準指令碼名稱。如果目標具有修飾詞,它們必須按照它們在下面出現的順序排列(例如 lint:fix:js:watch
而不是 lint:watch:js:fix
)。
修正
如果 linter 可以修正它發現的問題,請新增一個指令碼副本,在結尾附加 :fix
,該副本也會進行修正。
目標
正在執行的動作目標名稱。在 build
指令碼的情況下,它應識別建置產物,例如「javascript」或「css」或「website」。在 lint
或 test
指令碼的情況下,它應識別正在檢查或測試的項目。在 start
指令碼的情況下,它應識別正在啟動哪個伺服器。
目標可以參考受影響的副檔名清單(例如 cjs
或 less
),以 +
分隔。如果有多個副檔名,則清單應按字母順序排列。當副檔名具有變體時(例如 CommonJS 的 cjs
和 ESM 的 mjs
),可以使用副檔名的通用部分,而不是明確列出所有變體(例如 js
而不是 cjs+jsx+mjs
)。
目標不應參考執行動作的工具名稱(eleventy
、webpack
等)。
選項
不屬於其他修飾詞的其他選項。
監看
如果指令碼監看檔案系統並回應變更,請將 :watch
新增至指令碼名稱。