Tailwind CSS v4移行ガイド｜v3からの変更点・破壊的変更と移行手順

Tailwind CSS v4は、設定をJavaScriptファイルではなくCSS内で行う「CSS-first」へと刷新し、新エンジンOxideで大幅に高速化したメジャーバージョンです。2025年1月22日に正式リリースされ、tailwind.config.jsから@themeへの移行、@tailwindディレクティブの廃止、ボーダー色やリング幅などの破壊的変更を伴います。v3からの移行は公式アップグレードツールでほぼ自動化できますが、対応ブラウザ要件が上がる点に注意が必要です。

v3のプロジェクトをそのままv4に上げたら、@tailwind baseが効かない、設定ファイルが読まれない、ボーダーの色が変わってしまった——v4は「速くなった」だけでなく、設定の書き方そのものが変わっているため、何も知らずにアップグレードすると確実につまずきます。逆に変更点さえ把握すれば、移行作業自体は短時間で終わります。

この記事では、Tailwind公式の発表とアップグレードガイドをもとに、v3からv4で何が変わったのかを「設定方法・記法・破壊的変更・対応ブラウザ」の観点で整理し、公式アップグレードツールを使った移行手順と、移行後に必ず確認すべき検証チェックリストまでを通しでまとめます。「今すぐ移行すべきか、v3.4に留まるべきか」の判断基準も最後に示します。

Tailwind CSS v4とは｜v3からの本質的な変化

Tailwind CSS v4.0は、開発者Adam Wathan氏により2025年1月22日に正式リリースされたメジャーバージョンです（出典: Tailwind CSS公式ブログ「Tailwind CSS v4.0」）。単なる機能追加ではなく、設定の仕組みとビルドエンジンが根本から作り直されている点が、v3との最大の違いです。

まず、v3とv4の違いを全体像として押さえましょう。「どこを直せば移行できるか」がこの表でほぼ見えてきます。

Tailwindそのものの基本的な書き方や導入手順から学び直したい場合は、Tailwind CSSの学習方法｜初心者が最短でマスターする7つのステップを先に押さえておくと、v4の変更点がより理解しやすくなります。

新エンジンOxideとパフォーマンス

v4の目玉のひとつが、Rustで書かれた新エンジン「Oxide」による高速化です。公式が示したベンチマークでは、フルビルドもインクリメンタルビルド（差分ビルド）も大幅に短縮されています。

特に、新しいCSSクラスが増えていない差分ビルドはマイクロ秒単位で完了し、v3比で約182倍高速とされています（出典: Tailwind CSS公式ブログ）。開発中の保存→反映の体感がこの差分ビルドの速度に直結するため、規模の大きいプロジェクトほど恩恵が大きくなります。

速度面だけでなく、ビルドまわりの依存もシンプルになります。v4はベンダープレフィックスの付与や@importの解決、ネスト記法の処理を内部で扱うため、これまで併用していたautoprefixerやpostcss-importといったツールが基本的に不要になります。移行のタイミングで、これらの周辺パッケージを整理できるのも見逃せないメリットです。

最大の変化：CSS-first設定（@theme）

移行で最も影響が大きいのが、設定方法の変更です。v3ではtailwind.config.jsというJavaScriptファイルでカスタマイズしていましたが、v4ではCSSファイル内の@themeブロックで設定する「CSS-firstコンフィグ」に変わりました。テーマの値はそのままネイティブのCSS変数として公開されます。

たとえばブランドカラーを1色追加するだけでも、書く場所と書き方が次のように変わります。

// v3: tailwind.config.js（JavaScript）
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["./src/**/*.{html,js}"],
  theme: {
    extend: {
      colors: { brand: "#1da1f2" },
    },
  },
};

/* v4: CSSファイル内（@theme） */
@import "tailwindcss";

@theme {
  --color-brand: #1da1f2;
}

