ts-library

TypeScript ライブラリの開発

unocss、shiki、unplugin、vite、vitest、vueuse、zod、trpc、drizzle-orm などの調査から得られた、高品質な TypeScript ライブラリを作成するためのパターンです。

使用する場面

• 新しい TypeScript ライブラリ（単一またはモノレポ）を開始するとき
• デュアル CJS/ESM 向けに package.json の exports を設定するとき
• ライブラリ開発用に tsconfig を設定するとき
• ビルドツール（tsdown、unbuild）を選ぶとき
• 型安全な API（ビルダー、ファクトリー、プラグインのパターン）を設計するとき
• 高度な TypeScript 型を記述するとき
• ライブラリのテスト用に vitest を設定するとき
• リリースワークフローと CI を設定するとき

Nuxt モジュールの開発には： nuxt-modules スキルを使用してください

クイックリファレンス

作業内容	ファイルを読み込む
新規プロジェクトのセットアップ	references/project-setup.md
パッケージの exports	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 の exports またはデュアル 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 の exports を設定する → 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 (minimal)
{
  "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 の両方のコンシューマーを常にサポート
• 最新の TypeScript には moduleResolution: "Bundler" を使用
• ほとんどのビルドには tsdown、複雑なケースには unbuild を使用
• スマートなデフォルト：環境を検出し、設定を強制しない
• ツリーシェイキング可能：遅延ゲッターと適切な sideEffects: false

トークン効率：メインスキルは約300トークン、各リファレンスは約800～1200トークン