`@tailwindcss/vite`でSourcemapの警告が出ていた問題を修正

@tailwindcss/viteのtransformフックで、Tailwind CSSのルートファイルでないCSSを処理した際に src をそのまま返していたことが原因で、Sourcemap is likely to be incorrect 警告が大量に出力されていました。変更を加えなかった場合は undefined を返すよう修正し、不要な警告を解消します。

背景

Viteのtransformフックには、変更なしを示すための仕様があります。モジュールのソースを変更しなかった場合、undefined（またはその他のnull値）を返すことでViteに「何も変わっていない」と伝えられます。逆に、変更前と同じ文字列を返してしまうと、ViteはSourcemapの連鎖（sourcemap chain）を照合しようとして不整合を検出し、警告を発します。

#19930では、@tailwindcss/vite@4.2.2 と Nuxt 4.4.2 / Vite 7.3.2 の組み合わせで、ビルド時に [plugin @tailwindcss/vite:generate:build] Sourcemap is likely to be incorrect ... という警告が繰り返し出力されることが報告されていました。この警告はCIログを汚染し、strict な警告ポリシーを採用しているプロジェクトではリリースブロッカーとして扱われるケースもありました。

@tailwindcss/viteのtransformフックは、処理対象のCSSファイルがTailwind CSSのルートファイル（@tailwind ディレクティブを持つファイル）かどうかを判定します。ルートでない場合はCSSを変換しないため、受け取った src をそのまま戻り値として返していましたが、これがViteの仕様に反していました。

技術的な変更

packages/@tailwindcss-vite/src/index.ts の serve・build 両フェーズのtransformハンドラで、result が偽値だった場合の戻り値を src から undefined（暗黙の return）に変更しました。

変更前（serve / build 共通パターン）:

let result = await root.generate(src, (file) => this.addWatchFile(file), I)
if (!result) {
  roots.delete(id)
  return src
}

変更後（serve / build 共通パターン）:

let result = await root.generate(src, (file) => this.addWatchFile(file), I)
if (!result) {
  roots.delete(id)
  return
}

差分としては2箇所（serveフェーズ: 241行目付近、buildフェーズ: 357行目付近）でそれぞれ return src を return に置き換えるだけの1行変更です。

あわせて、integrations/vite/source-maps.test.ts に再現テストが追加されました。テストでは、Tailwind CSSルートを持たないViteプロジェクトのproductionビルドを構成し、inspect-source-map-chain という名前のカスタムプラグインを挿入して getCombinedSourcemap() を呼び出すことで、Rollupがビルド中にsourcemapチェーンを強制的に解決するシナリオを再現しています。

設計判断

Viteのtransformフックにおけるnull返却規約を正しく遵守することが、この修正の核心です。Viteは transform の戻り値が null / undefined であれば「変換なし」と解釈し、sourcemapチェーンへの影響を発生させません。一方、同一の文字列を返した場合でも「変換あり」として扱い、前後のsourcemapとの照合を試みます。

この修正はTailwind CSSルートでないCSSファイルへの処理を変えるものではなく、Viteへの「変更なし」シグナルを正しく伝える点のみの修正です。roots.delete(id) による内部状態のクリーンアップは引き続き行われるため、動作上の副作用はありません。

まとめ

return src を return に変えるだけの2行の修正ですが、Viteのtransformフック仕様に対する正確な準拠により、Tailwind CSSルートを含まないプロジェクトやモジュールに対する不要なsourcemap警告を根本から除去できます。CIログのノイズ削減やstrict警告ポリシーへの対応として、実用的な影響の大きい修正です。