ただし、性能向上だけを見て移行すると、既存プロジェクトの構成で詰まる。tailwind.config.js は従来の前提ではなくなり、content の手動指定も不要になった。PostCSSの構成も変更されている。Tailwind v4の移行は、バージョン番号の更新ではない。ビルドパイプラインとデザイントークンの管理方法を置き換える作業である。
Rust製エンジンOxideが実現するビルド速度の向上
Tailwind CSS v4の変更点で最も分かりやすいのは、ビルド速度である。v4ではRust製の新しいエンジンが採用された。従来のJavaScript中心の処理から、より高速なネイティブ実装を利用する構成へ移行している。
公式発表では、フルビルドが最大5倍高速化された。インクリメンタルビルドでは最大100倍以上の高速化が示されている。変更がない状態の再ビルドでは、マイクロ秒単位の処理も報告されている。
ベンチマークの見方には注意が必要である。フルビルドとインクリメンタルビルドは、処理の性質が異なる。初回起動時の速度と、開発中に1ファイルを編集した後の速度を同じ指標で比較することはできない。
| 比較対象 | 主な処理 | v4で示されている改善 |
|---|---|---|
| フルビルド | プロジェクト全体からCSSを生成 | 最大5倍 |
| インクリメンタルビルド | 変更箇所を反映して再生成 | 最大100倍以上 |
| 変更なしの再ビルド | キャッシュや依存関係を確認 | マイクロ秒単位の処理例 |
| 構成変更後の初回ビルド | 新しい設定や依存関係を読み込み | プロジェクト構成に依存 |
一部のベンチマークでは、フルビルドで3.5倍から3.78倍以上の高速化も確認されている。ここで重要なのは、すべての環境で同じ倍率が出るという意味ではないことだ。CPU、ストレージ、プロジェクト規模、テンプレート数、プラグイン構成によって結果は変わる。
それでも、開発時の体感に影響しやすいのはインクリメンタルビルドである。LaravelのBladeテンプレートやVueコンポーネントを編集するたびにCSS生成が走る構成では、待ち時間が短くなるほど開発フローの中断が減る。
たとえば、変更処理が44ミリ秒から5ミリ秒になった例がある。変更がない場合は35ミリ秒から192マイクロ秒になった例も示されている。これは単純な数値差ではない。数回の編集では小さな差でも、画面調整を繰り返す開発では累積する。
Tailwind v4の高速化は、リリースビルドよりも、編集と確認を繰り返す開発サイクルで効果が出やすい。
ビルド速度だけで評価してはいけない
Tailwind CSS v4への移行を、単純な速度改善として判断するのは不十分である。設定ファイルの扱いが変わるため、既存のデザインシステムやビルド構成に影響する。
特に確認すべきなのは次の点である。
tailwind.config.jsに定義していたカラートークンやブレークポイントcontentに指定していたBlade、Vue、Reactなどのテンプレートパス- PostCSSに追加していたプラグイン
- ViteのCSS処理とTailwindの接続方法
- カスタムプラグインや独自ユーティリティの依存関係
高速化のメリットがあっても、移行後にテーマ変数が失われれば修正コストが発生する。速度と移行コストを分けて評価する必要がある。
tailwind.config.jsの廃止とCSS-first設計
[Tailwind CSS v3では、JavaScript設定ファイルがプロジェクトの中心だった。tailwind](/articles/abortcontrollergafei-tong/).config.js にテーマ、プラグイン、コンテンツパスなどを定義し、Tailwindがその設定を読み取ってCSSを生成する。
v4では、この構成が変更された。JavaScript設定ファイルとcontentパスの手動設定を前提にせず、CSSファイルの中でテーマを定義するCSS-first設計へ移行している。
たとえば、従来は設定ファイルにカラーパレットを定義していた。v4ではCSS内の@themeディレクティブでデザイントークンを記述する。設定の入口がJavaScriptからCSSへ移った形である。
ここでいうCSS-firstは、単にCSSへ記述場所を変えただけではない。テーマ定義と生成されるユーティリティの関係を、CSSの構文とカスタムプロパティで管理する設計である。
従来の構成では、設定ファイルとCSSファイルを別々に読む必要があった。デザイントークンを変更する場合、JavaScriptの設定を修正し、ビルド結果を確認する流れになる。v4では、CSS側でテーマを確認できる。デザインに関する定義が一つのファイルに集約されるため、依存関係を追いやすい。
一方で、JavaScriptから設定値を組み立てていたプロジェクトでは、移行時に設計を見直す必要がある。環境変数や外部JSONからテーマを生成していた場合、単純な置き換えでは対応できない可能性がある。
contentの手動設定が不要になった意味
v3では、Tailwindがどのファイルを解析するかをcontentに指定する必要があった。LaravelであればBlade、Vue、JavaScriptなどのパスを列挙する。指定漏れがあると、テンプレートで使用しているクラスがCSSに出力されない。
v4では、テンプレートファイルの自動検出が導入された。これにより、プロジェクトごとにパスを手動で記述する作業が減る。
これは設定ミスを減らす方向の変更である。ただし、自動検出がすべてのファイルや生成処理を無条件に理解するという意味ではない。クラス名を文字列連結で組み立てる実装は、v3と同様に問題になり得る。
たとえば、次のようなクラス指定は解析しにくい。
bg-${color}-500
Tailwindは実行時に生成された文字列を評価するフレームワークではない。ビルド時にテンプレートからクラス名を検出してCSSを生成する。そのため、クラス名が静的に存在しない場合は、CSSに出力されない可能性がある。
この問題はcontent設定の有無とは別である。v4で自動検出になっても、クラス名の生成方式そのものが変わるわけではない。
v3の設定をそのまま残す移行は避ける
v4ではJavaScript設定がCSS設定へ置き換わる。tailwind.config.jsを残したまま、v3と同じ運用を継続できると考えるのは危険である。
既存設定を移行する場合は、次の順序で内容を分解するとよい。
1. theme に定義している色、フォント、余白、ブレークポイントを洗い出す。
2. plugins に追加している独自機能を確認する。
3. content の対象ファイルを整理する。
4. CSS内の@themeへデザイントークンを移す。
5. 実際に使用しているクラスが生成されるか確認する。
6. 不要になったJavaScript設定と依存パッケージを削除する。
設定ファイルを機械的に移すのではなく、設定項目の役割を分解する必要がある。特にプラグインは、テーマ変数と同じ扱いにはできない。
@themeとCSSカスタムプロパティの関係
v4のCSS-first設計を理解するには、@themeの役割を把握する必要がある。@theme内で定義したデザイントークンは、標準のCSSカスタムプロパティとして出力される。
たとえば、ブランドカラーを--color-brandとして定義すると、その値はTailwindのユーティリティ生成だけでなく、CSSやHTML全体から参照できる。Tailwind固有の設定値が、ブラウザ標準のCSS変数へ接続される構造である。
この変更により、UIコンポーネントの設計が整理しやすくなる。Tailwindのクラスだけに色を閉じ込めず、CSS変数をデザインシステムの共通インターフェースとして扱える。
デザイントークンを一元化する
フロントエンドとバックエンドを分離した構成では、色や余白の定義が複数の場所に分散しやすい。
LaravelのBlade、Vue、React、WordPressのブロックテーマなどを同じデザイン方針で運用する場合、次のような重複が発生する。
- Tailwindのテーマ設定
- コンポーネント内の独自CSS
- JavaScript側の表示状態
- WordPress側のテーマ設定
- デザインツールから出力した値
@themeで管理する値をCSSカスタムプロパティとして公開すれば、少なくともブラウザ上のスタイル参照は統一できる。コンポーネントごとに異なる色コードを埋め込む必要が減る。
ただし、CSS変数を追加すれば設計が自動的に整うわけではない。変数名の命名規則がなければ、別の混乱が生じる。
たとえば、--color-blue-500と--color-primaryを同時に使うと、色の役割と色相が混在する。アプリケーションのデザインシステムでは、役割を示すトークンと値を示すトークンを分ける方が管理しやすい。
- 色相を表すトークン
- ボタンやリンクなど用途を表すトークン
- ダークモードやテーマ変更に対応する意味トークン
Tailwind v4の@themeは、これらを定義するための場所になる。ただし、命名の責任はプロジェクト側にある。
CSSとHTMLから参照できる利点
CSSカスタムプロパティは、Tailwindのユーティリティだけでなく、通常のCSSでも利用できる。コンポーネントの一部をTailwindで書き、複雑な状態表現をCSSで書く構成にも適している。
たとえば、疑似要素、複雑なアニメーション、外部ライブラリのスタイル調整では、ユーティリティクラスだけでは表現しにくい場合がある。そのような箇所で同じCSS変数を参照すれば、Tailwindのクラスと手書きCSSの値が分離しない。
VueやReactのコンポーネントでも、CSS変数を境界にできる。コンポーネント内部で直接カラーコードを持たず、テーマトークンを参照する構成にすれば、ブランド変更やテーマ切り替えの影響範囲を限定できる。
WordPressとの連携でも同じ考え方を使える。Tailwindで生成したCSSをテーマの共通スタイルとして利用し、ブロック側の追加スタイルからCSS変数を参照する。バックエンドがLaravelであってもWordPressであっても、ブラウザに渡るデザイン値を統一できる。
@themeの価値は、設定をCSSに書けることではない。デザイントークンを、Tailwindと通常のCSSが共有できる標準形式へ変換する点にある。PostCSS構成の簡素化とVite連携
Tailwind CSS v4では、PostCSSの構成も変わった。従来のTailwind用PostCSSプラグインをそのまま利用するのではなく、v4用の@tailwindcss/postcssパッケージを使用する。
また、postcss-importやautoprefixerを個別に記述する従来構成も見直されている。v4では必要な処理が自動化され、PostCSS設定の記述量が減る。
この変更は小さく見えるが、ビルドエラーの原因になりやすい部分である。パッケージを更新しただけで、古いプラグイン名や設定ファイルが残っていると、Tailwindが正しく読み込まれない。
移行時に確認する対象は次の通りである。
postcss.config.jsまたは同等のPostCSS設定tailwindcssを直接参照しているプラグイン設定autoprefixerやpostcss-importの個別依存- Vite側のCSS処理
- npmスクリプトやCIのビルドコマンド
不要になった依存パッケージは、動作確認後に削除する。先に削除すると、どの変更が原因でビルドが壊れたか判断できない。
Viteプロジェクトでは専用プラグインを使う
Vite向けには@tailwindcss/viteプラグインが提供されている。Laravelの新しいフロントエンド構成ではViteが使われることが多いため、既存のPostCSS構成からViteプラグインへ移行する選択肢がある。
Vite連携を採用する利点は、Tailwindの処理をViteのビルドパイプラインへ直接接続できる点にある。設定の経路が減り、PostCSSを経由した処理との責任範囲を分けやすい。
ただし、PostCSSからViteプラグインへ変更すれば必ず高速になると断定することはできない。プロジェクトにはCSS Modules、Sass、UIコンポーネントライブラリなど、別のCSS処理が存在する場合がある。既存のパイプラインとの重複がないか確認する必要がある。
判断基準は単純である。Tailwindの処理をどこで管理するかを一つに決めることだ。
- PostCSSで管理する
- Viteプラグインで管理する
- 複数の入口からTailwindを読み込まない
- 旧設定と新設定を同時に有効化しない
複数の構成を残すと、同じCSSが二重処理される可能性がある。生成結果の重複や、開発時と本番時で処理経路が変わる原因になる。
Laravelでの移行時に見るべき箇所
Laravelでは、フロントエンドのエントリーポイントがVite設定に集約されていることが多い。通常はresources/cssやresources/js配下を起点に、BladeやVueの画面へスタイルを提供する。
移行時は、次の順序で確認すると原因を切り分けやすい。
1. Tailwind v4本体と関連パッケージのバージョンを確認する。
2. ViteまたはPostCSSのどちらをTailwindの入口にするか決める。
3. CSSエントリーファイルでv4の読み込み方法を確認する。
4. @themeに主要なデザイントークンを移す。
5. BladeやVueで使用するクラスの生成結果を見る。
6. npm run devと本番ビルドの両方を実行する。
開発サーバーだけで動作確認を終えるのは避けるべきである。HMRではキャッシュが残り、古い生成結果が表示される場合がある。本番ビルドでCSSが生成されるかを確認する必要がある。
移行ツールを使ったv4アップグレード
Tailwind CSS v3からv4への移行には、公式の自動アップグレードツールが提供されている。コマンドはnpx @tailwindcss/upgradeである。実行にはNode.js 20以上が必要になる。
自動アップグレードツールは移行作業を減らす手段であり、検証を省略する手段ではない。自動変換の結果が、プロジェクトの設計意図まで完全に理解することはない。
特に、次のような構成では変換後の確認が必要である。
- JavaScriptでテーマ値を動的に生成している
- 独自のTailwindプラグインを使用している
- BladeやVueでクラス名を組み立てている
- 複数のフロントエンドアプリケーションを一つのリポジトリで管理している
- WordPressテーマとLaravel側のCSSを共有している
- CI環境とローカル環境でNode.jsのバージョンが異なる
移行前に保存するもの
移行前には、変更前のビルド結果を保存しておく。CSSファイルそのものでもよい。画面のスクリーンショットでもよい。目的は、移行後の差分を確認することである。
最低限、次の状態を記録する。
- 本番ビルドが成功していること
- 主要画面のCSSが適用されていること
- レスポンシブ用のブレークポイントが機能していること
- hoverやfocusなどの状態クラスが出力されていること
- ダークモードやテーマ切り替えが機能していること
- CSSの生成サイズとビルド時間
v4の移行では、コンパイルが成功しても見た目が完全に同じとは限らない。特に、設定ファイルから移した色や間隔の値に抜けがあると、画面の一部だけが既定値へ戻る。
移行後の検証を分割する
検証は一度に行わない。ビルド、生成CSS、画面、CIの順に分ける方がよい。
1. 依存関係の検証
package.jsonとロックファイルを確認する。Tailwind v4本体、PostCSS用パッケージ、Vite用プラグインが意図した構成になっているかを見る。
旧バージョン向けのパッケージが残っていても、直ちに問題とは限らない。しかし、実際に使われていない依存関係は、次の更新時にボトルネックになる。
2. CSS生成の検証
主要なユーティリティクラスが生成されているか確認する。特に、動的クラス名、条件分岐の中にあるクラス、別ディレクトリにあるテンプレートを確認する。
自動検出の対象から外れているファイルがあれば、クラスがCSSに出力されない。画面側のコードが正しくても、ビルド結果に存在しなければブラウザでは動作しない。
3. デザイントークンの検証
@themeに移した値が、CSSカスタムプロパティとして利用できるかを見る。Tailwindのユーティリティだけでなく、手書きCSSやコンポーネント側から参照するケースも確認する。
色、フォント、間隔、画面幅など、UI全体に影響するトークンから優先する。すべての設定を一度に移すより、影響範囲の広い値から確認する方が効率的である。
4. 本番ビルドの検証
開発サーバーのHMRと、本番ビルドの出力は別物である。CI環境でNode.js 20以上が満たされているかも確認する。ローカルだけでアップグレードツールを実行し、CIのNode.jsが古いままでは移行は完了しない。
Tailwind v4移行で発生しやすい設計上の問題
Tailwind v4の変更は、設定ファイルを短くするだけではない。設定の責任をどこへ置くかが変わる。
設定値とアプリケーションロジックを分ける
v3ではJavaScript設定ファイルに処理を追加しやすかった。条件分岐や関数を使ってテーマを生成することもできる。この柔軟性は、同時に依存関係を複雑にする。
v4ではCSS-first設計が基本になる。テーマの値はCSS側に寄せ、アプリケーションロジックとは分離する方が適している。
環境ごとに色やURLを変更する処理を、CSSのテーマ定義へ直接混ぜると、逆に管理しにくくなる。環境変数はViteやLaravelの設定で管理し、デザイン値はCSSカスタムプロパティとして管理する。責務を分けるべきである。
動的クラス名の設計を見直す
Tailwindは、実行時に任意のクラスを生成する仕組みではない。ビルド時に検出できるクラスだけが生成対象になる。
そのため、次のような実装は避けた方がよい。
- クラス名の一部を変数で連結する
- APIレスポンスの値をそのままクラス名にする
- データベースの値をCSSクラスとして扱う
- コンポーネントのpropsから未定義のクラスを生成する
代わりに、値とクラスの対応表を静的に定義する。クラス名がソースコード内に存在すれば、検出と生成が安定する。
この問題はLaravelの状態表示で頻繁に発生する。注文状態や権限に応じて色を変える場合、状態値から直接bg-*クラスを作るのではなく、状態ごとのクラスを定義しておく方が安全である。
ブラウザ互換性は別途判断する
Tailwind v4の新しいビルドエンジンとCSS構成が、すべてのレガシーブラウザで同じように利用できるとは限らない。旧ブラウザのサポートが必要なプロジェクトでは、互換性を先に確認する必要がある。
特に、Safari 16.3以下やChrome 110以下など、古いブラウザを含む環境については、公式のサポート情報を基準に判断すべきである。旧ブラウザ対応を優先する場合、Tailwind CSS v3.4の継続利用が選択肢になる。
これはv4が劣っているという話ではない。新しい構成には新しい前提がある。対象ブラウザと開発速度のどちらを優先するかというトレードオフである。
v4へ移行するべきプロジェクト、待つべきプロジェクト
Tailwind CSS v4は、すべてのプロジェクトが即座に移行すべきバージョンではない。判断材料は、ビルド速度だけでは足りない。
移行効果が出やすい構成
次のようなプロジェクトでは、v4の恩恵を受けやすい。
- LaravelとViteで継続的に画面を開発している
- BladeやVueの編集回数が多い
- CSSビルドの待ち時間が開発上のボトルネックになっている
- テーマ設定をCSS側へ集約したい
- デザインシステムをCSSカスタムプロパティで統一したい
- PostCSS構成を整理したい
- Node.js 20以上を開発環境とCIで利用できる
インクリメンタルビルドの高速化は、個人開発でも効果がある。画面を一人で実装する場合、ビルド待ちの時間はそのまま作業の中断になる。速度の改善は、チーム規模に関係しない。
移行を慎重にすべき構成
一方で、次の条件では段階的な検証が必要である。
- 独自プラグインに依存している
- JavaScript設定でテーマを複雑に生成している
- 複数のCSSビルドツールを併用している
- 古いブラウザをサポートする必要がある
- WordPressやLaravelなど複数の実行環境で同じCSSを使っている
- CIのNode.jsをすぐに更新できない
WordPressでは、テーマやブロックの読み込み方式がLaravelと異なる。Laravel側で動作した構成を、そのままWordPressへ移植できるとは限らない。アセットの生成場所と読み込み経路を分けて確認する必要がある。
移行による改善率とトレードオフ
Tailwind v4の移行結果を評価する場合、単にビルドが通ったかを見るだけでは不十分である。速度、設定、生成結果、互換性を分けて確認する。
- フルビルドは最大5倍の高速化が示されている。
- インクリメンタルビルドは最大100倍以上の高速化が示されている。
tailwind.config.jsとcontentの手動設定を中心とする構成から、CSS-first設計へ移行する。@themeの値はCSSカスタムプロパティとして利用できる。- PostCSSでは
@tailwindcss/postcssを使用する。 - Viteでは
@tailwindcss/viteを選択できる。 - アップグレードツールの実行にはNode.js 20以上が必要である。
- 旧ブラウザ対応や独自プラグインがある場合、v3.4を継続する判断も成立する。
lightningcssを手動で追加する構成は避けるべきである。依存関係の衝突を招く可能性がある。
Tailwind CSS v4の本質は、速くなったことだけではない。ビルド処理をRust製エンジンへ移し、設定をJavaScriptからCSSへ移し、デザイントークンを標準のCSS変数へ接続した点にある。
移行では、古い設定を新しい構文へ変換するだけでは足りない。Tailwindをどこで処理し、テーマをどこで定義し、コンポーネントがどの値を参照するかを整理する必要がある。
この設計変更を受け入れられるプロジェクトでは、開発時の待ち時間と設定の重複を減らせる。逆に、旧ブラウザや独自プラグインが主要な制約であれば、v3.4を維持する方が合理的である。結論は、バージョンの新しさではなく、プロジェクトの依存関係と運用条件から決めるべきである。
Related reading: Tailwind CSSのビルドで動的クラスが消えたトラブルと解決の記録.