tsdown - エレガントなライブラリバンドラー

Rolldown と Oxc によるパワフルな、超高速の TypeScript/JavaScript ライブラリバンドラー。

使用場面

• npm 用の TypeScript/JavaScript ライブラリ構築
• TypeScript 宣言ファイル (.d.ts) の生成
• 複数フォーマット (ESM, CJS, IIFE, UMD) へのバンドル
• ツリーシェイキングとミニフィケーションによるバンドル最適化
• tsup からの最小限の変更での移行
• React、Vue、Solid、Svelte コンポーネントライブラリの構築

クイックスタート

# インストール
pnpm add -D tsdown

# 基本的な使い方
npx tsdown

# 設定ファイル付き
npx tsdown --config tsdown.config.ts

# ウォッチモード
npx tsdown --watch

# tsup からの移行
npx tsdown-migrate

基本設定

import { defineConfig } from 'tsdown'

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

コアリファレンス

トピック	説明	リファレンス
はじめに	インストール、初めてのバンドル、CLI の基本	guide-getting-started
設定ファイル	設定ファイル形式、複数設定、ワークスペース	option-config-file
CLI リファレンス	すべての CLI コマンドとオプション	reference-cli
tsup からの移行	移行ガイドと互換性に関する注記	guide-migrate-from-tsup
プラグイン	Rolldown、Rollup、Unplugin サポート	advanced-plugins
フック	カスタムロジック用のライフサイクルフック	advanced-hooks
プログラマティック API	Node.js スクリプトからのビルド	advanced-programmatic
Rolldown オプション	Rolldown に直接オプションを渡す	advanced-rolldown-options
CI 環境	CI 検出、'ci-only' / 'local-only' 値	advanced-ci

ビルドオプション

オプション	使用方法	リファレンス
エントリーポイント	entry: ['src/*.ts', '!**/*.test.ts']	option-entry
出力フォーマット	format: ['esm', 'cjs', 'iife', 'umd']	option-output-format
出力ディレクトリ	outDir: 'dist'、outExtensions	option-output-directory
型宣言	dts: true、dts: { sourcemap, compilerOptions, vue }	option-dts
ターゲット環境	target: 'es2020'、target: 'esnext'	option-target
プラットフォーム	platform: 'node'、platform: 'browser'	option-platform
ツリーシェイキング	treeshake: true、カスタムオプション	option-tree-shaking
ミニフィケーション	minify: true、minify: 'dce-only'	option-minification
ソースマップ	sourcemap: true、'inline'、'hidden'	option-sourcemap
ウォッチモード	watch: true、ウォッチオプション	option-watch-mode
クリーニング	clean: true、クリーンパターン	option-cleaning
ログレベル	logLevel: 'silent'、failOnWarn: false	option-log-level

依存関係の処理

機能	使用方法	リファレンス
バンドルしない	deps: { neverBundle: ['react', /^@myorg\//] }	option-dependencies
常にバンドル	deps: { alwaysBundle: ['dep-to-bundle'] }	option-dependencies
バンドルのみ	deps: { onlyBundle: ['cac', 'bumpp'] } - ホワイトリスト	option-dependencies
node_modules をスキップ	deps: { skipNodeModulesBundle: true }	option-dependencies
自動外部化	ピア/依存関係の自動外部化	option-dependencies

出力強化

機能	使用方法	リファレンス
Shims	shims: true - ESM/CJS 互換性を追加	option-shims
CJS デフォルト	cjsDefault: true (デフォルト) / false	option-cjs-default
パッケージエクスポート	exports: true - exports フィールドを自動生成	option-package-exports
CSS 処理	[実験的] css: { ... } — プリプロセッサー、Lightning CSS、PostCSS、コード分割を備えた完全なパイプライン; @tsdown/css が必要	option-css
CSS インジェクト	css: { inject: true } — JS 出力に CSS インポートを保持	option-css
アンバンドルモード	unbundle: true - ディレクトリ構造を保持	option-unbundle
ルートディレクトリ	root: 'src' - 出力ディレクトリマッピングを制御	option-root
実行可能ファイル	[実験的] exe: true - スタンドアロン実行可能ファイルとしてバンドル、@tsdown/exe でクロスプラットフォーム対応	option-exe
パッケージ検証	publint: true、attw: true - パッケージを検証	option-lint

フレームワークとランタイムのサポート

フレームワーク	ガイド	リファレンス
React	JSX 変換、React Compiler	recipe-react
Vue	SFC サポート、JSX	recipe-vue
Solid	SolidJS JSX 変換	recipe-solid
Svelte	Svelte コンポーネントライブラリ (ソース配布推奨)	recipe-svelte
WASM	rolldown-plugin-wasm 経由の WebAssembly モジュール	recipe-wasm

よくあるパターン

基本的なライブラリバンドル

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

複数のエントリーポイント

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

ブラウザライブラリ (IIFE/UMD)

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['iife'],
  globalName: 'MyLib',
  platform: 'browser',
  minify: true,
})

