【Tailwind CSS】3.4→4.3 移行ログ:PostCSS・JS設定・見た目が変わった4箇所

Tailwind CSS 3から4への移行を、重なったスタイルシートから1枚のカードへの変化で表したアイキャッチ画像
目次

Tailwind CSS 3.4 のPostCSS構成が4.3で動かないときの直し方

Tailwind CSS 3.4.19 のPostCSS構成を4.3.5へ上げると、プラグインエラーに加え、ユーティリティ欠落と見た目の変化が起きました。同じ最小プロジェクトで出力CSSを比較しながら、4箇所の修正と確認手順をまとめます。

  • tailwindcss を4系に上げたら、PostCSSのビルドがエラーで止まった
  • ビルドは通るのに、text-brand や shadow-sm が出力CSSから消えた
  • JS設定のカスタムカラーや、ring・shadow・borderの見た目を維持したい

対象読者: Tailwind CSS 3.4 をPostCSSで運用していて、4系へ移行したい人です。

前提知識: npmとPostCSSの基本操作、Tailwindのユーティリティクラスが分かることです。

結論

PostCSS構成ではプラグイン・CSSの読み込み・JS設定・クラス名の4箇所を直します。最後に出力CSSを比較すれば、ビルドが通るだけでは見つからない変更も確認できます。

npm install tailwindcss@4.3.5 @tailwindcss/postcss@4.3.5
npm run build

# 実行結果(修正完了後)
# [v4.3.5 + fixed classes] build exit=0
# fixed .border-gray-200: True
# fixed .shadow-xs: True
# fixed .text-brand: True
# fixed .ring-3: True
# fixed .ring-blue-500: True

公式は新しいブランチで npx @tailwindcss/upgrade を実行する方法を推奨しています。今回は変更を1つずつ確かめるため、公式アップグレードガイドの手動移行手順で進めました。

箇所 起きたこと 直し方
PostCSS v4にした瞬間ビルドが停止 @tailwindcss/postcss を使う
@tailwind 終了コード0でもCSSが欠落 @import “tailwindcss” にする
JS設定 text-brand が消える @config で明示する
クラス 影・リング・枠線の見た目が変わる shadow-xs・ring-3・色指定を使う

移行前の構成と確認方法

移行前は Tailwind CSS 3.4.19・PostCSS・autoprefixer の構成です。カスタムカラー text-brand と、border・shadow-sm・ring を付けた1つのボタンをビルド対象にしました。

// tailwind.config.mjs
export default {
  content: ["./index.html"],
  theme: {
    extend: {
      colors: {
        brand: "#123456",
      },
    },
  },
};

// 実行結果(Tailwind CSS 3.4.19)
// [v3.4.19] build exit=0
// v3 text-brand: True

各段階で npm run build を実行し、出力CSSに目的のセレクタがあるかを調べました。shadow と ring は宣言値まで比較しています。

1. PostCSSプラグインの分離でビルドが止まった

v4では tailwindcss をPostCSSプラグインとして直接指定できません。専用パッケージへの移行が必要です。

npm install tailwindcss@4.3.5
npm run build

# 実行結果
# Error: It looks like you're trying to use `tailwindcss` directly as a PostCSS plugin. The PostCSS plugin has moved to a separate package, so to continue using Tailwind CSS with PostCSS you'll need to install `@tailwindcss/postcss` and update your PostCSS configuration.

@tailwindcss/postcss をインストールし、設定のキーごと置き換えます。

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

// 実行結果
// [v4.3.5 + fixed classes] build exit=0

Tailwindのためだけに使っていた postcss-import と autoprefixer は外せます。v4ではimportの展開とvendor prefix付与をTailwind側が処理するためです。

2. @tailwindのままだとビルド成功なのにCSSが欠けた

最初のエラーを直しただけでは移行は終わりません。v3のディレクティブを残したまま4.3.5でビルドしたところ、終了コードは0なのに2つのクラスが出力されませんでした。

/* src/input.css(移行前) */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* 実行結果 */
/* [v4.3.5 + old @tailwind] build exit=0 */
/* old @tailwind text-brand: False / shadow-sm: False */

公式も @tailwind ディレクティブは削除されたと案内しています。通常のCSS import 1行へ置き換えます。

@import "tailwindcss";
@config "../tailwind.config.mjs";

/* 実行結果 */
/* [v4.3.5 + @config] build exit=0 */
/* @config text-brand: True */

「エラーが無い」を確認先にすると取りこぼします。移行中は主要なクラスが出力CSSに残るかまで見るのが確実です。