これによりbg-brandのようなユーティリティが使えるようになる点はv3と同じですが、設定がCSSの世界に統合されるのが大きな思想転換です。なおtailwind.config.jsも後方互換として読み込めますが、新規プロジェクトや本格的な移行では@themeへ寄せるのが推奨です。

テーマ値をネイティブCSS変数として使える

CSS-first設定のもうひとつの利点は、@themeで定義した値がそのままネイティブのCSS変数（カスタムプロパティ）として公開されることです。Tailwindのユーティリティクラスが届かない素のCSSやキーフレームアニメーションからも、同じデザイントークンをvar()で直接参照できます。

/* @themeで定義した値は CSS変数として参照できる */
.custom-card {
  border: 1px solid var(--color-brand);
  color: var(--color-brand);
}

v3ではJavaScript側にあった設定値をCSSから使うには一手間が必要でしたが、v4ではデザイントークンの定義場所とCSSの利用場所が地続きになります。ユーティリティと素のCSSが混在するプロジェクトほど、この一貫性は効いてきます。

インストール・記法の変更点

設定以外にも、エントリーCSSの書き方とビルド設定が変わりました。移行時にまず手を入れる箇所です。

エントリーCSSは@importの1行に

v3で3行書いていた@tailwindディレクティブは廃止され、v4では@import "tailwindcss";の1行に置き換わります。

/* v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* v4 */
@import "tailwindcss";

PostCSSプラグインとViteプラグイン

PostCSS経由で使う場合、プラグインはtailwindcssから@tailwindcss/postcssに変わりました。Viteを使うなら、より高速な公式の@tailwindcss/viteプラグインが用意されています。

// v4: postcss.config.mjs
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

// v4: Viteを使う場合は vite.config.ts
import tailwindcss from "@tailwindcss/vite";
export default {
  plugins: [tailwindcss()],
};

content配列が不要になった

v3で必須だったテンプレートファイルのcontent配列指定は、v4では自動検出になり原則不要です。.gitignoreを考慮しつつプロジェクト内のファイルを走査してくれるため、設定漏れでスタイルが当たらないトラブルが減ります。

対応ブラウザ要件と移行可否の判断

移行の可否を左右する最重要ポイントが、対応ブラウザ要件です。v4は@propertyやcolor-mix()といったモダンCSS機能に依存しているため、サポート対象が引き上げられています。

公式は、これより古いブラウザをサポートする必要がある場合はv3.4に留まることを推奨しています（出典: Tailwind CSS公式 Upgrade guide）。エンタープライズ案件で古い環境を切れない場合は、移行を急がない判断も正解です。自社・案件のブラウザサポート方針を最初に確認してから移行に着手しましょう。

主な破壊的変更（breaking changes）一覧

見た目に直接影響する破壊的変更がいくつかあります。アップグレードツールがコードは書き換えてくれますが、デフォルト値の変更はデザインの差分として現れるため、把握しておかないと「なぜか見た目が変わった」と混乱します。

とくにボーダー色とring幅はUI全体に波及しやすい変更です。borderだけ書いて色を指定していなかった箇所は、v4ではcurrentColorになるため、明示的にborder-gray-200などを付けるとv3の見た目を維持できます。CSS変数の任意値は、角括弧[ ]から丸括弧( )へ記法が変わった点に注意してください。

該当箇所が多くて1つずつ直すのが現実的でない場合は、ベースレイヤーでデフォルトのボーダー色を一括指定し、旧来の見た目に寄せる方法もあります。ただし影響範囲が広いため、いきなり全体に当てる前に、まずは差分とデザインへの影響を確認してから採用するかを判断するのが安全です。

v3からv4への移行手順

既存プロジェクトの移行は、公式のアップグレードツールを使うのが最短です。設定ファイルのCSSへの変換、依存関係の更新、テンプレート内のクラス名変更までをまとめて自動化してくれます。

