Web Components 介紹與實作說明 (3) | 模組化開源與 CDN

前情

先前我們介紹了如何實作一個 Tooltips 的 WebComponenet 元件，今天我們來說明如何將我們辛苦寫好的 UI 元件模組化並上傳到 NPM 套件庫，方便之後可以重複使用。

模組化

在先前 CodePen 的範例中，其實我們就使用了 立即調用函式 IIFE (Immediately Invoked Function Expression) 的方式來宣告我們的 Custom Element。

使用 IIFE 來執行模組化除了可以在網頁載入時執行我們定義的函式外，也可以透過局部作用域的創建來避免變數汙染與命名衝突等問題，是前端模組化常常使用的模式，他的基本語法如下:

1
2
3
(function () {
  // 要執行的程式碼
})();

而宣告與定義一個 WebComponent 主要是使用 window.customElements.define 來宣告我們自定義的 HTML 標籤，所以語法會像下面這樣:

1
2
3
4
5
6
7
8
9
// my-tag.js
(function () {
  window.customElements.define(
    "my-tag",
    class extends HTMLElement {
      // 定義 Custom Element 參數、行為等
    }
  );
})();

完成上述的 IIFE 的程式碼後，我們可以將這段程式碼儲存在一個自訂的檔案，如: my-tag.js，後續只要透過 <script> 標籤在網頁載入即可使用

1
2
3
4
5
6
7
8
9
<html>
  <head>
    <script src="my-tag.js"></script>
  </head>
  <body>
    <!-- 使用 my-tag 標籤 -->
    <my-tag></my-tag>
  </body>
</html>

使用 JS 打包工具

雖然直接將 JS 程式碼透過 IIFE 打包就可以執行模組化並上傳到 NPM 套件庫上，但在實務上由於我們還會需要執行 單元 / E2E 測試 、 Lint 語法檢測 、 Babel 轉換程式碼 ，甚至是 編譯 CSS 還有 Minify 產出 等等工作，所以通常都還是會使用像是 Webpack、 Rollup 等模組化打包工具來執行打包的作業。

各類打包工具的介紹網路上可以找到許多資源，這邊我們就不多做說明，大家可以選擇自己偏好的工具來使用，如果您的模組比較簡單，也可以直接使用 IIFE 的方式來發行您的模組。

發布套件到 NPM 套件庫

在開發完成我們的模組之後，接下來我們可以按照下列步驟將它發佈到 NPM 套件庫上，方便之後重複安裝與使用。

一、整理 package.json

在專案目錄中修改 package.json 檔案，如果目錄沒有這個檔案，可以執行下列指令來新增：

1
npm init

上述指令執行後會跳出輸入專案相關資訊的對話，輸入完成後會產生如下的 package.json 檔案:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "name": "@yishiahsia/wc-tooltip",
  "version": "1.0.0",
  "description": "A lightweight and developer-friendly tooltip web component.",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [
    "tooltip",
    "webcomponent"
  ],
  "author": "yishiashia <yishiashia@gmail.com>",
  "license": "MIT"
}

在範例專案中，我使用 rollup 套件打包工具來編譯與打包專案，編譯完成的產出會在 dist/ 目錄，專案目錄結構如下:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
.
├── LICENSE
├── README.md
├── babel.config.js
├── dist
│   └── tooltip.js
├── package-lock.json
├── package.json
├── rollup.config.js
├── src
│   ├── index.ts
│   ├── tooltip.scss
│   ├── tooltip.ts
│   └── types
│       └── declaration.d.ts
├── tsconfig.json
└── types
    └── index.d.ts

編譯完成後，我們需要修改 package.json 如下，首先要指定專案版本編號，一個編號只能夠被發佈一次不可以重複使用，另外要指定需打包的檔案以及套件的載入點，包含 dist/ 產出目錄還有為了支援 Typescript ，我們也加入了 types/ 目錄 (Optional，可不加)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
{
  "name": "@yishiahsia/wc-tooltip",
+  "version": "1.0.0",
  "description": "A lightweight and developer-friendly tooltip web component.",
-  "main": "index.js",
+  "main": "dist/tooltip.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [
    "tooltip",
    "webcomponent"
  ],
+  "files": [
+    "dist/*",
+    "types/*"
+  ],
  "author": "yishiashia <yishiashia@gmail.com>",
  "license": "MIT"
}

二、發佈到 NPM 套件庫

在整理完成 package.json 之後，我們就可以著手來發佈我們的套件，可以先到 https://www.npmjs.com/ 網站註冊一個帳號，註冊完畢後，回到專案目錄中，執行下列指令進行套件發佈:

1
npm publish --access=public

執行上述指令後，依照指示登入您剛剛註冊完成的帳號，即可完成套件的發佈，完成後可以在 npm 官網上看到剛剛發佈的套件。

完整範例專案可參考: GitHub

安裝與使用

完成套件發佈以後，我們就可以在新專案中來安裝使用這個套件，可以透過 npm 指令 安裝套件到我們新的專案，或者透過 jsDelivr CDN 直接在 HTML 中載入與使用套件。

一、使用 CDN 來安裝使用套件

當套件在 NPM 套件庫發佈以後，jsDelivr CDN 服務會自動快取我們發佈的套件，並在他們的 CDN 提供套件的靜態檔案快取，透過如下的 html 可以直接使用我們寫好的套件:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>title</title>

    <!-- 從 CDN 載入套件 -->
    <script src="https://cdn.jsdelivr.net/npm/@yishiashia/wc-tooltip@1.0.2"></script>

  </head>
  <body>

    <!-- 使用 wc-tooltip 自定義標籤 -->
    <wc-tooltip alt="hello">
      <span style="border: solid 1px black; padding: 16px"> hover me </span>
    </wc-tooltip>

  </body>
</html>

二、使用 npm 來安裝使用套件

除了使用 CDN 載入套件外，也可以透過 npm 工具來安裝到我們的專案目錄:

1
npm install @yishiashia/wc-tooltip

安裝完成後除了可以直接使用 wc-tooltip 自定義 HTML 標籤外，也可以繼承 Tooltip Class 來進一步擴充它的功能:

1
2
3
4
5
import Tooltip from '@yishiashia/wc-tooltip';

class NewTooltip extends Tooltip {
  // Override here
}

結語

今天我們介紹了如何將寫好的套件模組化，並發佈到 NPM 套件庫中，然後透過 CDN 或 npm 工具進行安裝與使用在後續的新專案之中，透過重複使用發佈的 WebComponent 元件來減少重複開發的成本，也可以加速專案開發的時程。

前情#

模組化#

使用 JS 打包工具#

發布套件到 NPM 套件庫#

一、整理 package.json#

二、發佈到 NPM 套件庫#

安裝與使用#

一、使用 CDN 來安裝使用套件#

二、使用 npm 來安裝使用套件#

結語#

前情

模組化