製作 node 套件 (I) - New Repository


這系列文章,我想說明並記錄一下如何製作並使用 npm 發布 node 套件。

一、環境準備

在我們開始之前,您的環境要先:
  • 裝有 node (若需要 node 版本管理,可以使用 nnvm 來協助你)
  • 裝有 npm (你若從 node.js 官網下載安裝套件,npm 會隨附其中)
  • 裝有 git CLI 工具
  • 擁有 GitHub 帳號 (或是 bitbucket、私有的 repo server 也行,總之我以 GitHub 為例)
  • 其他提醒:
    • 若沒有 npm 帳號,請先註冊一個
    • 請先在工作電腦上產生 SSH key,然後將金鑰貼進你的 GitHub 帳號管理系統中
  • 還有一些雜項設定,零零總總說起來,請見下面三張投影片。包含以上這一堆東西,都只要做一次就好了,以後就不用再弄啦! (如果換工作電腦或重灌的話,SSH key 要重新產生再貼到你的 GitHub)





二、在 GitHub 開一個新的 repository

如果您對 GitHub 蠻熟的,這個步驟可以直接跳過。

我習慣先用 GitHub 的 Web 介面先開好倉儲庫(以下簡稱 repo),然後再 clone 回自己電腦繼續下一步,因為我很懶得 git init、改 .gitignore 啦。你也可以在電腦的 terminal 使用下指令的方式來開新的 repo。

  • 在 Repositories 下按 New 新建一個 repo


  • 填寫 repo 的基本資訊,以下請自己看圖說故事
    • 名稱是一定要填的,我時常希望我在 npm 上發布的模組名稱能跟我的 repo 名稱一樣,所以我也會先到 npm 上面搜尋看看自己屬意的名稱有沒有被用走了。(repo 的名稱跟你要向 npm 註冊的 package 名稱也可以不一樣沒關係,我個人是喜歡盡量一樣)
    • 我習慣在開 repo 時,就把初始化 README.md、Add .gitignore 選擇 Node 以及 License 給選好。.gitignore 裡面記載著哪些東西在不要追蹤,當然也不會 check in 到 repo 裡面 (例如我們開發 Node 模組時,專案底下的 /node_modules 目錄,就不要 check in 啦,除非你有特殊的需求!因為那些依賴模組,之後再 npm install 一次通通可以安裝回來,這對使用者來說也比較友善,因為這樣你的 module 才不會很大一坨)

  • Repo 建立完成後,你可以在這個 repo 底下找到 clone 的網址,把它複製起來



  • 在你的工作電腦上,將新開的專案給 clone 下來,然後 cd 進去

  • 在專案資料夾底下,執行 npm init (這會產生一支 package.json)
    • 當我們建立新專案時,不管你有沒有要把它發布到 npm registry,建議還是執行 npm init 產生 package.json,用以管理專案的相關資訊 (我個人覺得 Heroku 的建議很棒!請見 10 Habits of a Happy Node Hacker (2016))
    • 執行 npm init 之後,那幾個問題就照填,很容易懂,不會很難

    • 完成之後你會得到一支 package.json 檔,它是一支記載著跟這個 package 相關訊息的檔案。在這支檔案中 "name" 欄位的值,是真正 npm publish 時要向 npm 註冊的模組名稱,它可以跟 repo 的名稱不一樣沒關係。版本號我們就從 0.0.1 起跳吧!(有些人習慣從 0.1.0 開始,看你自己。)


三、Commit 目前的工作並 push 到遠端倉儲庫

這個步驟我們連續下個幾個 git 指令
  • git status: 查看哪些檔案有變更且尚未 add (staging,列入追蹤)
  • git add package.json:若有很多檔案,我習慣一個一個 add (你也可以用 --all 旗標一次 add 全部)
  • git commit -m 'some message about this commit': 為此次 commit 加上 commit message,如果有多支檔案那就 git cm -am 'xxxxx'    (cm是我設定 commit 子命令的 alias)
  • git push origin master: 將目前專案的狀態 push 到遠端 repo 的 master branch
  • 如果你沒有跟其他人一起合作開發,上述幾個指令會在開發過程中一直使用,一直鬼打牆
  • 上去 GitHub 看看,剛剛的 push 成功啦!

如果這個專案你並沒有要發布的意思 (它可能是一個 app 或測試程式等等之類的),那麼截至以上所提到的關於 git 與 GitHub 的部分,就是會一直圍繞在你開發工作之間的事。如果你想將你的作品發布出去,那麼就進到下面的第四點。
 
(其實你不只可以將 node 或 JS 相關的模組發佈到 npm,只要你爽,你要發 C, C++, Java 都可以,只要你的套件中有合法的 package.json 即可。曾經有 npm 的工程師告訴我,我可以將我寫的 Lua 模組也使用 npm 來管理,後來我也那樣做了。不過,有一派憤怒的開發者非常不認同將 node/JS 以外的東西發佈到 npm,甚至連 React 的 View Component 都不行啊,認為這會使 npm 服務變得很亂!你知道,這還是看你自己的選擇,npm 本身並不會管你想怎麼做。)

四、npm publish 發布模組/套件

接下來,就把這個 module 或 package 發佈到 npm registry 吧!這邊要說明一下,一般對於發佈到 npm 上的模組 (module),習慣就會稱做套件 (package),雖然它也是模組沒錯啦!但是模組更廣義,在你的專案底下每個 xxx.js 都可以是一個 "module" 但就不會稱做是 "package" 啦!package 比較有一整包的概念。
  • 在你的專案資料夾底下,使用 npm publish 命令發布套件
  • 到 npm 看看,很好!成功發布出去了。這樣子別人只要下 npm install humanbeings 就可以安裝這個套件囉~

小結

這篇文章,應該是能夠讓超級新新手有一點點概念。關於如何撰寫模組、如何 publish 還是有一些眉角的,這我們會陸續看到哦!
 
還有還有,如果您有稍微試玩,並不是認真要發布模組的話。依據 npm 的最新政策,請在 24 小時內執行 npm unpublish humanbeings --force 移除你的測試套件,超過時限或是24 小時內已有人相依於你的套件,你就無法再移除發布過的東西囉~
 
(為什麼要趕快移除?因為我覺得應該有一堆人 test 來 test 去,發布了很多垃圾在上面吧 XDDD)
 
 
 
 

沒有留言

技術提供:Blogger.