1. Node.jsを20以上にする：アップグレードツールはNode.js 20+が必要。まずnode -vで確認する
2. 作業ブランチを切る：差分を確認・巻き戻せるよう、移行専用のGitブランチを作成しておく
3. アップグレードツールを実行する：プロジェクト直下で公式ツールを走らせ、自動変換を任せる
4. 差分をレビューする：設定のCSS化・@import化・クラス名変更が意図通りか、Gitの差分で1つずつ確認する
5. ビルドして表示を確認する：開発サーバーを起動し、破壊的変更（ボーダー・ring等）の影響が出ていないか目視する

# Node 20+ を確認
node -v

# 公式アップグレードツールを実行（プロジェクト直下で）
npx @tailwindcss/upgrade

ツールは多くの変更を自動で適用しますが、すべてが完璧に変換されるとは限りません。とくに動的に組み立てているクラス名や、独自プラグイン・複雑なカスタム設定は手動対応が必要になることがあります。次の章の検証は必ず行ってください。

移行後の検証チェックリスト

アップグレードツールを走らせて「ビルドが通った」だけで終わらせると、見た目の崩れを見落とします。移行後は次の観点を1つずつ確認しましょう。

• ビルドがエラーなく完了するか：@tailwindの残存や旧プラグイン参照が残っていないか
• ボーダーの色：色指定なしのborderがcurrentColor化していないか。必要ならborder-gray-200を補う
• フォーカスリング：ringの太さ（3px→1px）と色（currentColor）の変化で見え方が変わっていないか
• プレースホルダー：入力欄のプレースホルダー色が想定どおりか
• CSS変数の任意値：[--var]記法が(--var)に置き換わっているか
• 動的クラス名：文字列結合で生成しているクラスが正しく適用されているか
• 対応ブラウザでの表示：要件を満たすブラウザで主要画面を一通り確認したか

手動対応が必要になるケースと対処

アップグレードツールで完結しない、つまずきやすいパターンと対処を挙げます。検証で違和感があったら、まずここを疑ってください。

• 動的に生成するクラス名：`text-${color}-500`のような文字列結合は自動変換の対象外になりやすい。安全なクラスの組み立て方に見直す
• 独自プラグイン・複雑なtheme設定：@themeやCSSベースの記法へ手動で書き換える必要がある場合がある
• 意図的に依存していたデフォルト値：ボーダー色やring幅の旧デフォルトに頼っていた箇所は、明示指定に直す
• サードパーティUIライブラリ：Tailwindに依存するライブラリがv4対応済みか、バージョンを確認する

大規模なプロジェクトや、デザインの再現性が厳しく問われる案件では、移行とリグレッション確認に相応の工数がかかります。社内に手が足りない場合は、RINIAのような制作チームに移行作業とデザイン検証をまとめて依頼するのも選択肢です。

v4移行後に新しく使えるようになる機能

移行は「壊れた箇所を直す」だけの作業に見えがちですが、v4ではこれまでプラグインが必要だった機能や、新しいユーティリティが標準で使えるようになります。移行後の「次の一手」として、活用できるものを押さえておきましょう（出典: Tailwind CSS公式ブログ）。

• コンテナクエリが標準搭載：v3では別プラグインが必要だった@containerベースのレスポンシブが、追加なしで@container／@max-*として使える
• 3D変形ユーティリティ：rotate-x-*・rotate-y-*・scale-z-*など、3D変形をクラスだけで表現できる
• @starting-styleのサポート：要素の出現・消滅アニメーション（enter/exit遷移）をJavaScriptなしで扱えるstartingバリアントが追加
• not-*バリアント：擬似クラスやメディアクエリを否定条件として書ける。条件分岐的なスタイルがすっきりする
• P3対応の刷新カラーパレット：従来のRGBからOKLCHベースへ刷新され、広色域ディスプレイでより鮮やかな発色になった

つまりv4移行は、ビルドの高速化に加えて「これまで外部プラグインで補っていた表現をネイティブに置き換えられる」機会でもあります。移行が一段落したら、既存のプラグイン依存を見直し、標準機能へ寄せていくと依存関係をスリムにできます。

