TypeScript ライブラリ開発

unocss、shiki、unplugin、vite、vitest、vueuse、zod、trpc、drizzle-orm などの研究から抽出した、高品質な TypeScript ライブラリ作成のパターン集。

使用場面

• 新しい TypeScript ライブラリの開始(単一またはモノレポ)
• CJS/ESM のデュアル対応用に package.json のエクスポート設定
• ライブラリ開発向けの tsconfig 設定
• ビルドツールの選択(tsdown、unbuild)
• 型安全な API の設計(ビルダー、ファクトリー、プラグインパターン)
• 高度な TypeScript 型の作成
• ライブラリテスト用の vitest セットアップ
• リリースワークフローと CI の設定

Nuxt モジュール開発の場合: nuxt-modules スキルを使用してください

クイックリファレンス

作業内容	ファイルを読み込む
新規プロジェクト設定	references/project-setup.md
パッケージエクスポート	references/package-exports.md
tsconfig オプション	references/typescript-config.md
ビルド設定	references/build-tooling.md
ESLint 設定	references/eslint-config.md
API 設計パターン	references/api-design.md
型推論テクニック	references/type-patterns.md
テストセットアップ	references/testing.md
リリースワークフロー	references/release.md
CI/CD セットアップ	references/ci-workflows.md

ファイルの読み込み

タスクに応じてこれらの参考ファイルの読み込みを検討してください:

• references/project-setup.md - 新しい TypeScript ライブラリプロジェクトを開始する場合
• references/package-exports.md - package.json のエクスポート設定、または CJS/ESM のデュアル対応を設定する場合
• references/typescript-config.md - tsconfig.json をセットアップまたは変更する場合
• references/build-tooling.md - tsdown、unbuild、またはビルドスクリプトを設定する場合
• references/eslint-config.md - ライブラリ開発向けに ESLint をセットアップする場合
• references/api-design.md - パブリック API、ビルダーパターン、またはプラグインシステムを設計する場合
• references/type-patterns.md - 高度な TypeScript 型または型推論を使用する場合
• references/testing.md - vitest をセットアップするか、ライブラリコードのテストを作成する場合
• references/release.md - リリースワークフローまたはバージョニングを設定する場合
• references/ci-workflows.md - GitHub Actions または CI/CD パイプラインをセットアップする場合

すべてのファイルを一度に読み込まないでください。 現在のタスクに関連するものだけを読み込んでください。

新規ライブラリワークフロー

1. プロジェクト構造を作成 → references/project-setup.md を読み込み
2. package.json エクスポート設定 → references/package-exports.md を読み込み
3. tsdown でビルド設定 → references/build-tooling.md を読み込み
4. ビルドを検証: pnpm build && pnpm pack --dry-run — 出力に .mjs、.cjs、.d.ts が含まれていることを確認
5. テストを追加 → references/testing.md を読み込み
6. リリース設定 → references/release.md を読み込み

クイックスタート

// package.json (最小構成)
{
  "name": "my-lib",
  "type": "module",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  },
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "files": ["dist"]
}

// tsdown.config.ts
import { defineConfig } from 'tsdown'

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

重要原則

• ESM ファースト: "type": "module" と .mjs 出力
• デュアル形式: CJS と ESM の両方のコンシューマーをサポート
• moduleResolution: "Bundler" で最新の TypeScript に対応
• ほとんどのビルドには tsdown、複雑なケースには unbuild
• スマートなデフォルト: 環境を検出し、設定を強制しない
• ツリーシェーキング対応: lazy getter、適切な sideEffects: false

トークン効率: メインスキル ~300 トークン、各参考ファイル ~800-1200 トークン