การเผยแพร่ Package

การเผยแพร่ npm package ต้องการให้คุณตัดสินใจเรื่อง metadata ที่ถูกต้อง เลือกสิ่งที่จะ expose และควบคุม lifecycle การ versioning ให้ดี บทเรียนนี้ครอบคลุมทุกอย่างตั้งแต่ package.json ที่พร้อม publish ไปจนถึงการ push package ขึ้น registry

package.json ที่พร้อม publish

package ที่ดีควรมีฟิลด์สำคัญเหล่านี้:

{
  "name": "@myorg/my-lib",
  "version": "1.0.0",
  "description": "A concise description for npm search",
  "license": "MIT",
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "files": [
    "dist",
    "README.md"
  ],
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    }
  },
  "engines": {
    "node": ">=18.0.0"
  }
}

ฟิลด์ files

"files" ระบุว่าไฟล์และโฟลเดอร์ใดจะถูกรวมไว้ใน published package ใช้เป็น allowlist เพื่อให้แน่ใจว่าไม่ส่ง source file, test, หรือ config ที่ไม่จำเป็นไปให้ผู้ใช้

{
  "files": [
    "dist",
    "README.md",
    "LICENSE"
  ]
}

ไฟล์บางอย่างถูก exclude โดยอัตโนมัติ เช่น node_modules, .git, และไฟล์ที่ระบุใน .npmignore หรือ .gitignore

ฟิลด์ bin

หาก package ของคุณมี CLI tool ใช้ฟิลด์ "bin" เพื่อ map ชื่อคำสั่งไปยังไฟล์ที่รันได้:

{
  "bin": {
    "my-cli": "./dist/cli.js"
  }
}

เมื่อ install globally หรือใช้ใน npx คำสั่ง my-cli จะพร้อมใช้งาน

การกำหนดเวอร์ชันด้วย Semantic Versioning

npm ใช้ Semantic Versioning (semver): MAJOR.MINOR.PATCH

PATCH — bug fix ที่ backwards compatible
MINOR — feature ใหม่ที่ backwards compatible
MAJOR — breaking changes

ใช้คำสั่ง npm version เพื่อ bump version, อัปเดต package.json, และสร้าง git tag โดยอัตโนมัติ:

# bump patch version: 1.0.0 → 1.0.1
npm version patch

# bump minor version: 1.0.0 → 1.1.0
npm version minor

# bump major version: 1.0.0 → 2.0.0
npm version major

ทดสอบก่อน publish ด้วย npm pack

ก่อน publish ให้สร้าง tarball local เพื่อตรวจสอบว่าไฟล์ที่จะถูกส่งออกนั้นถูกต้อง:

npm pack

คำสั่งนี้สร้างไฟล์ .tgz ในโฟลเดอร์ปัจจุบัน คุณสามารถ inspect เนื้อหาหรือติดตั้งใน project อื่นเพื่อทดสอบก่อน publish จริง:

# install local tarball in another project
npm install ../my-lib/myorg-my-lib-1.0.0.tgz

การ publish

# login to npm registry
npm login

# publish public scoped package
npm publish --access public

# publish with a dist-tag (e.g. beta)
npm publish --tag beta

สำหรับ package ที่มีชื่อ scope เช่น @myorg/my-lib ต้องระบุ --access public เพื่อ publish แบบ public มิฉะนั้น npm จะถือว่าเป็น private (ต้องเสียค่าใช้จ่าย)

Scoped packages

Scoped packages มีรูปแบบ @scope/name และช่วยจัดกลุ่ม package ขององค์กรหรือโปรเจกต์:

# create a scoped package
npm init --scope=@myorg

# publish to npm public registry
npm publish --access public

# install a scoped package
npm install @myorg/my-lib