Tailwind CSS v4：実際に何が変わったのか、移行すべきか

これだけです。設定ファイルなし。PostCSSプラグイン設定もなし（ほとんどのセットアップで）。@tailwind base; @tailwind components; @tailwind utilities;ディレクティブもなし。1つのインポートで動作します。

v3と比較してみましょう：

3つのファイルが1行に削減されました。これは単にボイラープレートが減っただけではなく、設定ミスの可能性が減ったということです。v4ではコンテンツ検出が自動化されています。globパターンを指定しなくても、プロジェクトファイルを自動的にスキャンします。

@themeによるCSSファースト設定

これが最大の概念的転換です。v3では、JavaScript設定オブジェクトを通じてTailwindをカスタマイズしていました：

v4では、これらすべてが@themeディレクティブを使ってCSSに配置されます：

最初は抵抗感がありました。デザインシステム全体を一望できる単一のJavaScriptオブジェクトが気に入っていたのです。しかし、CSSアプローチを1週間使ってみて、3つの理由で考えが変わりました：

1. ネイティブCSSカスタムプロパティが自動的に公開されます。 @themeで定義したすべての値が:rootのCSSカスタムプロパティになります。つまり、テーマ値は素のCSS、CSSモジュール、<style>タグなど、CSSが動作するあらゆる場所でアクセス可能になります：

2. @theme内でCSS機能を使えます。 メディアクエリ、light-dark()、calc() — 本物のCSSがここで動きます。なぜなら、これは本物のCSSだからです：

3. 他のCSSとの共存。 テーマ、カスタムユーティリティ、ベーススタイルがすべて同じ言語で、望めば同じファイルに配置できます。「CSSの世界」と「JavaScript設定の世界」の間でコンテキストスイッチする必要がありません。

デフォルトテーマのオーバーライドと拡張

v3ではtheme（置換）とtheme.extend（マージ）がありました。v4ではメンタルモデルが異なります：

名前空間を完全に置き換えたい場合（全デフォルトカラーの削除など）は、@themeで--color-*ワイルドカードリセットを使います：

このワイルドカードリセットパターンはエレガントです。デフォルトテーマのどの部分を残し、どの部分を置き換えるかを正確に選べます。デフォルトのspacingは全部残してカラーだけカスタムにしたい？--color-*: initial;をリセットして、spacingはそのままにします。

複数テーマファイル

大規模プロジェクトでは、テーマをファイルに分割できます：

これはv3の巨大なtailwind.config.jsを持つパターンや、require()で分割しようとするパターンよりもはるかにクリーンです。

Oxideエンジン：本当に10倍速い

Tailwind v4のエンジンはRustで完全に書き換えられました。Oxideと呼ばれています。「10倍速い」という主張には懐疑的でした——マーケティングの数字が実際のプロジェクトで通用することは稀です。そこで自分でベンチマークを取りました。

テストプロジェクト： 847コンポーネント、142ページ、約23,000のTailwindクラス使用箇所を持つNext.jsアプリ。

「10倍」の主張は私のプロジェクトでは控えめな数字でした。インクリメンタルビルドが真に輝く部分です——18msということは、本質的に瞬時です。ファイルを保存すると、タブを切り替える前にブラウザに新しいスタイルが反映されています。

なぜこれほど速いのか？

3つの理由があります：

1. JavaScriptの代わりにRust。 コアのCSSパーサー、クラス検出、コード生成がすべてネイティブRustです。「楽しいからRustで書き換えよう」という話ではありません——CSSのパースは本当にCPUバウンドな作業であり、ネイティブコードはV8に対して圧倒的な優位性を持ちます。

2. ホットパスにPostCSSがない。 v3では、TailwindはPostCSSプラグインでした。すべてのビルドで、CSSをPostCSS ASTにパースし、Tailwindプラグインを実行し、CSS文字列にシリアライズし直し、その後他のPostCSSプラグインが実行されていました。v4では、Tailwind独自のCSSパーサーがソースから出力に直接変換します。PostCSSは互換性のためにサポートされていますが、プライマリパスは完全にスキップします。

3. よりスマートなインクリメンタル処理。 新しいエンジンは積極的にキャッシュします。1つのファイルを編集すると、そのファイルだけをクラス名のために再スキャンし、変更されたCSSルールだけを再生成します。v3のエンジンはこの点について一般に思われているより賢かった（JITモードは既にインクリメンタルでした）が、v4は細粒度の依存関係追跡でさらに先を行っています。

