Tailwind CSS v4の変更点と移行ガイド

Tailwind CSS v4 の大きな変化

v4 は単なるアップデートではなく、設定方法から内部エンジンまで再設計されています。

変更点サマリー

	v3	v4
設定ファイル	`tailwind.config.js`	CSS ファイル (`@theme`)
エンジン	PostCSS（Node.js）	Oxide（Rust）
Vite サポート	プラグイン追加が必要	`@tailwindcss/vite` でネイティブ対応
`@apply`	使用可能	非推奨（段階的に廃止方向）
CSS 変数	手動定義	デザイントークンを自動で CSS 変数化

インストール方法（Vite の場合）

npm install tailwindcss @tailwindcss/vite

// vite.config.ts
import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [tailwindcss()],
});

/* src/styles/global.css */
@import "tailwindcss";

tailwind.config.js は不要です。

CSS ファイルで設定する

/* @theme でカラー・フォント・スペーシングを定義 */
@import "tailwindcss";

@theme {
  --color-brand: #3b82f6;
  --color-brand-dark: #1d4ed8;

  --font-sans: "Noto Sans JP", sans-serif;

  --spacing-18: 4.5rem;
}

定義した値はそのまま Tailwind ユーティリティとして使えます：

<div class="bg-brand text-brand-dark p-18 font-sans">...</div>

同時に CSS 変数としてもアクセス可能：

.custom {
  color: var(--color-brand);
}

v3 からの移行チェックリスト

`content` 設定が不要に

v4 は自動でソースファイルをスキャンします。v3 の content 配列は削除してください。

クラス名の変更

shadow-sm  → shadow-xs   （v4 でリネーム）
blur       → blur-sm     （同様）
ring       → ring-1      （デフォルト値変更）

`@apply` の代替

/* v3 */
.btn { @apply px-4 py-2 rounded bg-blue-600 text-white; }

/* v4 推奨 — CSS ネストで書く */
.btn {
  padding: theme(spacing.4) theme(spacing.2);
  border-radius: theme(borderRadius.DEFAULT);
  background-color: theme(colors.blue.600);
  color: white;
}

または Tailwind の CSS @utility を使う：

@utility btn {
  padding: 0.5rem 1rem;
  border-radius: 0.375rem;
  background-color: var(--color-blue-600);
  color: white;
}

ダークモード

/* v4 でのダークモード設定 */
@import "tailwindcss";

@variant dark (&:where(.dark, .dark *));

まとめ

Tailwind CSS v4 の最大の変化は設定を CSS ファイルに統合したことです。tailwind.config.js が不要になり、@theme ブロックで直感的に設定できます。Oxide エンジンにより、ビルド速度も v3 比で大幅に改善されています。

v3 からの移行は破壊的変更があるため、公式マイグレーションガイドを参照しながら進めることを推奨します。

参考: Tailwind CSS v4 公式ドキュメント

S	公式ソース確認済み
A	成功実績多数・失敗例少数
B	賛否両論
C	動作未確認・セキュリティリスク高
Z	個人所感