建立套件

一個套件是一個資料夾包含一些程式碼和用來提供 Yarn 關於套件資訊的 package.json

大多數的套件會使用版本控制系統,最常使用的一個就是 git ,但是 Yarn 並不會在意你所使用的是哪一套。在以下的指南中,我們的範例將使用 git 。

附註: 如果你想跟著指南實作,請確保你已經安裝 gitYarn

建立你的第一個套件

為了建立你的第一個套件,請先開起你的系統終端機,執行以下指令:

git init my-new-project
cd my-new-project
yarn init

這將會建立一個新的 git 儲存區,移動到這個儲存區,接著啟動一個互動式的介面如下引導你建立新的 yarn 專案:

name (my-new-project):
version (1.0.0):
description:
entry point (index.js):
git repository:
author:
license (MIT):

你可以回答每個問題,或直接按 enter 來留白以使用預設值。

提示: 如果你想要每個都使用預設值,你也可以執行 yarn init --yes 來跳過互動式的介面。

package.json

現在你應該有個 package.json 內容看起來如下:

{
  "name": "my-new-project",
  "version": "1.0.0",
  "description": "My New Project description.",
  "main": "index.js",
  "repository": {
    "url": "https://example.com/your-username/my-new-project",
    "type": "git"
  },
  "author": "Your Name <you@example.com>",
  "license": "MIT"
}

這些在 package.json 中的欄位意義如下:

  • name 是你的套件的名字,如果你想要將它發佈到公開的平台上的話,請確保它是獨一無二的。
  • version 是個相容於 semver 的套件版本號,你可以隨時發佈你的套件,但它們必須要有不同的版本號。
  • description 是個可選的欄位,但建議你加上這個欄位,讓其他的使用者可以搜尋與了解你的專案。
  • main 用來定義你的程式的進入點,這會被如 Node.js 的程式使用,如果沒有指定的話,會使用預設的 index.js
  • repository 是另一個可選但建議的欄位,這可以幫助其他的使用者找到你的源始碼與貢獻。
  • author 是紀錄套件的建立者或維護者的,請使用以下格式 "Your Name <you@example.com> (http://your-website.com)"
  • license 是你的套件所使用的授權條款。

當你執行 yarn init,你所做的事情就是建立這個檔案,沒有其它的了,你可以隨時視你所需要的編輯這個檔案。

額外的欄位

接下來是一些你可能會想加入你的 package.json 的額外的欄位。

{
  "name": "my-new-project",
  "...": "...",
  "keywords": ["cool", "useful", "stuff"],
  "homepage": "https://my-new-project-website.com",
  "bugs": "https://github.com/you/my-new-project/issues",
  "contributors": [
    "Your Friend <their-email@example.com> (http://their-website.com)",
    "Another Friend <another-email@example.com> (https://another-website.org)"
  ],
  "files": ["index.js", "lib/*.js", "bin/*.js"],
  "bin": {
    "my-new-project-cli": "bin/my-new-project-cli.js"
  }
}
  • keywords 是個關鍵字的清單,讓其他開發者可以找到你的套件或是相關的套件。
  • homepage 是個指向你的套件的首頁的網址,讓開發者們可以在這找到相關的介紹、文件和相關的資源。
  • bugs 是個網址指向回報 bugs 用的頁面,當使用者發現問題時可以回報。
  • contributors 是個套件貢獻者們的列表,如果有其它人參與你的專案,你可以把他們列在這裡。
  • files 是個檔案列表,指示這些檔案在必須包含在套件發佈或安裝時,若沒有指定 Yarn 會包含進所有檔案。
  • bin 是指令列的指令 (執行檔) 的對應關係,讓 Yarn 可以在安裝時建立它們。

若需要完整的 package.json 欄位列表與更多細節,請參閱 package.json documentation

授權條款與開放源始碼

Yarn 的套件通常鼓勵 open source,然而需注意不是把源始碼發佈就可以稱為開放源始碼。

為了讓源始碼可以真正的開源,你將會需要一個開源的授權條款。有很多開源的授權條款可供選擇,以下為幾個常見的:

如果你想要更多的選項,你可以在這找到一個更完整的清單

當你為你的專案選定了一個授權條款時,請記得在專案目錄下加入 LICENSE 檔,內容需有授權條款,與更新 package.json 中的 license 欄位。

附註: 如果你不希望你的專案開源,你必須明確的提供授權條款,否則它將會沒有授權。

分享源始碼

相信你會希望使用者可以取得你的源始碼與回報問題,以下是常見的程式碼託管網站:

這些網站允許使使用者看到你的源始碼、回報問題、與貢獻。當你託管了你的程式碼,你應該加入以下欄位至你的 package.json

{
  "homepage": "https://github.com/username/my-new-project",
  "bugs": "https://github.com/username/my-new-project/issues",
  "repository": {
    "url": "https://github.com/username/my-new-project",
    "type": "git"
  }
}

文件

理想狀況下,你應該在發佈你的套件前寫好你的文件, 至少你應該撰寫一個 README.md 在你的專案目錄下,用來介紹你的專案與公開的 API。

好的文件會讓使用者具備所有需要的知識來開始使用你的專案, 請想想一個完全不了解你的專案的人會遇到什麼樣的問題, 請精確的描述與給予必要的細節,同時請盡量包持文件的簡潔與易讀性, 一個擁有高品質的文件的專案更容易成功。

保持一個較小的套件

當建立一個 Yarn 的套件時,我們鼓勵你將它維持的小而簡潔, 若有需要,將大的套件拆成小的套件, 這能讓 Yarn 有效率的安裝上百甚至上千的套件。

大多的小套件可以減少下載的大小,因為其中不會包含大量的相依性,使得你可以只使用其中的一小部份。

同時你應該檢視套件的內容, 確保你沒有不小心發佈任何不必要的檔案 (建構腳本、圖片等) 在你的套件之中。

同時請注意你所相依的套件,永遠優先使用較小的相依套件,除非你有一個好理由,小心不要意外的相依於一個大規模的套件。