速度は本当に重要か？

はい、ただし想像とは違う理由で重要です。ほとんどのプロジェクトでは、v3のビルド速度は「問題ない」レベルでした。開発中に数百ミリ秒待つ程度。苦痛ではありません。

v4の速度が重要なのは、ツールチェーンの中でTailwindを透明にしてくれるからです。ビルドが20ms以下になると、Tailwindをビルドステップとして意識しなくなります。シンタックスハイライトのように——常にそこにあるけど、邪魔にならない。この心理的な違いは、1日の開発を通じて大きな意味を持ちます。

ネイティブ@layer統合

v3では、Tailwindは@layer base、@layer components、@layer utilitiesという独自のレイヤーシステムを使っていました。これらはCSSカスケードレイヤーのように見えましたが、実際にはそうではなく、生成されたCSSが出力内のどこに配置されるかを制御するTailwind固有のディレクティブでした。

v4では、Tailwindは本物のCSSカスケードレイヤーを使用します：

これは重要な変更です。なぜなら、CSSカスケードレイヤーには実際の詳細度への影響があるからです。低優先度レイヤーのルールは、セレクターの詳細度に関係なく、高優先度レイヤーのルールに必ず負けます。つまり：

ユーティリティは常にコンポーネントをオーバーライドします。コンポーネントは常にベースをオーバーライドします。これはv3でも概念的にはTailwindの動作でしたが、今はソース順序の操作ではなく、ブラウザのカスケードレイヤーメカニズムによって強制されます。

カスタムユーティリティの追加

v3では、プラグインAPIまたは@layer utilitiesでカスタムユーティリティを定義していました：

v4では、カスタムユーティリティは@utilityディレクティブで定義します：

@utilityディレクティブは「これはユーティリティクラスです——utilitiesレイヤーに配置し、バリアントで使えるようにしてください」とTailwindに伝えます。最後の部分が重要です。@utilityで定義されたユーティリティは、hover:、focus:、md:、その他すべてのバリアントで自動的に動作します：

カスタムバリアント

@variantでカスタムバリアントも定義できます：

これはほとんどのユースケースでv3のaddVariantプラグインAPIを置き換えます。パワーは少し劣ります（プログラマティックなバリアント生成はできません）が、実際に行われることの90%をカバーします。

コンテナクエリ：組み込み、プラグイン不要

コンテナクエリはv3で最もリクエストの多かった機能の一つでした。@tailwindcss/container-queriesプラグインで利用できましたが、アドオンでした。v4ではフレームワークに組み込まれています。

基本的な使い方

@containerでコンテナをマークし、@プレフィックスでそのサイズをクエリします：

@md、@lgなどのバリアントはレスポンシブブレークポイントのように機能しますが、ビューポートではなく最も近い@container祖先に対して相対的です。ブレークポイントの値はTailwindのデフォルトブレークポイントに対応します：

名前付きコンテナ

特定の祖先をクエリするためにコンテナに名前を付けることができます：

なぜこれが重要か

コンテナクエリはレスポンシブデザインの考え方を変えます。「このビューポート幅で3カラム表示」ではなく、「このコンポーネントのコンテナが十分な幅になったら3カラム表示」と言えるようになります。コンポーネントが真に自己完結するのです。カードコンポーネントをフル幅レイアウトからサイドバーに移動しても、自動的に適応します。メディアクエリの体操は不要です。

コンポーネントライブラリをビューポートブレークポイントの代わりにデフォルトでコンテナクエリを使うようリファクタリングしてきました。結果として、配置場所に関係なく動作するコンポーネントが生まれ、親がコンポーネントのレスポンシブ動作について何も知る必要がなくなりました。

本当に重要な新バリアント

v4はいくつかの新しいバリアントを追加し、私は常に手を伸ばしています。実際のギャップを埋めてくれます。

starting:バリアント

これはCSS @starting-styleにマッピングされ、要素が最初に表示される際の初期状態を定義できます。JavaScriptなしで要素の登場をアニメーションする欠けていたピースです：

starting:バリアントは@starting-styleブロック内にCSSを生成します：

これはダイアログ、ポップオーバー、ドロップダウンメニューなど、登場アニメーションが必要なもの全般にとって大きな進歩です。以前は次のフレームでクラスを追加するためにJavaScriptが必要だったり、@keyframesを使ったりしていました。今はユーティリティクラスで済みます。