移行すべきか・見送るべきかの判断基準

最後に、移行のゴーサインを出す前のチェックです。次の表で「移行向き」「v3.4継続向き」を見極めましょう。

結論として、モダンブラウザ前提のプロジェクトであれば、v4移行のメリットは大きいです。一方で、ブラウザ要件や依存ライブラリの都合で急げない場合に無理をする必要はありません。判断軸さえ持っておけば、移行は「いつ・どう進めるか」の計画の問題に落とし込めます。

よくある質問

Q. Tailwind CSS v4はいつリリースされましたか？

2025年1月22日に正式リリースされました（出典: Tailwind CSS公式ブログ）。開発はAdam Wathan氏が中心で、新エンジンOxideとCSS-first設定が目玉です。

Q. v3からv4へは自動で移行できますか？

公式のアップグレードツール（npx @tailwindcss/upgrade）で多くを自動化できます。ただし動的なクラス名や独自プラグインは手動対応が必要なことがあり、移行後の表示確認は必須です。実行にはNode.js 20以上が必要です。

Q. tailwind.config.jsはもう使えないのですか？

後方互換として読み込むことは可能ですが、v4では@themeを使ったCSS-first設定が推奨です。新規プロジェクトや本格的な移行では、設定をCSS側へ寄せる方針が将来的に扱いやすくなります。

Q. 古いブラウザに対応する必要がある場合はどうすべきですか？

v4はSafari 16.4+/Chrome 111+/Firefox 128+が必要です。これより古い環境をサポートする必要があるなら、公式はv3.4に留まることを推奨しています。ブラウザ要件は移行可否の最重要ポイントなので、最初に確認してください。

Q. v4にアップグレードするとデザインが崩れることはありますか？

あり得ます。ボーダーのデフォルト色がcurrentColorに、ringの幅が3px→1pxに変わるなど、デフォルト値の破壊的変更が見た目に影響します。色やringを明示指定していなかった箇所は、移行後に表示を確認して必要に応じて指定を補ってください。

Q. 既存のCSS（リセットCSS等）と併用できますか？

v4にもPreflight（ベースリセット）が含まれているため、別途リセットCSSを重ねると競合することがあります。リセットの基礎を整理したい場合はReset CSS おすすめ5選比較【2026年】結局どれを使うべき？も参考にしてください。

Q. 移行にはどれくらい時間がかかりますか？

プロジェクトの規模とカスタマイズの度合いによります。標準的な構成で動的クラス名や独自プラグインが少なければ、公式ツールでの自動変換と検証を合わせて短時間で済みます。一方、UIライブラリへの依存や複雑なtheme設定がある場合は、リグレッション確認に時間を見込んでください。まず小さなブランチで試し、差分の量を見てから本対応のスケジュールを決めるのが安全です。

まとめ

Tailwind CSS v4は、CSS-first設定（@theme）・@importへの一本化・新エンジンOxideによる高速化が柱のメジャーバージョンです。移行は公式アップグレードツールでほぼ自動化できますが、ボーダー色やring幅などの破壊的変更がデザインに影響するため、移行後の検証が欠かせません。

そして移行可否を最初に決めるのは対応ブラウザ要件です。モダンブラウザ前提なら積極的に移行し、古い環境が必要ならv3.4に留まる——この判断軸を持って、計画的に進めましょう。細かな変更点は公式のUpgrade guideが一次情報として最も確実なので、着手前に一読しておくと安心です。

関連記事

• Tailwind CSSの学習方法｜初心者が最短でマスターする7つのステップ
• 2026年 新CSSフレームワーク「lism-css」とは？軽量＆直感的な書き方が魅力！
• Reset CSS おすすめ5選比較【2026年】結局どれを使うべき？
• CSS実装テクニック集【基礎・レイアウト・アニメーション・設計手法】