Astro v5のエイリアス解決に対応するため、`config.createResolver`へのフォールバックを実装

@tailwindcss/viteで、Vite Environment APIが利用可能な環境でもconfig.createResolverを適切にフォールバックするようになりました。これにより、Astro v5のようにEnvironment APIとレガシーなリゾルバの両方が混在する環境で、インポートエイリアスが正常に動作するようになります。

背景

Astro v5では、Vite Environment APIが利用可能なバージョンを使用している一方で、内部的にはconfig.createResolverをオーバーライドしてカスタムエイリアスを注入しています。Vite 7.0.0でconfig.createResolverは正式に非推奨となりましたが、それ以前のバージョンでは技術的に有効な手法でした。#19677は、この混在状況でTailwindのインポートエイリアスが機能しなくなる問題を報告しています。

@tailwindcss/viteは、Environment APIが利用可能な場合はvite.createIdResolver()を使用し、そうでない場合はconfig.createResolver()を使用する実装でした。しかし、Astro v5のように両方が存在する環境では、Environment APIの存在によりconfig.createResolver()が呼ばれず、Astroが設定したエイリアスが無視される問題が発生していました。

技術的な変更

packages/@tailwindcss-vite/src/index.tsに、Vite内部で使用されているcreateBackCompatIdResolver()関数が追加されました。この関数は、Environment名に応じて適切なリゾルバを選択します。

変更前:

// Newer Vite versions
let cssResolver = vite.createIdResolver(env.config, {
  // ...
});

変更後:

function createBackCompatIdResolver(
  config: ResolvedConfig,
  options?: Partial<InternalResolveOptions>,
): ResolveIdFn {
  const compatResolve = config.createResolver(options)
  let resolve: ResolveIdFn
  return async (environment, id, importer, aliasOnly) => {
    if (environment.name === 'client' || environment.name === 'ssr') {
      return compatResolve(id, importer, aliasOnly, environment.name === 'ssr')
    }
    resolve ??= vite.createIdResolver(config, options)
    return resolve(environment, id, importer, aliasOnly)
  }
}

let cssResolver = createBackCompatIdResolver(env.config, {
  // ...
});

createBackCompatIdResolver()は、Environment名が'client'または'ssr'の場合にconfig.createResolver()を優先的に使用します。それ以外のEnvironmentでは、代わりにvite.createIdResolver()が使用されます。この判定により、Astro v5のような環境でも正しくエイリアスが解決されます。

統合テストintegrations/vite/astro.test.tsには、tsconfig.jsonでエイリアスを定義し、Astroの<style>ブロック内で@referenceディレクティブを使用するケースが追加されました。

'tsconfig.json': json`
  {
    "compilerOptions": {
      "paths": {
        "@styles/*": ["./src/styles/*"]
      }
    }
  }
`,

このテストケースは、#19677で報告された問題を再現し、修正が有効であることを検証します。

設計判断

Viteの内部実装をコピーする方式が採用されました。

PR本文では、Vite自身が内部的にこのフォールバックロジックを使用しているものの、公開APIとして提供していないことが述べられています。createBackCompatIdResolver()関数はViteのソースコードから直接コピーされ、必要な調整が加えられています。関数内のコメントでも「Copied as-is from vite」と明示されています。

clientとssrという特定のEnvironment名に依存する判定ロジックは、Viteの標準的なEnvironment命名規則に基づいています。vitejs/vite#20031でconfig.createResolverが正式に非推奨となったことを踏まえ、将来的にVite 7未満のサポートを終了する際には、この関数を削除する予定がコメントに記載されています。

まとめ

本PRは、Environment APIとレガシーなリゾルバAPIが混在する環境での互換性問題を解決しています。Viteの内部実装を活用することで、Astro v5のようなフレームワークが設定するカスタムエイリアスを正しく解決できるようになりました。Vite 7への移行期における実用的な対応として、既存のエコシステムとの互換性を保ちつつ、新しいAPIへの移行を支援する設計判断が反映されています。