用 Claude Code 寫 npm package 的工作流

Claude Code 不只是 chat 介面 — 它能執行 git 指令、改檔案、跑測試、自動 debug。配合 npm package 開發特別順手。這篇拆解工作室從 0 到發布 npm 套件的標準流程，AI 怎麼接手每一步。

第 1 步：規劃

跟 Claude Code 對話開新專案：

我要寫一個 npm package
功能：把方波音效合成模組獨立出來
名稱：@hao0321/web-sfx
特性：
- TypeScript 寫
- ESM + CJS 雙格式輸出
- 0 依賴
- 支援 tree-shaking
請列出開發計畫，先別動手

Claude 會回一份分階段計畫。確認後再開工。

第 2 步：初始化專案

讓 Claude Code 自動跑：

npm init -y
npm i -D typescript @types/node tsup vitest
npx tsc --init

它會直接建好 package.json、tsconfig.json，並在 scripts 加好 build / test / dev 指令。

第 3 步：核心程式碼

給它原本散在遊戲裡的音效函式：

把這個音效合成程式碼從 dodge-master-v5.html
抽出來變成獨立的 TypeScript module，
請維持 API 簡潔，每個函式有 JSDoc 註解。

它會：

1. 抽出原始程式碼到 src/index.ts
2. 加 type 注解
3. 分檔（如果太大）
4. 幫每個 export 加 JSDoc

第 4 步：tsup 設定 ESM + CJS

tsup 是最簡單的 bundler 之一。設定：

// tsup.config.ts
import { defineConfig } from 'tsup';

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  clean: true,
  treeshake: true,
  sourcemap: true,
});

package.json 對應：

{
  "name": "@hao0321/web-sfx",
  "version": "0.1.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"
    }
  },
  "files": ["dist"],
  "scripts": {
    "build": "tsup",
    "test": "vitest"
  }
}

第 5 步：寫測試

跟 Claude 說「寫測試」即可：

用 vitest 為這套 sfx module 寫測試。
測試重點：
- 每個 oscillator 確實產生對應頻率
- gain 包絡曲線正確
- audio context state 處理

它會用 jsdom + Web Audio mock 寫好測試。

第 6 步：README

幫這個 package 寫 README，包含：
- 一行介紹
- 安裝（npm/pnpm/yarn）
- 5 個 example
- API reference
- License (MIT)

Claude 寫的 README 通常結構完整、example 可運行。我只需要審一下語氣是否夠正式。

第 7 步：CI 自動化

GitHub Actions：

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm run build
      - run: npm test

讓 Claude 直接寫這份 yml，避免手 typing 錯誤。

第 8 步：版本與發布

用 changesets 管版本：

npm i -D @changesets/cli
npx changeset init
# 每次改動：
npx changeset
# 發版：
npx changeset publish

發版前先 npm publish --dry-run 看哪些檔案會上傳，避免意外打包進測試檔。

Claude Code 最有用的 5 個場景

不要交給 AI 的

• API 設計決定：套件的 public API 是契約，要想清楚自己拍板
• License 選擇：MIT vs Apache vs GPL 是法律問題，自己決定
• 命名空間：@yourname/... 還是 unscoped，影響長期
• release 時間點：v1.0 標記什麼時候發，需要產品判斷

結語

Claude Code + tsup + changesets 是 2026 年最流暢的 npm 套件開發組合。原本要 1 週的「弄熟工具」時間壓到 1 天，剩下都在寫真正的 feature 程式碼。對獨立工作室是巨大的賦能。

有想交流 npm package 開發的，歡迎寄信 lo246179268@gmail.com。