`Config`型のTS2742エラーをtype aliasからinterfaceへの変更で解消

2026年04月30日 03:48 JST tailwindlabs/tailwindcss

https://github.com/tailwindlabs/tailwindcss/pull/19707

Tailwind CSS v4でConfig型を使うプロジェクトをTypeScriptでビルドすると発生していたTS2742エラーが、export type Config = UserConfigをexport interface Config extends UserConfig {}に変更することで解消されました。

背景

tailwindcssパッケージのConfig型は、内部でハッシュ付きファイル名（例: types-CJYAW1ql.d.mts）にバンドルされたUserConfig型へのtype aliasとして定義されていました。TypeScriptは宣言ファイル（.d.ts）の生成時にtype aliasを解決し、その元の型まで遡ります。そのため、Config型を返す関数のエクスポートを推論させると、TypeScriptはハッシュ付きの非公開パスを参照しようとし、「A type annotation is necessary」というTS2742エラーを発生させていました。

Issue #19706では、function defineConfig(config: Config): Config { return config; }のエクスポートでこのエラーが再現することが報告されています。また、同様の問題はIssue #15844でtailwindcss/pluginの型についても報告されており、今回はメインのtailwindcssエントリーポイントとtailwindcss/pluginの両方に対して修正が適用されています。

技術的な変更

Config型の定義方式をtype aliasからinterfaceに変更し、PluginWithConfig型をtailwindcss/pluginのエクスポートに追加することで、TS2742エラーが解消されています。

packages/tailwindcss/src/index.tsでのコア修正は次の通りです。

変更前:

export type Config = UserConfig

変更後:

export interface Config extends UserConfig {}

type aliasはTypeScriptの宣言emit時に元の型まで透過的に解決されますが、interfaceは独立した型として扱われます。interface Config extends UserConfig {}とすることで、ConfigはUserConfigと構造的に同一でありながら、TypeScriptがdeclaration emitの際にそのままConfigという名前で参照できるようになります。

packages/tailwindcss/src/plugin.tsでは、これまでエクスポートされていなかったPluginWithConfig型が追加されました。

export type {
  PluginFn as PluginCreator,
  Plugin as PluginsConfig,
  PluginUtils,
+ PluginWithConfig,
  ThemeConfig,
}

この変更により、プラグインのエクスポート時に型が内部ハッシュファイルへの参照を経由せずに解決されるようになります。あわせて、Issue #15844と#19706の両ケースを再現するインテグレーションテストがintegrations/cli/plugins.test.tsおよびintegrations/cli/config.test.tsに追加されています。

設計判断

type aliasをinterfaceに置き換えるという手法が採用されています。PRの説明には「type aliasとinterfaceは構造的に比較可能であるため、100%後方互換性がある」と明記されています。TypeScriptの構造的型付けにより、Configを期待する箇所にUserConfigを渡すコードもその逆も、引き続き型エラーなく動作します。

アプローチとしては、Configの定義をUserConfigの単純な別名としてではなく、独立した名前付き型として宣言することで、TypeScriptのdeclaration emitが安定した公開パス（tailwindcss）を通じて型を参照できるようにしています。これは内部バンドルのハッシュ戦略を変えることなく、型のエクスポート境界を明確にする最小限の修正です。

まとめ

type aliasがdeclaration emit時に非公開の内部ファイルへ解決されるというTypeScriptの挙動に起因するTS2742は、export interface Config extends UserConfig {}という一行の変更で解消されます。公開APIの動作には影響を与えず、TypeScriptを使ってTailwind CSS設定ファイルやプラグインをビルドするすべてのユーザーに恩恵をもたらす修正です。