tsdown

tsdown

概要

tsdown は、Rolldown（Rust ベース）上に構築された洗練されたライブラリバンドラーで、TypeScript および JavaScript ライブラリをビルドするための、すぐに使える包括的なソリューションを提供します。ソースの変換、複数の出力形式（ESM、CJS、IIFE、UMD）、TypeScript 宣言ファイルの生成、妥当なデフォルト設定による package.json の exports フィールド生成に対応しています。

使用するケース： npm 向けの TypeScript ライブラリのビルド、宣言ファイルの生成、ESM/CJS 両対応パッケージの作成、CLI ツールのバンドル、ウォッチモードでのライブラリ開発、tsup からの移行。

使用しないケース： アプリケーションのバンドル（Vite/Rolldown を直接使用）、サーバーサイドレンダリングのフレームワーク（フレームワークのバンドラーを使用）、Webpack 固有の機能が必要なプロジェクト、バンドル不要のシンプルなスクリプト。

クイックリファレンス

パターン	API	主なポイント
基本的なビルド	npx tsdown	src/index.ts エントリを自動検出
設定ファイル	tsdown.config.ts	型安全性のために defineConfig() を使用
エントリポイント	entry: ['src/index.ts']	名前付きエントリには文字列、配列、またはオブジェクトを指定
出力形式	format: ['esm', 'cjs']	ESM、CJS、IIFE、UMD に対応
宣言ファイル	dts: true	package.json の types フィールドから自動検出
拡張子の固定	fixedExtension: true	.mjs/.cjs および .d.mts/.d.cts を強制
外部モジュール	external: ['react']	デフォルトで node_modules を外部として扱う
依存関係のバンドル	noExternal: ['lodash-es']	特定の依存関係を強制的にバンドル
ターゲット	target: 'node18'	ES または Node のバージョン
プラットフォーム	platform: 'node'	node、browser、または neutral
圧縮	minify: true	ツリーシェイキングは別途有効化
ツリーシェイキング	treeshake: true	デッドコードを削除
ソースマップ	sourcemap: true	インラインまたは外部ソースマップ
ウォッチモード	tsdown --watch	ファイル変更時に自動で再ビルド
出力のクリーンアップ	clean: true	ビルド前に出力ディレクトリを削除
検証	--publint --attw	ビルド後にパッケージの品質をチェック
サイズレポート	--report	gzip/brotli の統計情報付きでバンドルサイズを表示
複数の設定	defineConfig([...])	出力ごとに設定の配列を指定
動的な設定	defineConfig((opts) => {})	CLI オプションを受け取る関数
プログラム API	import { build }	Node.js スクリプトで使用
バナー／フッター	banner: { js: '...' }	出力ファイルの先頭／末尾に追加
onSuccess フック	onSuccess: async () => {}	ビルド成功後に実行
Node プロトコル	nodeProtocol: true	組み込みモジュールのインポートに node: プレフィックスを追加／削除

よくある間違い

間違い	正しい設定
2つの形式で公開する際に fixedExtension を設定しない	ESM と CJS の両方を公開する場合は、.mjs/.cjs に fixedExtension: true を使用します
すべての node_modules をライブラリの出力にバンドルする	依存関係はデフォルトで外部化されます。特定の依存関係にのみ noExternal を使用します
TypeScript を設定せずに dts: true を使用する	適切な compilerOptions を含む tsconfig.json があることを確認します
モダンな構文に対して target を低く設定しすぎる	サポートする Node／ブラウザーの最低バージョンに合わせて target を設定します
package.json に types フィールドがない	宣言ファイルを解決できるよう、types または exports の types 条件を追加します
出力形式を変更する前に出力先をクリーンアップしない	前回のビルドの古いファイルを残さないよう、clean: true を使用します
Node の組み込みモジュールを external にインラインで指定する	Node の組み込みモジュール（node:fs など）は、platform: 'node' では自動的に外部化されます
CI で対話型 CLI フラグを使用する	CI ビルドには設定ファイルまたは非対話型 CLI フラグを使用します

委任

• ビルド設定のレビュー：Task エージェントを使用して、tsdown の設定が正しいか分析します
• パッケージの公開：Explore エージェントを使用して、package.json の exports フィールドと types フィールドを確認します
• tsup からの移行：Task エージェントを使用して、tsup のオプションを tsdown の相当するオプションに対応付けます

参考資料

• 設定：設定ファイル、エントリーポイント、出力形式、target、platform、外部依存関係
• 宣言ファイル：DTS の生成、分離宣言、型のバンドル
• 高度な機能：プラグイン、コード分割、ツリーシェイキング、ウォッチモード、検証