npm-package

npm パッケージ開発（Bun 優先）

Bun を主要なランタイムおよびツールチェーンとして npm パッケージをビルド、公開し、npm パッケージが使われるあらゆる環境で動作する出力を作成します。

このスキルを使う場合

次の場合に使用します：

• npm ライブラリパッケージを新規作成する
• 既存パッケージのビルド／テスト／lint ツールを設定する
• CJS/ESM の相互運用、exports マップ、または TypeScript の型宣言に関する問題を修正する
• パッケージを npm に公開する
• パッケージ設定をレビューまたは改善する

次の場合は使用しないでください：

• npx で実行可能な CLI ツールを作成する（npx-cli スキルを使用してください）
• アプリケーションを作成する（公開するパッケージではない場合）
• モノレポで作業する（このスキルは単一パッケージのリポジトリを対象としています）

ツールチェーン

対象	ツール	理由
ランタイム／パッケージマネージャー	Bun	インストール、実行、トランスパイルが高速
バンドラー	Bunup	Bun ネイティブ、デュアル出力、.d.ts 生成
型宣言	Bunup（tsc 経由）	ビルドに統合
TypeScript	module: "nodenext"、strict: true + 追加設定	公開コードの正確性を最大限に高める
フォーマット＋基本的な lint	Biome v2	ESLint より 10～25 倍高速で、単一ツール
型を考慮した lint	ESLint + typescript-eslint	Biome では実現できない 40 以上の型考慮ルール
テスト	Vitest	テストの分離、成熟したモック機能、カバレッジ
バージョン管理	Changesets	ファイルベース、明示的、モノレポ対応
公開	npm publish --provenance	Trusted Publishing / OIDC

新しいパッケージのひな形作成

ひな形作成スクリプトを実行し、完全なプロジェクトを生成します：

bun run <skill-path>/scripts/scaffold.ts ./my-package \
  --name my-package \
  --description "What this package does" \
  --author "Your Name" \
  --license MIT

オプション：

• --dual — CJS/ESM 両方の出力を生成します（デフォルト：ESM のみ）
• --no-eslint — ESLint をスキップし、Biome のみを使用します

続いて、依存関係をインストールします：

cd my-package
bun install
bun add -d bunup typescript vitest @vitest/coverage-v8 @biomejs/biome @changesets/cli
bun add -d eslint typescript-eslint  # unless --no-eslint

プロジェクト構成

my-package/
├── src/
│   ├── index.ts            # Package entry point — all public API exports here
│   └── index.test.ts       # Tests co-located with source
├── dist/                   # Built output (gitignored, included in published tarball)
├── .changeset/
│   └── config.json
├── package.json
├── tsconfig.json
├── bunup.config.ts
├── biome.json
├── eslint.config.ts        # Type-aware rules only
├── vitest.config.ts
├── .gitignore
├── README.md
└── LICENSE

重要な設定の詳細

設定を変更する前に、以下のリファレンスドキュメントを読んでください。各決定の理由と、気づきにくい不具合の原因となる落とし穴が記載されています：

• reference/esm-cjs-guide.md — exports マップの設定、デュアルパッケージの危険性、module-sync、よくある間違い
• reference/strict-typescript.md — tsconfig の根拠、Biome ルール、型を考慮した ESLint ルール、Vitest の設定
• reference/publishing-workflow.md — Changesets、files フィールド、Trusted Publishing、CI パイプライン

主要ルール（必ず守ること）

これらは、違反すると公開パッケージで最もよく発生し、最も深刻な不具合につながるルールです。例外なく従ってください。

パッケージ設定

1. package.json では必ず "type": "module" を使用します。 デフォルトとして適切なのは ESM のみです。サポート対象のすべての Node.js バージョンで require(esm) が動作します。

2. main ではなく、必ず exports フィールドを使用します。 main はレガシーです。exports を使うと、利用者がアクセスできる内容を正確に制御できます。

3. すべての exports ブロックで、types を最初の条件にします。 そうしないと、TypeScript は型を解決できなくてもエラーを表示しないことがあります。

4. 必ず "./package.json": "./package.json" をエクスポートします。 多くのツールで package.json へのアクセスが必要ですが、exports によってアクセスが完全にカプセル化されます。

5. package.json で files: ["dist"] を使用します。 ホワイトリスト方式により、秘密情報がパッケージに含まれるのを防げます。.npmignore は使用しないでください。

