はじめに
Tailwind CSS プロジェクトを v3 から v4 にアップグレードする。
Tailwind CSS v4.0 はフレームワークの新しいメジャーバージョンであるため、破壊的な変更を最小限に抑えるために懸命に取り組んできましたが、いくつかのアップデートが必要です。このガイドでは、プロジェクトを v3 から v4 にアップグレードするために必要なすべての手順を概説します。
Tailwind CSS v4.0 は Safari 16.4 以降、Chrome 111 以降、および Firefox 128 以降向けに設計されています。古いブラウザーをサポートする必要がある場合は、ブラウザーのサポート要件が変更されるまで v3.4 を使用してください。
プロジェクトを v3 から v4 にアップグレードする場合は、アップグレードツールを使用して、大部分の面倒な作業を自動化できます。
$ npx @tailwindcss/upgradeほとんどのプロジェクトでは、アップグレードツールは、依存関係の更新、構成ファイルの CSS への移行、テンプレートファイルへの変更の処理など、移行プロセス全体を自動化します。
アップグレードツールには Node.js 20 以降が必要であるため、実行する前に環境が更新されていることを確認してください。
新しいブランチでアップグレードツールを実行し、差分を注意深く確認し、プロジェクトをブラウザーでテストして、すべての変更が正しく表示されることを確認することを推奨します。複雑なプロジェクトでは手動で微調整する必要があるかもしれませんが、いずれにしても、このツールを使用することで時間を大幅に節約できます。
また、v4 の破壊的な変更をすべて確認し、変更内容を十分に理解して、アップグレードツールで検出されないプロジェクト内で更新する必要がある他の事項がないか確認することをお勧めします。
v3 では、tailwindcss パッケージは PostCSS プラグインでしたが、v4 では PostCSS プラグインは専用の @tailwindcss/postcss パッケージに存在します。
さらに、v4 では、インポートとベンダープレフィックスが自動的に処理されるようになったため、プロジェクトに postcss-import および autoprefixer が含まれている場合は削除できます。
export default { plugins: { "postcss-import": {}, tailwindcss: {}, autoprefixer: {}, "@tailwindcss/postcss": {}, },};Vite を使用している場合は、パフォーマンスの向上と最高の開発者エクスペリエンスのために、PostCSS プラグインから新しい専用の Vite プラグインに移行することをお勧めします。
import { defineConfig } from "vite";import tailwindcss from "@tailwindcss/vite";export default defineConfig({ plugins: [ tailwindcss(), ],});v4 では、Tailwind CLI は専用の @tailwindcss/cli パッケージに存在します。ビルドコマンドを更新して、代わりに新しいパッケージを使用してください。
npx tailwindcss -i input.css -o output.cssnpx @tailwindcss/cli -i input.css -o output.cssTailwind CSS v4.0 のすべての破壊的な変更点の包括的なリストを以下に示します。
弊社のアップグレードツールは、これらの変更点のほとんどを自動的に処理するため、可能な限り使用することを強くお勧めします。
Tailwind CSS v4.0 は最新のブラウザー向けに設計されており、Safari 16.4、Chrome 111、および Firefox 128 をターゲットとしています。コアフレームワーク機能には @property や color-mix() などの最新の CSS 機能に依存しており、Tailwind CSS v4.0 は古いブラウザーでは動作しません。
古いブラウザーをサポートする必要がある場合は、当面 v3.4 を使用することをお勧めします。より早くアップグレードできるように、互換モードを積極的に検討しており、今後の最新情報をお知らせしたいと考えています。
v4 では、Tailwind は v3 で使用した @tailwind ディレクティブではなく、通常の CSS @import ステートメントを使用してインポートします。
@tailwind base;@tailwind components;@tailwind utilities;@import "tailwindcss";v3 で非推奨となり、数年間ドキュメント化されていなかったユーティリティを削除しました。削除されたものと最新の代替手段のリストを以下に示します。
| 非推奨 | 代替 |
|---|---|
bg-opacity-* | bg-black/50 のような opacity 修飾子を使用 |
text-opacity-* | text-black/50 のような opacity 修飾子を使用 |
border-opacity-* | border-black/50 のような opacity 修飾子を使用 |
divide-opacity-* | divide-black/50 のような opacity 修飾子を使用 |
ring-opacity-* | ring-black/50 のような opacity 修飾子を使用 |
placeholder-opacity-* | placeholder-black/50 のような opacity 修飾子を使用 |
flex-shrink-* | shrink-* |
flex-grow-* | grow-* |
overflow-ellipsis | text-ellipsis |
decoration-slice | box-decoration-slice |
decoration-clone | box-decoration-clone |
v4 では、以下のユーティリティの名前を変更して、より一貫性と予測可能性を高めました。
| v3 | v4 |
|---|---|
shadow-sm | shadow-xs |
shadow | shadow-sm |
drop-shadow-sm | drop-shadow-xs |
drop-shadow | drop-shadow-sm |
blur-sm | blur-xs |
blur | blur-sm |
backdrop-blur-sm | backdrop-blur-xs |
backdrop-blur | backdrop-blur-sm |
rounded-sm | rounded-xs |
rounded | rounded-sm |
outline-none | outline-hidden |
ring | ring-3 |
すべてのユーティリティに名前付きの値があることを確認するために、デフォルトの shadow、radius、および blur スケールの名前を変更しました。「bare」バージョンは下位互換性のために引き続き機能しますが、<utility>-sm ユーティリティは、それぞれの <utility>-xs バージョンに更新しない限り、異なって表示されます。
これらの変更に合わせてプロジェクトを更新するには、v3 ユーティリティをすべて v4 バージョンに置き換えます。
<input class="shadow-sm" /><input class="shadow-xs" /><input class="shadow" /><input class="shadow-sm" />outline ユーティリティは、border および ring ユーティリティとの一貫性を高めるために、デフォルトで outline-width: 1px を設定するようになりました。さらに、すべての outline-<number> ユーティリティは、デフォルトで outline-style を solid に設定し、outline と組み合わせる必要がなくなりました。
<input class="outline outline-2" /><input class="outline-2" />以前の outline-none ユーティリティは、実際には outline-style: none を設定していませんでしたが、アクセシビリティ上の理由から、強制色モードでも表示される非表示のアウトラインを設定していました。
これをより明確にするために、このユーティリティの名前を outline-hidden に変更し、実際に outline-style: none を設定する新しい outline-none ユーティリティを追加しました。
この変更に合わせてプロジェクトを更新するには、outline-none の使用箇所をすべて outline-hidden に置き換えます。
<input class="focus:outline-none" /><input class="focus:outline-hidden" />v3 では、ring ユーティリティは 3px の ring を追加していました。v4 では、border および outline との一貫性を高めるために、これを 1px に変更しました。
この変更に合わせてプロジェクトを更新するには、ring の使用箇所をすべて ring-3 に置き換えます。
<input class="ring ring-blue-500" /><input class="ring-3 ring-blue-500" />space-x-* および space-y-* ユーティリティで使用されるセレクターを、大規模ページでの深刻なパフォーマンスの問題に対処するために変更しました。
/* Before */.space-y-4 > :not([hidden]) ~ :not([hidden]) { margin-top: 1rem;}/* Now */.space-y-4 > :not(:last-child) { margin-bottom: 1rem;}これらのユーティリティをインライン要素で使用したり、子要素の間隔を調整するために他の margin を子要素に追加したりした場合、プロジェクトに変化が見られる場合があります。
この変更がプロジェクトで問題を引き起こす場合は、flex または grid レイアウトに移行し、代わりに gap を使用することをお勧めします。
<div class="space-y-4 p-4"><div class="flex flex-col gap-4 p-4"> <label for="name">Name</label> <input type="text" name="name" /></div>v3 では、variants を使用してグラデーションの一部をオーバーライドすると、グラデーション全体が「リセット」され、この例では to-* カラーは黄色ではなくダークモードで透明になります。
<div class="bg-gradient-to-r from-red-500 to-yellow-400 dark:from-blue-500"> <!-- ... --></div>v4 では、これらの値は保持されます。これは、Tailwind の他のユーティリティの動作とより一貫性があります。
つまり、特定の状態の 3 ストップグラデーションを 2 ストップグラデーションに戻して「unset」する場合は、明示的に via-none を使用する必要がある場合があります。
<div class="bg-linear-to-r from-red-500 via-orange-400 to-yellow-400 dark:via-none dark:from-blue-500 dark:to-teal-400"> <!-- ... --></div>v3 では、container ユーティリティには、v4 には存在しなくなった center や padding などのいくつかの構成オプションがありました。
v4 で container ユーティリティをカスタマイズするには、@utility ディレクティブを使用して拡張します。
@utility container { margin-inline: auto; padding-inline: 2rem;}v3 では、border-* および divide-* ユーティリティは、デフォルトで構成済みの gray-200 カラーを使用していました。v4 では、Tailwind の意見を減らし、ブラウザーのデフォルトに合わせるために、これを currentColor に変更しました。
この変更に合わせてプロジェクトを更新するには、border-* または divide-* ユーティリティを使用する場所に色を必ず指定してください。
<div class="border border-gray-200 px-2 py-3 ..."> <!-- ... --></div>または、これらのベーススタイルをプロジェクトに追加して、v3 の動作を維持します。
@layer base { *, ::after, ::before, ::backdrop, ::file-selector-button { border-color: var(--color-gray-200, currentColor); }}ring ユーティリティの幅を 3px から 1px に変更し、デフォルトの color を blue-500 から currentColor に変更して、border-*、divide-*、および outline-* ユーティリティとの一貫性を高めました。
これらの変更に合わせてプロジェクトを更新するには、ring の使用箇所をすべて ring-3 に置き換えます。
<button class="focus:ring ..."><button class="focus:ring-3 ..."> <!-- ... --></button>次に、デフォルトの ring color に依存していた場所に ring-blue-500 を必ず追加してください。
<button class="focus:ring-3 focus:ring-blue-500 ..."> <!-- ... --></button>または、これらのテーマ変数を CSS に追加して、v3 の動作を維持します。
@theme { --default-ring-width: 3px; --default-ring-color: var(--color-blue-500);}ただし、これらの変数は互換性の理由でのみサポートされており、Tailwind CSS v4.0 の慣用的な使用法とは見なされないことに注意してください。
v4 の Preflight のベーススタイルにいくつかの小さな変更を加えました。
v3 では、placeholder テキストは、デフォルトで構成済みの gray-400 カラーを使用していました。v4 では、これを簡略化して、現在のテキストカラーを 50% の opacity で使用するようにしました。
おそらくこの変更に気付かないでしょう（プロジェクトの見栄えが良くなる可能性さえあります）が、v3 の動作を維持したい場合は、この CSS をプロジェクトに追加してください。
@layer base { input::placeholder, textarea::placeholder { color: var(--color-gray-400); }}ボタンは、デフォルトのブラウザーの動作に合わせて、cursor: pointer ではなく cursor: default を使用するようになりました。
デフォルトで cursor: pointer を引き続き使用する場合は、これらのベーススタイルを CSS に追加してください。
@layer base { button:not(:disabled), [role="button"]:not(:disabled) { cursor: pointer; }}Preflight は、他の要素がリセットされる方法と一貫性を持たせるために、<dialog> 要素の margin をリセットするようになりました。
ダイアログをデフォルトで中央に配置する場合は、この CSS をプロジェクトに追加してください。
@layer base { dialog { margin: auto; }}プレフィックスは variants のように表示されるようになり、常にクラス名の先頭にあります。
<div class="tw:flex tw:bg-red-500 tw:hover:bg-red-600"> <!-- ... --></div>プレフィックスを使用する場合でも、プレフィックスを使用していないかのようにテーマ変数を構成する必要があります。
@import "tailwindcss" prefix(tw);@theme { --font-display: "Satoshi", "sans-serif"; --breakpoint-3xl: 120rem; --color-avocado-100: oklch(0.99 0 0); --color-avocado-200: oklch(0.98 0.04 113.22); --color-avocado-300: oklch(0.94 0.11 115.03); /* ... */}生成された CSS 変数には、プロジェクト内の既存の変数との競合を避けるために、プレフィックスが含まれます。
:root { --tw-font-display: "Satoshi", "sans-serif"; --tw-breakpoint-3xl: 120rem; --tw-color-avocado-100: oklch(0.99 0 0); --tw-color-avocado-200: oklch(0.98 0.04 113.22); --tw-color-avocado-300: oklch(0.94 0.11 115.03); /* ... */}v3 では、@layer utilities または @layer components 内で定義したカスタムクラスは、Tailwind によって真のユーティリティクラスとして認識され、hover、focus、または lg などの variants で自動的に動作し、@layer components は常に生成されたスタイルシートで最初に表示されるという違いがありました。
v4 では、ネイティブカスケードレイヤーを使用しており、@layer アットルールをハイジャックしなくなったため、代替として @utility API を導入しました。
@layer utilities { .tab-4 { tab-size: 4; }}@utility tab-4 { tab-size: 4;}カスタムユーティリティは、定義するプロパティの量に基づいてソートされるようになりました。これは、この .btn のようなコンポーネントユーティリティを、追加の構成なしで他の Tailwind ユーティリティで上書きできることを意味します。
@layer components { .btn { border-radius: 0.5rem; padding: 0.5rem 1rem; background-color: ButtonFace; }}@utility btn { border-radius: 0.5rem; padding: 0.5rem 1rem; background-color: ButtonFace;}カスタムユーティリティの登録の詳細については、カスタムユーティリティの追加に関するドキュメントを参照してください。
v3 では、スタックされた variants は右から左に適用されていましたが、v4 では、CSS 構文のように見えるように、左から右に適用されるように更新しました。
この変更に合わせてプロジェクトを更新するには、プロジェクト内の順序依存のスタックされた variants の順序を逆にします。
<ul class="py-4 first:*:pt-0 last:*:pb-0"><ul class="py-4 *:first:pt-0 *:last:pb-0"> <li>One</li> <li>Two</li> <li>Three</li></ul>これらに該当するものはほとんどないでしょう。直接の子 variants (*) とタイポグラフィプラグイン variants (prose-headings) が最も可能性の高いものですが、それでも他の variants とスタックした場合に限ります。
v3 では、CSS 変数を var() なしで任意の values として使用できましたが、最近の CSS の更新により、これが曖昧になることが多いため、v4 ではこの構文を角かっこではなく丸かっこを使用するように変更しました。
この変更に合わせてプロジェクトを更新するには、古い変数の短縮構文の使用箇所を新しい変数の短縮構文に置き換えます。
<div class="bg-[--brand-color]"></div><div class="bg-(--brand-color)"></div>v4 では、プライマリー入力デバイスが hover をサポートしている場合にのみ hover variants が適用されるように更新しました。
@media (hover: hover) { .hover\:underline:hover { text-decoration: underline; }}タッチデバイスでタップ時に hover をトリガーすることに依存する方法でサイトを構築した場合、問題が発生する可能性があります。これが問題になる場合は、古い実装を使用する独自の variants で hover variants をオーバーライドできます。
@custom-variant hover (&:hover);ただし、一般的に、hover 機能は強化機能として扱い、タッチデバイスには hover 機能が実際にはないため、サイトの動作に hover 機能に依存しないことをお勧めします。
transition および transition-color ユーティリティに outline-color プロパティが含まれるようになりました。
つまり、フォーカス時にカスタムカラーで outline を追加した場合、カラーがデフォルトカラーからトランジションするのがわかります。これを回避するには、outline color を無条件に設定するか、両方の状態に対して明示的に設定してください。
<button class="transition hover:outline-2 hover:outline-cyan-500"></button><button class="outline-cyan-500 transition hover:outline-2"></button>v3 には、フレームワーク内の一部のユーティリティを完全に無効にするために使用できる corePlugins オプションがありました。これは v4 ではサポートされなくなりました。
v4 にはすべてのテーマ value の CSS 変数が含まれているため、可能な限り theme() 関数ではなく、これらの変数を使用することをお勧めします。
.my-class { background-color: theme(colors.red.500); background-color: var(--color-red-500);}（CSS 変数がサポートされていないメディアクエリなど）theme() 関数をまだ使用する必要がある場合は、古いドット表記ではなく、CSS 変数名を使用する必要があります。
@media (width >= theme(screens.xl)) {@media (width >= theme(--breakpoint-xl)) { /* ... */}JavaScript 設定ファイルは下位互換性のために引き続きサポートされていますが、v4 では自動的に検出されなくなりました。
JavaScript 設定ファイルをまだ使用する必要がある場合は、@config ディレクティブを使用して明示的にロードできます。
@config "../../tailwind.config.js";JavaScript ベースの設定の corePlugins、safelist、および separator オプションは、v4.0 ではサポートされていません。
v3 では、JavaScript ベースの設定を、他の JavaScript で使用できるフラットオブジェクトに変換するために使用できる resolveConfig 関数をエクスポートしました。
v4 では、代わりに生成する CSS 変数を直接使用できるように、これを削除しました。これにより、はるかにシンプルになり、バンドルサイズが大幅に削減されます。
たとえば、React 用の一般的な Motion ライブラリを使用すると、CSS 変数値との間でアニメーション化できます。
<motion.div animate={{ backgroundColor: "var(--color-blue-500)" }} />JS で解決された CSS 変数値にアクセスする必要がある場合は、getComputedStyle を使用して、ドキュメントルートのテーマ変数の値を取得できます。
let styles = getComputedStyle(document.documentElement);let shadow = styles.getPropertyValue("--shadow-xl");v4 では、メインの CSS ファイルとは別にバンドルされているスタイルシート（例：CSS モジュールファイル、Vue、Svelte、または Astro などの <style> ブロックなど）は、他のファイルで定義されているテーマ変数、カスタムユーティリティ、およびカスタム variants にアクセスできません。
これらの定義をこれらのコンテキストで使用できるようにするには、@reference を使用して、バンドル内の CSS を複製せずにインポートします。
<template> <h1>Hello world!</h1></template><style> @reference "../../app.css"; h1 { @apply text-2xl font-bold text-red-500; }</style>または、@apply をまったく使用せずに、CSS テーマ変数を直接使用することもできます。これにより、Tailwind がこれらのスタイルを処理する必要がなくなるため、パフォーマンスも向上します。
<template> <h1>Hello world!</h1></template><style> h1 { color: var(--text-red-500); }</style>CSS モジュールでの Tailwind の使用の詳細については、ドキュメントをご覧ください。