はじめに：なぜ Nuxt Kit で Vite 設定にアクセスするのか？

Nuxt 3 では Vite がデフォルトのビルドツールとして採用されており、開発体験やビルド速度の向上に大きく貢献しています。しかし、プラグイン開発や高度なカスタマイズを行う際には、Vite の内部設定に直接アクセスしたいケースが出てきます。
Nuxt Kit ユーティリティは、こうしたニーズに応えるために用意された API で、Nuxt のランタイム環境から Vite や webpack の設定を抽出・操作できるように設計されています。

この補足記事では、Nuxt Kit を使って Vite 設定にアクセスする具体的な方法と、実務での活用例、注意すべきポイントを丁寧に解説します。

まず結論：Nuxt Kit で Vite 設定にアクセスするポイント

• loadNuxt と buildNuxt を使って Nuxt インスタンスをプログラム的に読み込み・ビルドする
• nuxt.hook('vite:extendConfig', callback) で Vite のクライアント設定を取得可能
• フック内で設定を受け取ったら例外を投げてビルドを中断し、不要な処理を防ぐテクニックが有効
• SSR とクライアントの設定を区別して取得できるため、用途に応じて使い分ける
• webpack 設定も同様のフックでアクセス可能（webpack:extendConfig）

いつ使うべきか？使わない方がよいケースは？

使うべきケース

• Nuxt プロジェクトのビルド設定をプログラム的に解析・変更したいとき
• Nuxt プラグインやモジュール開発で、Vite の詳細設定を参照・拡張したい場合
• CI/CD やカスタムビルドパイプラインで、Nuxt のビルド設定を動的に取得したいとき
• 他のツールやライブラリと連携し、Vite 設定を共有・同期したい場合

使わない方がよいケース

• 単純な設定変更やカスタマイズは nuxt.config で済む場合（過度な複雑化を避ける）
• ランタイムでの動的変更が不要な場合（ビルド時に完結する設定は静的に管理したほうが安全）
• Nuxt の内部 API に依存するため、将来的な互換性リスクを考慮すべきプロダクション環境での多用

実務でよくあるユースケースとサンプルコード

1. Vite のクライアント設定を取得してカスタムプラグインに渡す

Nuxt モジュール開発時に、Vite の設定を取得して独自の Vite プラグインに設定を反映させる例です。

import { loadNuxt, buildNuxt } from '@nuxt/kit'

async function getClientViteConfig() {
  const nuxt = await loadNuxt({ cwd: process.cwd(), dev: false, overrides: { ssr: false } })
  return new Promise((resolve, reject) => {
    nuxt.hook('vite:extendConfig', (config, { isClient }) => {
      if (isClient) {
        resolve(config)
        throw new Error('_stop_') // ビルド中断用
      }
    })
    buildNuxt(nuxt).catch((err) => {
      if (!err.toString().includes('_stop_')) {
        reject(err)
      }
    })
  }).finally(() => nuxt.close())
}

getClientViteConfig().then(config => {
  console.log('Vite client config:', config)
  // ここでカスタムプラグインに設定を渡すなどの処理を行う
})

2. SSR とクライアントの設定を分けて取得し、環境ごとに最適化

SSR とクライアントで異なる Vite 設定を取得し、環境ごとに最適化処理を行う例。

async function getViteConfigs() {
  const nuxt = await loadNuxt({ cwd: process.cwd(), dev: false })
  const configs = { client: null, ssr: null }

  return new Promise((resolve, reject) => {
    nuxt.hook('vite:extendConfig', (config, { isClient }) => {
      if (isClient) {
        configs.client = config
      } else {
        configs.ssr = config
      }
      if (configs.client && configs.ssr) {
        resolve(configs)
        throw new Error('_stop_')
      }
    })
    buildNuxt(nuxt).catch((err) => {
      if (!err.toString().includes('_stop_')) {
        reject(err)
      }
    })
  }).finally(() => nuxt.close())
}

getViteConfigs().then(({ client, ssr }) => {
  console.log('Client config:', client)
  console.log('SSR config:', ssr)
})

3. CI/CD パイプラインでビルド前に設定を検証・ログ出力

ビルド前に Vite 設定を取得して、CI/CD のログに出力し問題を早期発見する用途。

async function validateViteConfig() {
  const config = await getClientViteConfig()
  // ここで設定の検証やログ出力を行う
  if (!config.plugins) {
    throw new Error('Vite plugins are missing!')
  }
  console.log('Vite config validated successfully.')
}

よくある落とし穴・注意点

1. ビルド中断のための例外処理

nuxt.hook('vite:extendConfig') 内で設定を取得したら、ビルドを続行しないために例外を投げるテクニックがよく使われます。
ただし、この例外は必ず特定の文字列（例: _stop_）を含めて判別し、他のエラーと混同しないようにしましょう。

2. SSR と CSR の設定の違いに注意

Vite の設定は SSR（サーバーサイドレンダリング）用とクライアント用で異なる場合があります。
用途に応じて isClient フラグを使い分け、適切な設定を取得してください。

3. パフォーマンスへの影響

loadNuxt と buildNuxt は内部的に Nuxt のビルドプロセスを起動するため、処理に時間がかかります。
頻繁に呼び出すのは避け、必要なときだけ実行するようにしましょう。

4. Nuxt の内部 API 依存による将来の互換性リスク

Nuxt Kit の API は強力ですが、Nuxt のバージョンアップに伴い仕様変更が起こる可能性があります。
プロダクション環境での多用は慎重に検討し、バージョン管理やテストを徹底してください。

まとめ

Nuxt Kit ユーティリティを使うことで、Nuxt のランタイムから Vite 設定をプログラム的に取得・操作できるようになります。
これにより、プラグイン開発やカスタムビルドパイプラインの構築が柔軟かつ強力に行えます。
ただし、ビルド中断の例外処理や SSR/CSR の設定差分、パフォーマンス面の注意点を理解した上で活用することが重要です。

Nuxt の公式ドキュメントだけでは触れきれない実務的なポイントを押さえ、より高度な Nuxt 開発に役立ててください。