6. 公開のたびに npm pack --dry-run を実行します。 tarball に意図したファイルだけが含まれていることを確認してください。

TypeScript

7. 公開パッケージでは module: "nodenext" を使用します。 "bundler" は使用しないでください。nodenext を満たすコードはどこでも動作しますが、その逆は成り立ちません。

8. strict: true は必須です。 これを設定しないと、strict モードを使う利用者のコードでエラーになる型を .d.ts ファイルに含めてしまう可能性があります。

9. noUncheckedIndexedAccess を有効にします。 配列やオブジェクトへのアクセス時にチェックがないことで起きる、実際のランタイムバグを検出できます。

10. declarationMap: true を設定して公開します。 利用者が「定義へ移動」を使って、元のソースに移動できるようになります。

11. 公開パッケージではパスエイリアス（paths）を使用しないでください。 tsc は出力コード内のパスエイリアスを書き換えません。利用者側で解決できなくなります。

コード品質

12. anyは禁止です。 unknownを使用し、型を絞り込んでください。本当に避けられない場合に限り、// biome-ignore suspicious/noExplicitAny: <reason>で抑制し、必ず理由を記載してください。

13. デフォルトエクスポートより名前付きエクスポートを優先してください。 デフォルトエクスポートは、CJS/ESMの境界をまたぐと動作が異なります。

14. 型のみのインポートには、必ずimport typeを使用してください。 verbatimModuleSyntaxとBiomeのuseImportTypeルールによって強制されます。

ビルド

15. format: ['esm']（またはデュアル形式の場合は['esm', 'cjs']）を指定して、Bunupでビルドしてください。 Bunupは.d.tsの生成、外部依存の検出、適切なファイル拡張子の設定を処理します。

16. package.jsonのengines.nodeを>=20.19.0に設定してください。 これは、require(esm)が安定版となった最初のLTSバージョンを、最低サポート対象のNode.jsバージョンとして示すものです。

テスト

17. bun:testではなくVitestを使用してください。 bun:testにはテストの分離機能がなく、モジュールのモックがファイル間で漏れます。Vitestでは、各テストファイルが個別のワーカーで実行されます。

18. カバレッジのしきい値を設定してください（branches、functions、lines、statementsのすべてで80%以上）。vitest.config.tsで強制されます。

開発ワークフロー

# Write code and tests
bun run test:watch    # Vitest watch mode

# Check everything
bun run lint          # Biome + ESLint
bun run typecheck     # tsc --noEmit
bun run test          # Vitest run

# Build
bun run build         # Bunup → dist/

# Prepare release
bunx changeset        # Create changeset describing changes
bunx changeset version  # Bump version, update CHANGELOG

# Publish
bun run release       # Build + npm publish --provenance

サブパスエクスポートの追加

パッケージで複数のエントリーポイントを公開する必要がある場合：

1. ソースファイルを追加します：src/utils.ts
2. bunup.config.tsのentryに追加します：entry: ['src/index.ts', 'src/utils.ts']
3. package.jsonのexportsに追加します：

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    },
    "./utils": {
      "types": "./dist/utils.d.ts",
      "default": "./dist/utils.js"
    },
    "./package.json": "./package.json"
  }
}

注意： エクスポートパスの追加または削除は、semverのメジャー変更です。

CJS/ESMデュアル出力への切り替え

Node.js < 20.19.0向けのCJSサポートが利用者に必要な場合：

1. bunup.config.tsを更新します：format: ['esm', 'cjs']
2. package.jsonのexportsを更新し、module-sync、import、requireの条件を含めます
3. エクスポートマップの正確な構造については、reference/esm-cjs-guide.mdを参照してください

Bun固有の注意事項

• bun buildは.d.tsファイルを生成しません。 Bunup（処理をtscに委譲します）を使用するか、別途tsc --emitDeclarationOnlyを実行してください。
• bun buildのCJS出力は実験的です。 npmで公開可能なCJSには、必ずtarget: "node"を使用してください。target: "bun"では、Bun固有のラッパーが生成されます。
• bun buildは構文をダウンレベル変換しません。 最新のES2022以降の構文は、そのまま出力されます。古いランタイムを対象にする場合は、追加のトランスパイルが必要です。
• bun publishは--provenanceをサポートしていません。 プロベナンス署名にはnpm publishを使用してください。
• bun publishが使用するのはNODE_AUTH_TOKENではなくNPM_CONFIG_TOKENです。 CIパイプラインの調整が必要になる場合があります。