3. tailwind.config.mjsが自動で読まれずtext-brandが消えた

@import だけにした段階では、text-brand が出力されませんでした。v4はソースファイルを自動検出しますが、JavaScriptの設定ファイルまでは自動で読み込みません。

@import "tailwindcss";

/* 実行結果 */
/* [v4.3.5 + @import only] build exit=0 */
/* @import only text-brand: False */

既存のJS設定を残すなら、公式のJavaScript config移行説明にある通り @config が必要です。今回はinput.cssから1つ上の階層を指定しました。

なお、v4の自動検出はテンプレート側の話です。公式のソース検出ドキュメントでは、.gitignore の対象やバイナリファイルは除外すると説明されています。

4. shadow・ring・borderの既定値が変わった

同じクラスが残っていても、見た目は元に戻りません。特に shadow-sm はv4で別の段階を指すため、生成CSSを比較すると差が出ます。

/* v3.4.19の出力(宣言を抜粋) */
.shadow-sm {
  --tw-shadow: 0 1px 2px 0 rgb(0 0 0 / 0.05);
}

/* v4.3.5の出力(宣言を抜粋) */
.shadow-sm {
  --tw-shadow: 0 1px 3px 0 var(--tw-shadow-color, rgb(0 0 0 / 0.1)), 0 1px 2px -1px var(--tw-shadow-color, rgb(0 0 0 / 0.1));
}

ring も実測では3pxから1pxに変わり、色のフォールバックは currentcolor になりました。border の既定色も v3のgray-200から currentColor に変わっています。

v3の見た目に寄せるため、クラスを次のように変更しました。

v3: border p-4 shadow-sm text-brand ring
v4: border border-gray-200 p-4 shadow-xs text-brand ring-3 ring-blue-500

実行結果
fixed .border-gray-200: True
fixed .shadow-xs: True
fixed .text-brand: True
fixed .ring-3: True
fixed .ring-blue-500: True

変更点の全一覧は公式の Changes from v3にあります。今回の3つ以外もクラス名の一覧と表示を確認しておきます。

つまずきポイント

  • アップグレードツールにはNode.js 20以上が必要です。今回はNode.js 24.16.0で実行しました。
  • v4の対象はSafari 16.4・Chrome 111・Firefox 128以降です。古いブラウザ対応が必要ならv3.4を維持します。
  • ビルド成功と見た目の維持は別です。カスタムカラー・shadow・ring・borderは出力CSSを比較します。

ブラウザ要件も公式ガイドのBrowser requirementsに明記されています。ここだけ後から気づくと、移行自体をやり直す判断になります。

検証環境

OS Windows 11 (build 10.0.26200)
CPU AMD Ryzen 9 PRO 8945HS w/ Radeon 780M Graphics
メモリ 28GB
言語/ツール Tailwind CSS 3.4.19 / Tailwind CSS 4.3.5 + @tailwindcss/postcss 4.3.5(npmで一時インストール) / Node.js 24.16.0
使用コマンド python migration_check.py(PostCSSビルドと出力CSSの比較)
測定日 2026-11-17

上記の環境で実際に実行して確認した結果です。環境が異なる場合は挙動が変わることがあります。

Tailwind CSS 3.4.19 と 4.3.5 で同じPostCSSプロジェクトをビルドした実測ログ。プラグインエラー、旧@tailwindによるCSS欠落、@configによるカスタムカラー復元、shadow・ringの宣言値の差、修正後の全セレクタ生成までを確認したもの
Tailwind CSS 3.4.19 と 4.3.5 で同じPostCSSプロジェクトをビルドした実測ログ。プラグインエラー、旧@tailwindによるCSS欠落、@configによるカスタムカラー復元、shadow・ringの宣言値の差、修正後の全セレクタ生成までを確認したもの

まとめ

Tailwind CSS 3.4から4.3への移行では、PostCSS周りを直した後に、JS設定とクラスの差分を確認します。今回は4箇所の修正でカスタムカラーを復元し、影・リング・枠線にv3相当の指定を戻せました。

自動ツールを使う場合も、差分確認の観点は同じです。主要コンポーネントのクラスと生成CSSを残しておくと、後から原因を追いやすいですよ。

参考

あわせて読みたい

この記事を書いた人: Kurosaki.Ren。記事のコードは隔離した環境で実行してから掲載しています。詳しいプロフィールは著者プロフィールページへどうぞ。

【広告】このサイトはConoHa WINGで運営しています。安定した高速サーバーで快適にブログを書けています。いつもありがとう!!

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

CAPTCHA


目次