Tailwind CSSでハマりがちな落とし穴3選｜動的クラス名・コンフリクト・v4の変更点

Tailwind CSSを使い始めて「なぜかスタイルが効かない」と頭を抱えた経験はないだろうか。ユーティリティファーストという設計思想は強力だが、独特の落とし穴がいくつかある。

この記事では、Tailwind CSSの初心者から中級者がつまずきやすいポイントを3つに絞って解説する。

落とし穴1：動的クラス名が効かない

Tailwind CSSはビルド時にクラス名をスキャンして必要なCSSだけを生成する。そのため、JavaScriptで動的にクラス名を組み立てると、ビルド時に検出されず、スタイルが適用されない。

たとえば、以下のコードは動作しない。

// ❌ これは効かない
const color = "red";
<div className={`bg-${color}-500`}>

解決策は、クラス名を完全な文字列として記述することだ。

// ✅ 正しい書き方
const colorClass = color === "red" ? "bg-red-500" : "bg-blue-500";
<div className={colorClass}>

もう一つの方法として、safelistに動的に使うクラスを登録する手もある。しかし、safelistの乱用はビルドサイズを増やすので注意が必要だ。

Tailwindのユーティリティクラスを複数指定した時、意図しない方が優先されるケースがある。たとえばp-4 px-2と書いた場合、期待通りに横方向のパディングだけ上書きされるかどうかは、CSSの生成順序に依存する。

この問題を解決するには、tailwind-mergeライブラリを使う。コンポーネントに渡されるクラス名を自動的にマージし、コンフリクトを解消してくれる。

import { twMerge } from 'tailwind-merge';
<div className={twMerge("p-4", "px-2")}>
// → px-2 が正しく優先される

Tailwind CSS v4では、設定ファイル（tailwind.config.js）が廃止され、CSSファイル内で直接設定を記述する方式に変わった。v3から移行する際に戸惑うポイントだ。

/* v4の設定方法 */
@theme {
  --color-primary: #3b82f6;
  --font-sans: "Inter", sans-serif;
}

既存プロジェクトを移行する場合は、公式のアップグレードガイドを参照するのが確実だ。自動移行ツールも提供されている。

Tailwind CSSの落とし穴は、仕組みを理解すれば回避できるものばかりだ。動的クラス名は完全な文字列で書く、コンフリクトにはtailwind-mergeを使う、v4の設定変更に備える──この3つを押さえておけば、大半のトラブルは防げるだろう。