發送自己的專案到 CDNJS 供別人使用吧!

網路上有很多文章是關於如何使用 cdnjs.com 來引用遠端腳本和樣式,但卻沒有人提到如何將自己的專案提交到 cdnjs.com 來讓他們進行提供的服務,而這篇文章就是要提及這個。(雖然這篇有提到,但還是看不懂)

所以什麼是 CDNJS?CDN 意指大型內容分發網路,在傳統網站中使用者會拜訪你的網站,然後向你的網站請求所有需要檔案,但當訪客量大時,你的網站將會不堪負荷,且瀏覽器現今還有最大同時連線數,這意味著一個網站同時最多只能有七個連線(大略),當讀取圖片又讀取樣式的時候,會需要等待部分圖片讀取完才可進行另一個請求。

因此你能夠將網站的部分內容改成讓使用者從 CDN 請求,你能夠把 CDN 看作是一個檔案伺服器,分佈在世界各地。當使用者來自台灣,就會向 CDN 的台灣機房請求檔案,而美國來的訪客則會向美國的 CDN 請求檔案,除了能減少網站負荷,還可以增加讀取速度,一舉兩得!而且這項服務還是免費的!

必要資格

使用這項服務是免費而且不限資格的,倘若是要將自己的專案發佈至 CDNJS 則需要符合下列任ㄧ資格即可。

  1. 這個專案在 GitHub 或 BitBucket 上有大於至少 100 個星星/追蹤者/衍生。
  2. 這個專案在 npm 每月超過 500 次下載數。

然後你的專案一定要有版本語意,例如透過標籤(Tag、Release)清楚地分明你的專案版本,如:1.0.02.3.0-rc1 等。


1. 初期動作

實際上 CDNJS 他們的教法是要你自己複製一整份倉庫到本機,然後新增自己的檔案,接著發送合併請求回去到他們的倉庫⋯⋯但那有 65 GB 欸。

其實你可以自己決定要複製什麼檔案,減少到剩下 2 GB,不過那對我的筆電來說也是不堪負荷,所以我決定直接轉戰網頁版的 GitHub,通通從網頁解決。

建立衍生倉庫

首先到 cdnjs 的 GitHub 倉庫中按下「Fork」來建立衍生倉庫。

如果你有多帳號或者多個組織,按下之後可能會出現一個視窗要你選擇衍生到哪個帳號,通常是選擇自己的帳號即可。

建立支線

現在你的帳號底下已經有了 CDNJS 的衍生倉庫,這意味著你可以開始更改倉庫內的檔案了。但 CDNJS 官方要求每個發布請求需要有一個具有意義的支線名稱,所以在這裡我們要建立一個新的支線。例如我的專案名稱是 tocas-ui,所以就建立一個 tocas-ui 支線。

在衍生倉庫的頁面上有個「Branch」的下拉式選單,裡面輸入新的支線名稱就會出現一個建立選項,按下去即可。

建立好之後 GitHub 將會自動導向到你剛才建立的支線,你可能看不出來有什麼差異就是了。

2. 在本地電腦準備檔案

因為等一下要一口氣上傳檔案,這樣才不會有多個修改記錄,到最後還要自己修改而造成麻煩,所以我們需要先在自己的電腦建立一個資料夾,這個資料夾由你的專案名稱為主,注意:只能小寫不可含空白可有減號分隔。在這裡以範例的 tocas-ui 為主。

接著裡面需要擺放一個版本資料夾,因為 tocas-ui 最新的版本是 2.3.2,所以就建立一個 2.3.2 資料夾然後裡面擺放要發布的檔案。

然後資料夾裡面還有個 package.json 的檔案用來表述你的專案,這比較複雜所以獨立到下面敘述。

建立 package.json

我們需要在同樣的資料夾內建立一個 package.json 用來表明專案、還有指定什麼檔案能被他人使用。你需要在這個檔案裡面輸入資訊,這裡是我的範本(別照抄,等等會有解釋)。

{
  "name": "tocas-ui",
  "filename": "tocas.css",
  "version": "2.3.2",
  "description": "A CSS3 UI library with the meaningful naming convention.",
  "homepage": "https://tocas-ui.com/",
  "keywords": [
    "tocas",
    "css3",
    "ui"
  ],
  "autoupdate": {
    "source": "git",
    "target": "git://github.com/TeaMeow/TocasUI.git",
    "fileMap": [
      {
        "basePath": "dist",
        "files": [
          "**/*"
        ]
      }
    ]
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/TeaMeow/TocasUI"
  },
  "license": "MIT",
  "author": "Yami Odymel <[email protected]>"
}