not-*バリアント

否定。ずっと望んでいたものです：

nth-*バリアント

nth-childとnth-of-typeへの直接アクセス：

ブラケット構文（nth-[3n+1]）は有効なnth-child式をすべてサポートします。テーブルのストライピングやグリッドパターンのために以前書いていたカスタムCSSの多くを置き換えます。

in-*バリアント（親の状態）

これはgroup-*の逆です。「親（group）がホバーされたとき自分をスタイリング」ではなく、「この状態にマッチする親の中にいるとき自分をスタイリング」です：

**:ディープユニバーサルバリアント

直接の子要素だけでなく、すべての子孫をスタイリングします。これは制御された力です——控えめに使うべきですが、散文コンテンツやCMS出力には非常に有用です：

破壊的変更：実際に壊れたもの

率直に言いましょう。大規模なv3プロジェクトがある場合、移行は簡単ではありません。私のプロジェクトで壊れたものを紹介します：

1. 設定フォーマット

tailwind.config.jsはそのままでは動きません。以下のいずれかが必要です：

• @theme CSSに変換する（新アーキテクチャ推奨）
• 互換レイヤーの@configディレクティブを使う（迅速な移行パス）

この@configブリッジは動作しますが、明示的に移行ツールです。長期的には@themeに移行することが推奨されています。

2. 廃止されたユーティリティの削除

v3で非推奨だったいくつかのユーティリティが削除されました：

v3で既にモダンな構文（スラッシュ不透明度、shrink-*）を使っていたなら問題ありません。そうでなければ、これらは単純な検索と置換の変更です。

3. デフォルトカラーパレットの変更

デフォルトカラーパレットがわずかに変更されました。v3の正確なカラー値（名前ではなく実際のhex値）に依存している場合、視覚的な違いに気付くかもしれません。名前付きカラー（blue-500、gray-200）はまだ存在しますが、一部のhex値が変更されています。

4. コンテンツ検出

v3では明示的なcontent設定が必要でした：

v4は自動コンテンツ検出を使用します。プロジェクトルートをスキャンしてテンプレートファイルを自動的に見つけます。これはほとんどの場合「そのまま動きます」が、通常とは異なるプロジェクト構造（プロジェクトルート外にパッケージがあるモノレポ、予期しない場所にあるテンプレートファイル）の場合、ソースパスを明示的に設定する必要があるかもしれません：

5. プラグインAPIの変更

カスタムプラグインを書いていた場合、APIが変更されました。addUtilities、addComponents、addBase、addVariant関数は互換レイヤーを通じて動作しますが、v4のイディオマティックなアプローチはCSSネイティブです：

ほとんどのファーストパーティプラグイン（@tailwindcss/typography、@tailwindcss/forms、@tailwindcss/aspect-ratio）にはv4互換バージョンがあります。サードパーティプラグインは対応状況がまちまちです——移行前にリポジトリを確認してください。

6. JITのみモード

v3では、JITモードをオプトアウトできました（ほぼ誰もしていませんでしたが）。v4では非JITモードはありません。すべてが常にオンデマンドで生成されます。何らかの理由で旧AOT（事前コンパイル）エンジンを使っていた場合、その道は閉ざされています。

7. 一部のバリアント構文の変更

いくつかのバリアントが名称変更または動作変更されました：

任意バリアント構文[&...]はまだ動作しますが、v4は一般的なパターンに対して名前付きの代替を提供します。

移行ガイド：実際のプロセス

実際にどのように移行したかを紹介します。ドキュメントのハッピーパスではなく、プロセスが実際にどのようなものだったかです。

ステップ1：公式コードモッドの実行

Tailwindはほとんどの機械的な変更を処理するコードモッドを提供しています：

これは多くのことを自動的に行います：

• @tailwindディレクティブを@import "tailwindcss"に変換
• 非推奨のユーティリティクラスの名称変更
• バリアント構文の更新
• 不透明度ユーティリティをスラッシュ構文に変換（bg-opacity-50をbg-black/50に）
• 設定からの基本的な@themeブロックの作成

コードモッドがうまく処理するもの

• ユーティリティクラスの名称変更（ほぼ完璧）
• ディレクティブ構文の変更
• シンプルなテーマ値（カラー、spacing、フォント）
• 不透明度構文の移行

