發佈 npm 套件的小細節

發表於 | 分類於 | |

最近發佈了一個套件 date-reminder

起因是為了可以讓部落格在特別的節日發出祝賀詞
但因為自己是懶人…
所以不可能自己在每個節日前手動更新網站
於是乎上網找了可以提醒的套件
結果…沒有！！！

就手動做了一個套件順便上傳

底下講講發佈 npm 時我的遇到的問題與想法
還有首次製作 npm 時可以特別留意的小細節：

  • 撰寫 README.md
  • 發佈 npm 時指定產品代碼與排除原始代碼
  • Webpack 打包時兼顧 Script Include 與 Script Module

撰寫 README.md

替套件撰寫 README.md 應該是最重要的事

任何人要使用一個網路上的套件時
都會先看 README.md 寫的完不完整
能不能看完就理解套件是如何運作與使用
再來是看有沒有提供 Demo 與範例

當然還有更新日期與星星數等指標

總之就是要判斷這個套件好不好用
還有會不會有後續問題
才來決定要不要使用

我這邊先分享一個網站 readme.so
這個網站提供了一些常用的範例
可以作為 readme 的架構

另外底下提供我認為比較通俗的範本：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# Package Name (套件名稱)

## Description (說明)

套件的主要用途與功能簡單說明

## Installation (安裝方式)

安裝說明

## Usage (使用方式)

需要包含代碼範例還有 API 文件

## License (許可)

許可說明

發佈 npm 時指定產品代碼與排除原始代碼

講這個是因為我首次

npm publish

就把專案上的所有東西一起推上去了 XD

但是用套件的人安裝下去
其實只需要打包後的產品代碼呀 哈哈

所以我後續做了一些補救措施
也就是排除原始代碼與指定發佈檔案

如果要排除發佈的檔案
可以在專案根目錄加上 .npmignore
把用不著的原始代碼都給忽略掉

像是：

1
2
3
4
5
/*

!/dist/js/
!package.json
!README.md

這樣npm publish時就會根據文檔案的內容決定哪些要推送哪些不要

另外一種方式我比較推薦：

就是直接在 package.json 裡面設定 files 屬性
如果有設定這個屬性基本上npm publish就只會看這個來決定有哪些檔案是要發佈的

1
2
3
4
5
"files": [
  "dist/js/",
  "package.json",
  "README.md"
],

Webpack 打包時兼顧 Script Include 與 Script Module

Script Include 就是 js 傳統模組化方式
就是在 html 裡面用 sciprt 標籤引入代碼的這種方式

Script Module 就是 Es Module 的模組化方式
可以使用 import 和 export 來進行匯入與匯出

如果是用 webpack 來打包產品的話
為了能使用 Script Include 的模組方式
要特別在 output 設定 library

1
2
3
4
5
6
7
output: {
  path: path.resolve(__dirname, "dist"),
  filename: "js/[name].js",
  library: "dateReminder",
  libraryTarget: "umd",
  libraryExport: 'default'
},
屬性說明
library模組的函數名稱
libraryTarget模組的目標環境
libraryExport模組的匯出方式

library 的名稱基本上就是暴露出來的接口名稱可以在當前的全域環境裡調用
libraryTarget umd（Universal Module Definition）可以讓模組同時支持瀏覽器環境與 node 環境

另外比較特別的是這個 libraryExport

如果入口文件最後使用 export default 預設匯出的方式
就要特別在 webpack 設定 libraryExport: ‘default’
不然無法在全局裡直接根據 library 名稱來調用

其它備註：

libraryTarget說明
"var"在瀏覽器環境中將模組作為一個變數。
"assign"在瀏覽器環境中將模組分配給特定的全局變數。
"this"在瀏覽器環境中將模組分配給 this 對象。
"window"在瀏覽器環境中將模組分配給 window 對象。
"global"在 Node.js 環境中將模組分配給 global 對象。
"commonjs"使用 CommonJS 的 module.exports 將模組暴露給瀏覽器或 Node.js 環境。
"commonjs2"使用 CommonJS2 的 module.exports 將模組暴露給瀏覽器或 Node.js 環境。
"amd"將模組定義為 AMD (Asynchronous Module Definition) 的形式，供瀏覽器使用。
"umd"支持在 AMD 和 CommonJS 環境中使用的通用模組定義（Universal Module Definition）。
"umd2"類似於 UMD，但使用了 CommonJS2 的 module.exports，適用於瀏覽器和 Node.js 環境。
"thisGlobal"在瀏覽器中使用 this 對象，在 Node.js 中使用 global 對象，以便在兩者中都可使用。

本文作者： David Huang
本文地址： https://davidblog.github.io/2023/07/26/發佈-npm-套件的小細節/

0%