unbuild の使い方 — ゼロコンフィグで動く統合JavaScriptビルドシステム

一言でいうと

unbuild は、package.json の情報から自動的にビルド設定を推論し、CommonJS / ESM の両形式 + 型定義ファイルを生成してくれる統合ビルドシステムです。内部では Rollup を使いつつ、設定ファイルをほぼ書かずにライブラリのビルドが完結します。

どんな時に使う？

1. npm パッケージ（ライブラリ）を公開したい — CJS/ESM のデュアルフォーマット + .d.ts を一発で生成したい場合に最適です
2. ビルド設定を極力書きたくない — package.json の exports / main / types フィールドからエントリポイントや出力形式を自動推論してくれます
3. 開発中にビルドの待ち時間をなくしたい — --stub モードを使えば、dist をスタブ化して jiti 経由でソースを直接読み込むため、watch & rebuild が不要になります

インストール

# npm
npm install -D unbuild

# yarn
yarn add -D unbuild

# pnpm
pnpm add -D unbuild

基本的な使い方

1. ソースファイルを作成

// src/index.ts
export const greet = (name: string): string => {
  return `Hello, ${name}!`;
};

2. package.json を設定

{
  "name": "my-library",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "build": "unbuild",
    "prepack": "unbuild"
  },
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  },
  "main": "./dist/index.cjs",
  "types": "./dist/index.d.ts",
  "files": ["dist"]
}

3. ビルド実行

npx unbuild

これだけで dist/ に以下が生成されます：

• dist/index.mjs — ESM 形式
• dist/index.cjs — CommonJS 形式
• dist/index.d.ts — 型定義ファイル
• dist/index.d.mts / dist/index.d.cts — 各形式用の型定義

設定ファイルは不要です。 package.json の exports や main フィールドからエントリポイントと出力形式が自動推論されます。

よく使うAPI・設定

1. defineBuildConfig — 型安全な設定定義

より細かい制御が必要な場合は build.config.ts を作成します。

// build.config.ts
import { defineBuildConfig } from "unbuild";

export default defineBuildConfig({
  entries: ["./src/index"],
  outDir: "dist",
  declaration: true,
});

2. mkdist ビルダー — ファイル単位のトランスパイル

バンドルせずにファイル構造を維持したまま変換したい場合（コンポーネントライブラリなど）に使います。

// build.config.ts
import { defineBuildConfig } from "unbuild";

export default defineBuildConfig({
  entries: [
    {
      builder: "mkdist",
      input: "./src/components/",
      outDir: "./dist/components",
    },
  ],
  declaration: true,
});

3. --stub モード — 開発時のパッシブウォッチャー

npx unbuild --stub

dist/ にスタブファイルが生成され、実行時に jiti を通じてソースコードが直接読み込まれます。npm link や monorepo でのローカル開発時に、ビルドし直す必要がなくなります。

// スタブ実行後の dist/index.mjs の中身（イメージ）
// jiti 経由で src/index.ts を直接 import するコードが生成される

4. 複数ビルド設定 — 配列で定義

通常ビルドと minify ビルドなど、複数の出力を同時に生成できます。

// build.config.ts
import { defineBuildConfig } from "unbuild";

export default defineBuildConfig([
  {
    entries: ["./src/index"],
    outDir: "dist",
    declaration: "compatible",
  },
  {
    name: "minified",
    entries: ["./src/index"],
    outDir: "dist/min",
    rollup: {
      esbuild: {
        minify: true,
      },
    },
  },
]);

5. declaration オプション — 型定義生成の制御

import { defineBuildConfig } from "unbuild";

export default defineBuildConfig({
  entries: ["./src/index"],

  // "compatible": .d.ts + .d.mts + .d.cts を全て生成（最大互換性）
  // "node16":     .d.mts + .d.cts のみ生成
  // true:         "compatible" と同等
  // false:        型定義を生成しない
  // undefined:    package.json の types フィールドから自動判定
  declaration: "compatible",
});

補足: ソースマップ生成・デコレータ対応

import { defineBuildConfig } from "unbuild";

export default defineBuildConfig({
  // ソースマップ生成
  sourcemap: true,

  // デコレータサポート
  rollup: {
    esbuild: {
      tsconfigRaw: {
        compilerOptions: {
          experimentalDecorators: true,
        },
      },
    },
  },
});

類似パッケージとの比較

tsup はシンプルさと速度のバランスが良く、unbuild は package.json からの自動推論とスタブモードが強みです。Nuxt / unjs エコシステムのライブラリは基本的に unbuild を採用しています。

注意点・Tips

package.json の exports フィールドが設定の要

unbuild は exports、main、module、types フィールドを読み取ってビルドを構成します。これらが正しく設定されていないと、期待通りの出力が得られません。

{
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    },
    "./utils": {
      "import": "./dist/utils.mjs",
      "require": "./dist/utils.cjs"
    }
  }
}

外部依存の扱い

dependencies に記載されたパッケージは自動的に external 扱い（バンドルに含めない）になります。devDependencies のみに記載されたパッケージをソースで使っていると、ビルド時に missing dependency の警告が出ます。これは意図的な安全機構です。

--stub モードは開発専用

スタブモードは jiti による動的トランスパイルに依存するため、パフォーマンスは本番ビルドに劣ります。公開前には必ず unbuild（スタブなし）で正式ビルドを行ってください。prepack スクリプトに設定しておくと安心です。

設定ファイルの配置場所

build.config.ts 以外にも build.config.{js,cjs,mjs,mts,cts,json} や package.json の "unbuild" キーが使えます。TypeScript で書く場合は build.config.ts が型補完も効いて最も快適です。

obuild への移行について

⚠️ v3.6.1 時点の情報です

README にある通り、rolldown ベースの後継ツール obuild が実験的に開発されています。ビルド速度を重視する場合は検討の余地がありますが、現時点ではベータ段階のため、プロダクション利用には unbuild が安定した選択肢です。

まとめ

unbuild は「package.json を正しく書けばビルド設定は不要」という思想のもと、ライブラリ開発に必要な CJS/ESM デュアル出力・型定義生成・依存関係チェックをワンコマンドで実現するビルドツールです。特にスタブモードによる開発体験の向上は他のツールにない大きな強みです。Nuxt / unjs エコシステムに限らず、npm パッケージを公開するあらゆるプロジェクトで検討する価値があります。