コードモッドが処理しないもの

• 複雑なプラグインの変換
• 動的設定値（JavaScript内のtheme()呼び出し）
• 条件付きテーマ設定（例：環境に基づくテーマ値）
• カスタムプラグインAPIの移行
• 新しいパーサーが異なる解釈をする任意値のエッジケース
• JavaScriptで動的に構築されるクラス名（テンプレートリテラル、文字列結合）

ステップ2：PostCSS設定の修正

ほとんどのセットアップでは、PostCSS設定を更新します：

注意：プラグイン名がtailwindcssから@tailwindcss/postcssに変更されました。Viteを使っている場合は、PostCSSを完全にスキップしてViteプラグインを使えます：

ステップ3：テーマ設定の変換

ここが手動作業の部分です。tailwind.config.jsのテーマ値を@themeに変換します：

キーフレームは@themeの外に出て通常のCSS @keyframesになることに注目してください。@themeのアニメーション名はそれらを参照するだけです。こちらの方がクリーンです——キーフレームはCSSであり、CSSとして書かれるべきです。

ステップ4：ビジュアルリグレッションテスト

これは必須です。移行後、アプリのすべてのページを開いて視覚的に確認しました。Playwrightのスクリーンショットテストも実行しました（もしあれば）。コードモッドは優秀ですが完璧ではありません。ビジュアルレビューで発見したこと：

• 不透明度構文の移行がわずかに異なる結果を生成したいくつかの箇所
• 引き継がれなかったカスタムプラグインの出力
• レイヤー順序によるz-indexのスタッキング変更
• カスケードレイヤーで異なる動作をした!importantオーバーライド

ステップ5：サードパーティ依存関係の更新

Tailwind関連のすべてのパッケージを確認します：

@tailwindcss/container-queriesプラグインはもう不要です——コンテナクエリが組み込まれました。他のプラグインにはv4互換バージョンが必要です。

Next.jsとの連携

ほとんどのプロジェクトでNext.jsを使っているので、具体的なセットアップを紹介します。

PostCSSアプローチ（Next.js推奨）

Next.jsは内部でPostCSSを使用しているため、PostCSSプラグインが自然な選択です：

これがセットアップの全体です。tailwind.config.jsなし、autoprefixerなし（v4がベンダープレフィックスを内部的に処理します）。

CSSインポート順序

つまずいたポイントが一つ：v4ではカスケードレイヤーのためにCSSインポート順序がより重要になります。@import "tailwindcss"はカスタムスタイルより前に来る必要があります：

Tailwindの前にカスタムCSSをインポートすると、スタイルが低いカスケードレイヤーに配置され、予期せず上書きされる可能性があります。

ダークモード

ダークモードは概念的には同じように動作しますが、設定がCSSに移りました：

これはv3の設定を置き換えます：

@variantアプローチはより柔軟です。ダークモードを好きなように定義できます——クラスベース、data属性ベース、メディアクエリベース：

Turbopack互換性

Next.jsをTurbopack（現在のデフォルト開発バンドラー）で使っている場合、v4はうまく動作します。Rustエンジンは、Turbopack自身のRustベースアーキテクチャとうまく噛み合います。開発起動時間を計測しました：

CSS変更に対する40ms HMRはほとんど知覚できません。瞬時に感じます。

パフォーマンス深掘り：ビルド速度を超えて

Oxideエンジンの利点はビルド速度だけにとどまりません。

メモリ使用量

v4はメモリ使用量が大幅に少なくなります。847コンポーネントのプロジェクトでの計測：

これはメモリが制限されるCI/CDパイプラインや、10個のプロセスを同時実行する開発マシンにとって重要です。

CSS出力サイズ

v4は新しいエンジンが重複排除とデッドコード除去に優れているため、わずかに小さいCSS出力を生成します：

コードを変更せずに13%の削減。革命的ではありませんが、無料のパフォーマンス改善です。

テーマ値のツリーシェイキング

v4では、テーマ値を定義しても、テンプレートで使用していない場合、対応するCSSカスタムプロパティはそのまま出力されます（@themeに含まれており、:root変数にマッピングされるため）。ただし、未使用値のユーティリティクラスは生成されません。これはv3のJIT動作と同じですが、注目すべき点です：CSSカスタムプロパティは、ユーティリティ使用がない値であっても常に利用可能です。

