tsdown

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

Rolldown と Oxc を基盤とする、TypeScript／JavaScript ライブラリ向けの超高速バンドラーです。

実行環境の要件

tsdown の実行には Node.js 22.18.0 以降が必要です（ビルド時のみ）。ただし、target オプションを使って、バンドル出力の対象をはるかに古い Node.js バージョンに設定できます。そのため、tsdown でビルドしたライブラリは、実行時に Node.js 22 以降に限定されるわけではありません。

パッケージで Node.js 18／20 をサポートする必要がある場合：

• CI では Node.js 22 以降を使ってビルドします（例：target: 'node18' または target: 'node20' を設定します）。
• サポート対象とする古い Node.js バージョンで、ビルド済みの出力（またはパッケージ化した tarball）をテストします。たとえば、公開済みパッケージのテストを Node.js 18／20／22 で実行するマトリックスジョブを使用します。

使用する場面

• npm 向けの TypeScript／JavaScript ライブラリのビルド
• TypeScript 宣言ファイル（.d.ts）の生成
• 複数の形式（ESM、CJS、IIFE、UMD）へのバンドル
• ツリーシェイキングとミニファイによるバンドルの最適化
• 最小限の変更で tsup から移行
• React、Vue、Solid、Svelte コンポーネントライブラリのビルド

クイックスタート

# Install
pnpm add -D tsdown

# Basic usage
npx tsdown

# With config file
npx tsdown --config tsdown.config.ts

# Watch mode
npx tsdown --watch

# Migrate from 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

オプションの対応表を含む包括的な移行支援については、専用の tsdown-migrate スキルをインストールしてください：npx skills add rolldown/tsdown --skill tsdown-migrate | フック | 独自のロジックを実装するライフサイクルフック | 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: true - ESM／CJS 互換性を追加します	option-shims
CJS のデフォルト	cjsDefault: true（デフォルト）／false	option-cjs-default
パッケージのエクスポート	exports: true - exports フィールドを生成します	option-package-exports
CSS の処理	[experimental] css: { ... } — プリプロセッサー、Lightning CSS、PostCSS、CSS モジュール、コード分割を含む完全なパイプラインです。@tsdown/css が必要です	option-css
CSS モジュール	css: { modules: { localsConvention: 'camelCase' } } — .module.css ファイルのスコープ付きクラス名です	option-css
CSS の注入	css: { inject: true } — JS 出力で CSS インポートを保持します	option-css
アンバンドルモード	unbundle: true - ディレクトリ構造を保持します	option-unbundle
ルートディレクトリ	root: 'src' - 出力ディレクトリのマッピングを制御します	option-root
実行可能ファイル	[experimental] 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, // Preserve file structure
  format: ['esm'],
  dts: true,
})

CI を考慮した設定

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  failOnWarn: 'ci-only',  // opt-in: fail on warnings in 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,
  }
})

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

複数のパッケージをビルドするには、glob パターンを使用します。

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

CLI クイックリファレンス

# Basic commands
tsdown                          # Build once
tsdown --watch                  # Watch mode
tsdown --config custom.ts       # Custom config
npx tsdown-migrate              # Migrate from tsup

# Output options
tsdown --format esm,cjs        # Multiple formats
tsdown -d lib                  # Custom output directory (--out-dir)
tsdown --minify                # Enable minification
tsdown --dts                   # Generate declarations
tsdown --exe                   # Bundle as standalone executable
tsdown --unbundle              # Bundleless mode

# Entry options
tsdown src/index.ts            # Single entry
tsdown src/*.ts                # Glob patterns
tsdown src/a.ts src/b.ts       # Multiple entries

# Workspace / Monorepo
tsdown -W                      # Enable workspace mode
tsdown -W -F my-package        # Filter specific package
tsdown --filter /^pkg-/        # Filter by regex

# Development
tsdown --watch                 # Watch mode
tsdown --sourcemap             # Generate source maps
tsdown --clean                 # Clean output directory
tsdown --from-vite             # Reuse Vite config
tsdown --tsconfig tsconfig.build.json  # Custom tsconfig

ベストプラクティス

1. TypeScript ライブラリでは、必ず型宣言を生成します。

   { dts: true }
   

2. 不要なコードのバンドルを避けるため、依存関係を外部化します。

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

3. バンドルサイズを最適化するため、ツリーシェイキングを使用します。

   { treeshake: true }
   

4. 本番ビルドでは、圧縮を有効にします。

   { minify: true }
   

5. ESM/CJS との互換性を高めるため、シムを追加します。

   { shims: true }  // Adds __dirname, __filename, etc.
   

6. package.json の exports を自動生成します。

   { exports: true }  // Creates proper exports field
   

7. 開発中は、ウォッチモードを使用します。

   tsdown --watch
   

8. ファイル数の多いユーティリティでは、構造を維持します。

   { unbundle: true }  // Keep directory structure
   

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