這裡是這個檔案你應該要更改的地方,還有相對應的註釋。

  • name:專案名稱,僅能小寫、不可空白、可有減號作分隔線。
  • filename:最主要的檔案名稱。
  • version:專案最新的版本號,請確保你的專案都有用 Tag 做版本釋出。
  • description:用英文撰寫的專案註釋。
  • homepage:專案的網站網址。
  • keywords:符合專案的關鍵字。
  • autoupdate.target:專案 GitHub 的 .git 路徑。
  • autoupdate.fileMap.basePath:專案裡會被發布的資料夾路徑,假設是 dist,則是專案內 dist 資料夾裡的檔案都會被發布。
  • autoupdate.fileMap.files:這個地方基本上不用修改,因為我們有透過 basePath 指定資料夾了,**/* 指的是所有檔案,因此即是 basePath 裡的所有檔案。
  • repository.url:專案的 GitHub 網址。
  • license:專案的授權規範,如 MITGPLBSD
  • author:專案作者名稱和電子郵件地址。

而且有趣的是這個檔案很坑人,你必須移除多餘的結尾空白,而且通常你看不到那些空白,例如 } 後面常常藏著空白。還有你必須用兩個空白當作排版,四個空白會出錯。

為什麼我會知道?不是因為我叫 Trivago,因為我就被坑過。

3. 上傳檔案

新的支線已經建立好了、檔案也都準備好了,現在要開始在這個倉庫內新增自己的檔案。現在回到你的衍生倉庫,進入 cdnjs/ajax/libs 並且點擊畫面右邊的「Upload files」上傳檔案的按鈕。

接著會看到下面的介面,這頁面表明你可以拖曳檔案上傳,所以我們直接拖曳剛才在本地電腦建立的專案資料夾(這裡範例是 tocas-ui 資料夾)到頁面上然後放開。檔案就會逐一上傳,像下面這樣。

檔案都上傳好了之後,在下面的「Commit changes」中輸入你的修改資訊,這個資訊一定要按照這個格式:Add 專案名稱@版本號碼 w/ git auto-update,所以這個範例就是 Add [email protected] w/ git auto-update

git auto-update 的意思就是透過 GitHub 倉庫自動更新,未來你在 GitHub 釋出新的版本,CDNJS 那邊也就會自動抓取更新。不過如果你常常在 npm 上面發佈更新的話,你就可以改成 w/ npm auto-update

好了之後按下綠色的「Commit changes」按鈕即可。

4.建立合併請求

當按下按鈕後你會回來你自己的衍生倉庫頁面,接著按下「New pull request」按鈕。

然後會來到下面這個頁面,檢查你的檔案沒有問題,順便記得看一下你的 package.json 確定沒有多餘的結尾空白(這真的很靠邀)。

然後記得將自己的支線切換成我們替自己專案所建立的支線,因為 CDNJS 要求你一定要用有意義的支線發送合併請求。

之後就可以按下綠色的「Create pull request」按鈕,然後就會開啟一個輸入表單要你填寫資訊。

這個表單翻譯成中文是這樣。

# Profile of the lib
 * Git 倉庫網址(必填):
 * 官方網站網址(可選、非倉庫網址):
 * NPM 套件網址(可選):
 * 授權方式:
 * GitHub / Bitbucket 知名度(必填):
   - 追蹤者人數:
   - 星星數量:
   - 衍生數量:
 * NPM 下載統計(可選):
   - 昨日下載次數:
   - 上星期下載次數:
   - 上個月下載次數:

# 必要檢查項目
 * [ ] 我是這個函式庫的作者
   * [ ] 我很樂意在我的網站或倉庫中加上 CDNJS 的相關連結
 * [ ] 這個專案沒有出現在 cdnjs 裏
 * [ ] 沒有重複的問題/合併請求
 * [ ] 這個專案有值得關注的知名度
   * [ ] 大於 100 [顆星星/關注者/衍生次數] 在 [GitHub / Bitbucket] 上
   * [ ] 每個月在 npm 有大於 500 次下載數
 * [ ] 專案已經在知名的平台上發佈過了 (或者在 npm 上)

# Auto-update checklist
 * [ ] 每個版本都有正確的標籤名稱 (for git auto-update)
 * [ ] Auto-update 設置
 * [ ] Auto-update 目標/來源是正確的
 * [ ] Auto-update filemap 是正確的

# Git commit checklist
 * [ ] 修改訊息少於 50 個字,而且清晰易於理解。
 * [ ] 複製的 cdnjs 倉庫沒有舊於 3 天
 * [ ] 合併請求是來自一個非 master 且具有意義的分支
 * [ ] 有將不相關的修改分開
 * [ ] 透過 rebase 將多餘的修改合併成一個
 * [ ] 有在修改訊息中提及到相對應的問題使其自動關閉
 * [ ] 在修改訊息中提到相對應的問題、人、事情

這部分可能比較難理解,所以可以參考我之前所發送的合併請求

發送之後你會看到你的合併請求已經到 cdnjs 的倉庫中提出了(就像下面這個畫面ㄧ樣)。接著就是等待他們的機器人建置測試,確認你的檔案沒有問題。

接下來⋯⋯就是等待審核了。

後記:出錯的話⋯⋯有友善的審核員

要是好死不死,你被 package.json 的結尾空白問題坑到,或者你的設定不對,就會有建置機器人告訴你 CI test failed,表示你的檔案沒有通過測試,這個時候會有下面這樣的訊息。

過一段時間也會有審核員來告訴你你的檔案哪裡出了問題,這位審核員告訴我 package.json 後面有個不可見的空白,只要砍掉就好了。這個時候只要回去自己的支線,然後編輯 package.json 就會直接在這裡出現修改訊息,並且機器人會重新幫你測試直到你通過為止(要有綠色打勾)。

他們的要求很嚴格,你需要把所有修改記錄統一成單個,但我們是透過網頁修改,網頁的 GitHub 並沒有提供此功能(不能合併修改成單個),所以我就告訴他們「如果有必要,我會重新開啟一個合併請求」,然而他們的審核員很親切,直接告訴我:「如果你不能自己手動複製倉庫的話,審核員能幫你合併修改記錄」。

我回答「好」之後,他就主動幫我合併了修改紀錄,而且途中不需要開什麼權限給他,在一切安好之後就是等待了。

過了四天之後,自己的專案終於上了 CDNJS,而且審核員都很熱心會幫你補上你先前的版本,告訴你哪裡出錯,或是幫你。