特定のテーマ値がCSSカスタムプロパティを生成するのを防ぎたい場合は、@theme inlineを使います：

これはCSS変数として公開したくない内部デザイントークンに便利です。

上級編：マルチブランド向けテーマの構成

v4が大幅に簡単にするパターンの一つが、マルチブランドテーミングです。テーマ値がCSSカスタムプロパティであるため、実行時にスワップできます：

v3ではこれにカスタムプラグインやTailwind外の複雑なCSS変数設定が必要でした。v4では自然です——テーマはCSS変数であり、CSS変数はカスケードするからです。これがCSSファーストアプローチの正しさを感じさせる類のものです。

v3で恋しいもの

バランスを取りましょう。v3にあってv4で本当に恋しいものがあります：

1. プログラマティックテーマのためのJavaScript設定。 単一のブランドカラーからJavaScript関数でカラースケールを生成していたプロジェクトがありました。v4では@themeでそれができません——CSSファイルを生成するビルドステップが必要か、カラーを一度計算してペーストする必要があります。@config互換レイヤーは役立ちますが、長期的な解決策ではありません。

2. IntelliSenseはリリース時の方が優秀でした。 v3のVS Code拡張機能は何年もの磨きがかかっていました。v4のIntelliSenseは動作しますが、初期にはいくつかのギャップがありました——カスタム@theme値がオートコンプリートされないことや、@utility定義が認識されないことがありました。最近のアップデートで大幅に改善されましたが、注目に値します。

3. エコシステムの成熟度。 v3周辺のエコシステムは巨大でした。Headless UI、Radix、shadcn/ui、Flowbite、DaisyUI——すべてがv3に対してテストされていました。v4サポートは展開中ですが、まだ普遍的ではありません。あるコンポーネントライブラリのv4互換性を修正するためにPRを送ったこともあります。

移行すべきか？

v4と数週間暮らした後の判断フレームワークを紹介します：

今すぐ移行すべき場合：

• 新規プロジェクトを始める場合（明白な選択——v4で始めましょう）
• プロジェクトにカスタムプラグインが最小限の場合
• 大規模プロジェクトでパフォーマンス上の利点が欲しい場合
• 既にモダンなTailwindパターン（スラッシュ不透明度、shrink-*など）を使っている場合
• コンテナクエリが必要でプラグインを追加したくない場合

待つべき場合：

• v4をサポートしていないサードパーティTailwindプラグインに大きく依存している場合
• 複雑なプログラマティックテーマ設定がある場合
• プロジェクトが安定しており積極的に開発されていない場合（なぜ触るのか？）
• 機能スプリントの真っ最中の場合（スプリント間で移行し、スプリント中にはしない）

移行すべきでない場合：

• v2以前を使っている場合（まずv3にアップグレードし、安定させてからv4を検討）
• プロジェクトがあと数ヶ月で終了する場合（変更のコストに見合わない）

正直な感想

新規プロジェクトにはv4が明白な選択です。CSSファースト設定はクリーンで、エンジンは劇的に高速で、新機能（コンテナクエリ、@starting-style、新バリアント）は本当に有用です。

既存プロジェクトには段階的なアプローチを推奨します：

1. 今すぐ： 新規プロジェクトはすべてv4で始める
2. 近いうちに： 小さな社内プロジェクトをv4に変換して実験する
3. 準備ができたら： ビジュアルリグレッションテストを伴い、穏やかなスプリント中にプロダクションプロジェクトを移行する

準備すれば移行は苦痛ではありません。コードモッドが作業の80%を処理します。残りの20%は手動ですが、簡単です。中規模プロジェクトで1日、大規模プロジェクトで2〜3日を見込んでください。

Tailwind v4はTailwindがずっとあるべきだった姿です。JavaScript設定は当時のツーリングへの譲歩でした。CSSファースト設定、ネイティブカスケードレイヤー、Rustエンジン——これらはトレンドではなく、フレームワークがプラットフォームに追いついたということです。Webプラットフォームは進化し、Tailwind v4はそれに逆らうのではなく寄り添っています。

デザイントークンをCSSで書き、CSS機能でそれらを構成し、ブラウザ自身のカスケードに詳細度を任せる——それが正しい方向性です。ここに至るまで4つのメジャーバージョンが必要でしたが、その結果はこれまでで最も首尾一貫したTailwindのバージョンです。

次のプロジェクトで始めてください。後戻りはないでしょう。