Tailwind CSS v4 移行完全ガイド：新エンジン、CSS-first 設定、パフォーマンスの飛躍

Tailwind CSS v4：アトミック CSS の再定義

v4 は段階的なアップグレードではなく、アーキテクチャの書き直しです——新エンジン（Oxide）が 10 倍のビルド速度をもたらし、CSS-first 設定が JS 設定を置き換えます。

次元	v3	v4
エンジン	PostCSS プラグイン	Rust エンジン (Oxide)
設定	tailwind.config.js	CSS @theme ディレクティブ
コンテンツ検出	content 配列	自動検出
ビルド速度	基準	10x+
コンテナクエリ	プラグイン	ネイティブ対応
3D 変換	プラグイン	ネイティブ対応

---

1. 新エンジン：Oxide

パフォーマンス比較

操作	v3	v4	改善
フルビルド (1000+ ユーティリティ)	~500ms	~50ms	10x
増分 HMR	~50ms	~5ms	10x
大規模プロジェクト (500+ コンポーネント)	~2s	~200ms	10x

Oxide は Rust で記述され、Wasm またはネイティブモジュールを通じてビルドツールに統合されます。

---

2. CSS-first 設定

v3：JS 設定ファイル

// tailwind.config.js
module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: {
        brand: '#3b82f6',
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
      },
    },
  },
  plugins: [require('@tailwindcss/typography')],
};

v4：CSS 設定

/* app.css */
@import "tailwindcss";

@theme {
  --color-brand: #3b82f6;
  --font-sans: "Inter", sans-serif;
  --breakpoint-xs: 475px;
  --spacing-18: 4.5rem;
}

利点：

• 設定が CSS、IDE がネイティブサポート
• JS ランタイム不要
• デザインシステムとの整合が容易

カスタムユーティリティ

@theme {
  --animate-fade-in: fade-in 0.3s ease-out;
}

@keyframes fade-in {
  from { opacity: 0; transform: translateY(-10px); }
  to { opacity: 1; transform: translateY(0); }
}

<div class="animate-fade-in">フェードイン効果</div>

---

3. 自動コンテンツ検出

v4 では content 配列を手動設定する必要がなくなり、プロジェクト構造から自動推論します：

フレームワーク	検出方法
Next.js	app/、src/ を自動スキャン
Vite	src/ を自動スキャン
Nuxt	components/、pages/ を自動スキャン
汎用	プロジェクトルートを自動スキャン

パスを除外する場合：

@import "tailwindcss" source("../src");
/* または除外 */
@import "tailwindcss" source("../src") not("../src/generated");

---

4. ネイティブコンテナクエリ対応

v3 はプラグインが必要

plugins: [require('@tailwindcss-container-queries')]
// <div class="md:max-w-sm"> → @container

v4 ネイティブ対応

<div class="@container">
  <div class="@md:flex-row flex-col">
    コンテナ幅 >= md で水平レイアウト
  </div>
</div>

@theme {
  --container-md: 448px;
}

コンテナクエリクラス	意味
@container	コンテナ定義
@sm:flex-row	コンテナ >= sm で flex-row
@md:grid-cols-2	コンテナ >= md で 2 列
@lg:hidden	コンテナ >= lg で非表示

---

5. ネイティブ 3D 変換対応

<div class="rotate-x-45 rotate-y-30 rotate-z-15
            perspective-500 translate-z-10
            scale-3d scale-x-110 scale-y-90">
  3D 変換要素
</div>

クラス	CSS プロパティ
rotate-x-45	rotateX(45deg)
rotate-y-30	rotateY(30deg)
rotate-z-15	rotateZ(15deg)
perspective-500	perspective(500px)
translate-z-10	translateZ(10px)
scale-3d	scale3d()
backface-hidden	backface-visibility: hidden

---

6. 移行手順

ステップ 1：依存関係のアップグレード

npm install tailwindcss@next @tailwindcss/postcss@next

ステップ 2：PostCSS 設定の更新

// postcss.config.js
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},  // 'tailwindcss' を置き換え
  },
};

ステップ 3：設定ファイルの移行

/* app.css - 新設定 */
@import "tailwindcss";

/* v3 の theme.extend を移行 */
@theme {
  /* colors */
  --color-primary: #3b82f6;
  --color-secondary: #10b981;

  /* fontFamily */
  --font-sans: "Inter", "system-ui", sans-serif;
  --font-mono: "JetBrains Mono", monospace;

  /* spacing */
  --spacing-18: 4.5rem;

  /* breakpoints */
  --breakpoint-xs: 475px;
  --breakpoint-3xl: 1920px;
}

ステップ 4：破壊的変更の処理

v3 の書き方	v4 の書き方	説明
bg-opacity-50	bg-blue-500/50	不透明度修飾子
overflow-ellipsis	text-ellipsis	名称変更
shadow-outline	カスタム	削除

ステップ 5：不要になったプラグインの削除

プラグイン	v4 の代替
@tailwindcss/container-queries	ネイティブ対応
@tailwindcss/3d	ネイティブ対応
@tailwindcss/line-clamp	ネイティブ対応 (line-clamp-3)

---

7. Vite 統合

// vite.config.ts
import tailwindcss from '@tailwindcss/vite';

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

PostCSS ミドルウェア不要——Vite プラグインが直接統合、より高速。

---

8. よくある移行の落とし穴

1. カスタムカラーが効かない

/* 誤り：--color- プレフィックスがない */
@theme {
  --brand: #3b82f6;  /* text-brand, bg-brand が生成されない */
}

/* 正解 */
@theme {
  --color-brand: #3b82f6;  /* text-brand, bg-brand, border-brand が生成される */
}

2. @apply の動作変更

/* v3: @apply は任意のユーティリティを使用可能 */
/* v4: @apply は静的ユーティリティのみ、動的値は不可 */

.button {
  @apply bg-blue-500 text-white;  /* ✅ */
  @apply bg-[#123456];            /* ❌ 直接 CSS を書く */
}

3. プレフィックスモードの変更

/* v3: プレフィックスは JS 設定で */
/* v4: プレフィックスは CSS で */
@import "tailwindcss" prefix(tw);
/* tw-flex, tw-text-lg などが生成される */

---

9. 推奨される移行戦略

1. 新規プロジェクトは v4 を直接使用：移行コストゼロ
2. 既存プロジェクトは段階的に移行：v3 と v4 は異なるエントリポイントで共存可能
3. まず設定を移行：JS 設定を CSS @theme に変換
4. 次に破壊的変更を処理：公式 codemod を使用
5. 最後にプラグインを削除：ネイティブ機能に置き換え

# 公式 codemod
npx @tailwindcss/upgrade@next