TypeScript สร้างและ publish library



อะไรถูก publish

ห้าม publish ไฟล์ .ts ตรง ๆ — ผู้ใช้ library ต้องได้:

  • .js (compiled — รันได้)
  • .d.ts (type — สำหรับ TS)

วิธีที่ 1: tsc

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}
tsc
# dist/index.js, dist/index.d.ts, dist/index.js.map, ...

tsc build เป็น format เดียว (ตาม module) — ถ้าต้อง dual ESM+CJS ใช้ tsup

วิธีที่ 2: tsup (แนะนำ)

npm install --save-dev tsup
// package.json
{
  "scripts": {
    "build": "tsup src/index.ts --format esm,cjs --dts --clean"
  }
}
npm run build
# dist/index.js       (ESM)
# dist/index.cjs      (CJS)
# dist/index.d.ts     (types)

tsup (build บน esbuild) — เร็วมาก, dual format, สร้าง .d.ts, tree-shake, minify ได้

package.json — exports field

{
  "name": "my-lib",
  "version": "1.0.0",
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./package.json": "./package.json"
  },
  "files": ["dist"],
  "sideEffects": false
}
  • "exports" — บอก Node/bundler ว่าไฟล์ไหนสำหรับ ESM (import), CJS (require), type (types)
  • "types" ต้องมาก่อน ใน object (order สำคัญ)
  • "types" (top-level) — fallback สำหรับ tool เก่า
  • "files" — เฉพาะ folder/file เหล่านี้ถูก publish (ไม่รวม src/, test, config)
  • "sideEffects": false — บอก bundler ว่า tree-shake ได้ปลอดภัย

multiple entry points

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    },
    "./utils": {
      "types": "./dist/utils.d.ts",
      "import": "./dist/utils.js"
    }
  }
}
import { main } from "my-lib";
import { helper } from "my-lib/utils";
{
  "scripts": {
    "build": "tsup src/index.ts src/utils.ts --format esm --dts --clean"
  }
}

ตรวจ package ก่อน publish

npm pack --dry-run          # ดูว่าไฟล์ไหนจะถูก publish
npx publint                 # ตรวจ exports/types config ผิด
npx @arethetypeswrong/cli   # ตรวจว่า types resolve ถูกในทุก module system
# ในโปรเจกต์ library
npm link

# ในโปรเจกต์ที่จะใช้ library
npm link my-lib

หรือใช้ monorepo (pnpm workspaces / npm workspaces) — reference ตรงจาก source (บทที่ 40)

versioning + publish

npm version patch    # 1.0.0 → 1.0.1  (แก้บั๊ก)
npm version minor    # 1.0.1 → 1.1.0  (feature ใหม่ compatible)
npm version major    # 1.1.0 → 2.0.0  (breaking)

npm publish --access public     # (public สำหรับ scoped package @user/lib)

prepublishOnly script — build อัตโนมัติก่อน publish:

{
  "scripts": {
    "prepublishOnly": "npm run build && npm run test"
  }
}

changesets — สำหรับ monorepo / ทีม

npm install --save-dev @changesets/cli
npx changeset init
npx changeset          # บันทึกว่าแก้อะไร (patch/minor/major)
npx changeset version  # bump version + สร้าง CHANGELOG
npx changeset publish  # publish

เรื่องที่คนมักพลาด

  • publish .ts โดยไม่ build — ผู้ใช้ที่เป็น JS ใช้ไม่ได้; ต้อง compile
  • ไม่มี "types" / .d.ts — ผู้ใช้ TS ไม่ได้ autocomplete/type check
  • "exports" order ผิด — "types" ต้องมาก่อน "import"/"require"
  • ไม่ตั้ง "files" — publish ทั้ง src/, test, .env (เสี่ยง secret หลุด)
  • ESM/CJS mismatch — package "type": "module" แต่ main ชี้ .js ที่เป็น CJS
  • ไม่รัน publint / arethetypeswrong — types resolve พังในบาง config โดยไม่รู้ตัว
  • peerDependencies ไม่ระบุ (เช่น React) — bundle React เข้าไปด้วย

สรุป

  • publish .js + .d.ts (ไม่ใช่ .ts); build ด้วย tsc (single format) หรือ tsup (dual ESM/CJS + dts)
  • "exports" ใน package.json — { ".": { "types": ..., "import": ..., "require": ... } } (types ก่อน)
  • "files": ["dist"] — คุมว่าอะไรถูก publish; "sideEffects": false — tree-shake ได้
  • ตรวจก่อน publish: npm pack --dry-run, publint, @arethetypeswrong/cli
  • npm version <patch|minor|major> (SemVer) + prepublishOnly build/test; changesets สำหรับทีม

บทถัดไปว่าด้วยการเขียนเทสต์ — Vitest กับ TypeScript, typing test, mock และ type-level testing