React コンポーネントライブラリ

export default defineConfig({
  entry: ['src/index.tsx'],
  format: ['esm', 'cjs'],
  dts: true,
  deps: {
    neverBundle: ['react', 'react-dom'],
  },
  inputOptions: {
    jsx: { runtime: 'automatic' },
  },
})

ディレクトリ構造を保持

export default defineConfig({
  entry: ['src/**/*.ts', '!**/*.test.ts'],
  unbundle: true, // ファイル構造を保持
  format: ['esm'],
  dts: true,
})

CI 対応設定

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  failOnWarn: 'ci-only',  // オプトイン: CI での警告で失敗
  publint: 'ci-only',
  attw: 'ci-only',
})

WASM サポート

import { wasm } from 'rolldown-plugin-wasm'
import { defineConfig } from 'tsdown'

export default defineConfig({
  entry: ['src/index.ts'],
  plugins: [wasm()],
})

CSS と Sass 付きライブラリ

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  target: 'chrome100',
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `@use "src/styles/variables" as *;`,
      },
    },
  },
})

スタンドアロン実行可能ファイル

export default defineConfig({
  entry: ['src/cli.ts'],
  exe: true,
})

クロスプラットフォーム実行可能ファイル (@tsdown/exe が必要)

export default defineConfig({
  entry: ['src/cli.ts'],
  exe: {
    targets: [
      { platform: 'linux', arch: 'x64', nodeVersion: '25.7.0' },
      { platform: 'darwin', arch: 'arm64', nodeVersion: '25.7.0' },
      { platform: 'win', arch: 'x64', nodeVersion: '25.7.0' },
    ],
  },
})

フック付き高度な設定

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  hooks: {
    'build:before': async (context) => {
      console.log('Building...')
    },
    'build:done': async (context) => {
      console.log('Build complete!')
    },
  },
})

設定機能

複数の設定

複数のビルド設定にはアレイをエクスポート:

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

条件付き設定

動的な設定にはファンクションを使用:

export default defineConfig((options) => {
  const isDev = options.watch
  return {
    entry: ['src/index.ts'],
    format: ['esm', 'cjs'],
    minify: !isDev,
    sourcemap: isDev,
  }
})

ワークスペース/モノレポ

複数のパッケージを構築するにはグロブパターンを使用:

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

CLI クイックリファレンス

# 基本コマンド
tsdown                          # 1 回ビルド
tsdown --watch                  # ウォッチモード
tsdown --config custom.ts       # カスタム設定
npx tsdown-migrate              # tsup から移行

# 出力オプション
tsdown --format esm,cjs        # 複数フォーマット
tsdown -d lib                  # カスタム出力ディレクトリ (--out-dir)
tsdown --minify                # ミニフィケーション有効化
tsdown --dts                   # 宣言ファイル生成
tsdown --exe                   # スタンドアロン実行可能ファイルでバンドル
tsdown --unbundle              # バンドルレスモード

# エントリーオプション
tsdown src/index.ts            # 単一エントリー
tsdown src/*.ts                # グロブパターン
tsdown src/a.ts src/b.ts       # 複数エントリー

# ワークスペース / モノレポ
tsdown -W                      # ワークスペースモード有効化
tsdown -W -F my-package        # 特定パッケージをフィルター
tsdown --filter /^pkg-/        # 正規表現でフィルター

# 開発
tsdown --watch                 # ウォッチモード
tsdown --sourcemap             # ソースマップ生成
tsdown --clean                 # 出力ディレクトリをクリーン
tsdown --from-vite             # Vite 設定を再利用
tsdown --tsconfig tsconfig.build.json  # カスタム tsconfig

ベストプラクティス

1. TypeScript ライブラリ用の型宣言を常に生成:

   { dts: true }
   

2. 依存関係を外部化して不要なコードのバンドルを回避:

   { deps: { neverBundle: [/^react/, /^@myorg\//] } }
   

3. ツリーシェイキングを使用して最適なバンドルサイズを実現:

   { treeshake: true }
   

4. 本番ビルド用にミニフィケーション有効化:

   { minify: true }
   

5. ESM/CJS 互換性向上のため Shims を追加:

   { shims: true }  // __dirname、__filename などを追加
   

6. package.json exports を自動生成:

   { exports: true }  // 適切な exports フィールドを生成
   

7. 開発中は ウォッチモード を使用:

   tsdown --watch
   

8. 多くのファイルを含むユーティリティ向けに構造を保持:

   { unbundle: true }  // ディレクトリ構造を保持
   

9. 公開前に CI でパッケージを検証:

   { publint: 'ci-only', attw: 'ci-only' }
   

リソース

• ドキュメント: https://tsdown.dev
• GitHub: https://github.com/rolldown/tsdown
• Rolldown: https://rolldown.rs
• 移行ガイド: https://tsdown.dev/guide/migrate-from-tsup