npm package開發指南-包內容篇

假設咱們要開發一個 npm 庫，名字叫 lib-dev-tutorial，那麼須要包含哪些內容？咱們下面就來列舉下，初始化目錄結構以下:

lib-dev-tutorial
  ├── src -- 源碼目錄
  |    └── index.js
  ├── .gitignore
  └── package.json

package包含的內容

庫的使用者使用的文件

若是開發人員安裝了你的庫，那麼引入的時候找哪一個文件？編譯源碼生成 dist/index.js，並在 package.json 中增長一個 main 字段指向這個文件。

lib-dev-tutorial
  ├── dist
  |    └── index.js
  ├── src -- 源碼目錄
  |    └── index.js
  ├── .gitignore
  └── package.json

{
  "main": "dist/index.js"
}

npm 始於 node，因此這個文件應該符合 commonjs 的模塊規範。

符合ES Module的文件

如今支持運行原生 ES Module 的環境在變多，若是開發人員使用 ES Module 來編寫程序。那麼咱們直接提供一個符合 ES Module 規範的文件，就不須要再把上一步中 commonjs 規範文件轉成 ES Module 了。經過編譯工具編譯出使用 ES Module 規範的文件 es/index.js，並在 package.json 中增長一個 module 字段指向這個文件。

lib-dev-tutorial
  ├── es
  |    └── index.js
  ├── dist
  |    └── index.js
  ├── src -- 源碼目錄
  |    └── index.js
  ├── .gitignore
  └── package.json

不少庫爲了把上述兩步的文件語義化區分，會把 dist 目錄改爲 lib，咱們也遵循這個習慣：

lib-dev-tutorial
  ├── es
  |    └── index.js
  ├── lib
  |    └── index.js
  ├── src -- 源碼目錄
  |    └── index.js
  ├── .gitignore
  └── package.json

{
  "main": "lib/index.js",
  "module": "es/index.js"
}

經過script引用的文件

若是你但願本身的庫健壯點，還能夠提供 umd 模式的文件，讓你的庫能夠直接在 html 上經過 script 標籤引用。經過編譯工具編譯出文件 umd/index.js

lib-dev-tutorial
  ├── umd
  |    └── index.js
  ├── es
  |    └── index.js
  ├── lib
  |    └── index.js
  ├── src -- 源碼目錄
  |    └── index.js
  ├── .gitignore
  └── package.json

umd/index.js 要不要壓縮按本身需求來決定。

類型聲明文件

TypeScript 的使用已經異常普遍了，咱們也增長一個本身庫的類型聲明文件。方法有三種：

• 把類型聲明文件放到某一個目錄下（譬如：typings/index.d.ts），並在 package.json 中增長 types 字段指向這個文件。

lib-dev-tutorial
  ├── umd
  |    └── index.js
  ├── es
  |    └── index.js
  ├── lib
  |    └── index.js
  ├── src -- 源碼目錄
  |    └── index.js
  ├── typings
  |    └── index.d.ts
  ├── .gitignore
  └── package.json

{
  "main": "lib/index.js",
  "module": "es/index.js",
  "types": "typings/index.d.ts"
}

注：package.json 中字段 types 也能夠寫成 typings，二者是等價的。

• 在庫的根目錄下直接放一個 index.d.ts，這個文件原則上不須要在 package.json 指定。可是推薦全部狀況都在 package.json 指明類型聲明文件的位置。

lib-dev-tutorial
  ├── umd
  |    └── index.js
  ├── es
  |    └── index.js
  ├── lib
  |    └── index.js
  ├── src -- 源碼目錄
  |    └── index.js
  ├── index.d.ts -- 原則上無需在 package.json 聲明文件位置
  |
  ├── .gitignore
  └── package.json

• 單獨編寫類型聲明文件，發佈到 npm 上的 @types organization 下 @types/lib-dev-tutorial，這種方式開發者須要單獨安裝類型聲明文件 npm install --save @types/lib-dev-tutorial

文檔

• READMD.md - 這個是做爲你的庫在 npm 網站上的主頁。
• CHANGELOG.md
• LICENSE

lib-dev-tutorial
  ├── umd
  |    └── index.js
  ├── es
  |    └── index.js
  ├── lib
  |    └── index.js
  ├── src -- 源碼目錄
  |    └── index.js
  ├── typings
  |    └── index.d.ts
  |
  ├── .gitignore
  ├── package.json
  ├── README.md
  ├── CHANGELOG.md
  └── LICENSE

發佈

package.json字段

如下是和發佈到 npm 有密切關係的字段(但不只限於這些字段)

• name：庫的名字。
• version：庫的版本號，發佈的時候讀取的就是這個字段。
• author：庫做者，會在 npm 網站庫首頁顯示。
• license：開源證書，會在 npm 網站庫首頁顯示。
• repository：代碼庫地址，會在 npm 網站庫首頁顯示。
• homepage：庫的主頁地址，會在 npm 網站庫首頁顯示。
• dependencies：你的庫依賴的其餘庫，在開發者 install 你的庫的時候會一併下載。

scoped庫

若是你的庫是公開庫，則直接 npm publish 就能夠了（對了 publish 前記得 login 噢~）。

若是你的庫名是 @name/subname，說明你的庫是 scoped，那麼你還要作這些事情：

1. 登陸到 npm 網站，創建一個 @name 的組織：https://www.npmjs.com/org/create （填寫 organization name 的時候 @ 符號不用填），付費仍是公開按需本身的須要。首次發佈，若是不先創建，是發不上去的，會報 Scope not found。
2. 若是你的庫名是 @name/subname，且按公開庫發佈，在運行 npm 發佈命令時要加參數：npm publis --access public

3. 第二步中若是不加參數，請在 package.json 中加上以下字段：

   {
     "publishConfig": {
       "access": "public"
     }
   }

和 package 無關

最後稍微說下你會在代碼庫中還會包含點什麼文件。

持續集成

使用持續集成服務，譬如 travis，你會有配置文件 .travis.yml

github

會有 .github 文件夾，下面會有些訪問 github 如何展現 issue 等頁面的配置文件。

其餘

各類 ignore 文件，各類工程化配置文件。各類 demo/example，各類測試相關文件，等等等等。

特別說明

本篇是筆者對本身開發工做的梳理總結，若是有遺漏其餘比較關鍵的部分，歡迎你們指正。