【まとめ】Nuxt UI v3でTailwind CSS v4を使う際の移行ポイントと解決策

backham

2025-09-02

はじめに

Nuxt UI v3 への移行プロジェクトで、Tailwind CSS v4 の統合環境に直面しました。v4 では根本的なアーキテクチャの変更があり、後述する「CSS-first アプローチ」という新しい設計思想が採用されています。約 130 個の Vue コンポーネントを持つプロジェクトで、15 日間かけて移行を完了させました。その過程で遭遇した対応についてのまとめを共有します。

本記事では以下について説明します：

概要

先に結論を書いておくと、Nuxt UI v3 環境では Tailwind CSS v4 が自動統合されているため手動アップグレードは不要ですが、v4 の新しい概念を理解して適切に対応することがポイントでした。

特に重要だったのは、動的クラス生成から CSS 変数を使った実装への移行です。また、プロジェクト独自のカスタムクラス名（アンダースコア使用）も v4 の命名規則に合わせて修正する必要がありました。

Tailwind v4 の CSS 変数についての詳細は、前回の記事「Tailwind CSS v4 で動的クラス名が使えない？CSS 変数と TypeScript で解決する 2 つの方法」もご参照ください。

なぜ Tailwind CSS v4 の理解が重要か

CSS 標準への準拠

v4 では設定方法が根本的に変わり、CSS-first アプローチが採用されました。 JavaScript ベースの設定（tailwind.config.ts）から CSS 設定（@theme）への移行が推奨され、従来の設定ファイルも後方互換性のため使用可能ですが、新機能の多くは CSS 設定で最適に動作します。

これにより、ビルドツールに依存しない標準的な CSS 実装が可能になり、CSS 変数による実行時の動的な値の変更や、ブラウザの開発者ツールでの直接的なデバッグが容易になりました。また、v4 では、新しい高性能エンジンにより、ビルド時間が大幅に短縮されます。 Tailwind CSS 公式のベンチマークによると、フルビルドは最大 3.78 倍高速（378ms → 100ms）となっています。

ブラウザサポート要件

Tailwind CSS v4 は以下のブラウザバージョンが必要です：

Safari 16.4 以上
Chrome 111 以上
Firefox 128 以上

v4 は@propertyやcolor-mix()などの最新 CSS 機能に依存しており、古いブラウザでは動作しません。古いブラウザのサポートが必要な場合は、v3.4 の使用を継続することを推奨します。
（出典：Tailwind CSS v4.0 公式リリースノート）

移行時間の目安

移行時間は、プロジェクトの複雑さ、カスタムコードの量、チームの経験によって大きく異なります。私たちのプロジェクト（環境:Nuxt UI v2.x → v3.3、Vue 3 + Nuxt 4 での約 130 個の Vue コンポーネント）では、初めての移行作業ということもあり、実際に 15 日間で移行を完了させました。動的クラスの対応や検証に特に時間を要しましたが、段階的なアプローチにより安全に移行できました。

CSS-first アプローチとは

v4 では設定方法が根本的に変わり、CSS-first アプローチが採用されました。従来の JavaScript ベースの設定（tailwind.config.ts）から、CSS 内で直接カスタマイズする方法へと移行しています。

従来の v3 設定（tailwind.config.ts）

// tailwind.config.ts
export default {
  theme: {
    extend: {
      colors: {
        accent_primary: "#1EB5B8",
      },
    },
  },
};

v4 の CSS 設定（main.css）

/* main.css */
@import "tailwindcss";
@import "@nuxt/ui";

@theme {
  --color-accent-primary: #1eb5b8;
}

Nuxt UI v3 を使用している場合、この設定は自動的に行われるため、手動での移行作業は最小限で済みます。

主要な変更点と対応

クラス名の変更

v4 では命名規則がより一貫性のあるものに変更されました。また、私たちのプロジェクトでは v3 時代にアンダースコアを使用したカスタムクラス名を定義していたため、これらも v4 の推奨される命名規則（ハイフン区切り）に合わせて修正しました。

<!-- v3（プロジェクト独自のカスタムクラス） -->
<div class="bg-accent_primary z-z_modal">
  <!-- v4（ハイフン区切りに統一） -->
  <div class="bg-accent-primary z-modal"></div>
</div>

移行前に以下のコマンドで影響範囲を調査しました：

# アンダースコアを含むカスタムクラス名の検出
grep -r "bg-[a-zA-Z_]*_[a-zA-Z_]*" --include="*.vue" .

検証ページの作成

本番コードを変更する前に、必ず検証ページを作成して動作確認を行いました。これにより、予期しない問題を事前に発見できます。

<!-- pages/tailwind-v4-test.vue -->
<template>
  <div class="p-8">
    <h1 class="mb-6 text-2xl font-bold">Tailwind v4 検証ページ</h1>

    <section class="mb-8">
      <h2 class="mb-4 text-xl">カスタムカラー</h2>
      <div class="bg-accent-primary rounded p-4 text-white">
        動作確認用のテストエリア
      </div>
    </section>
  </div>
</template>

動的クラスの実装方法

v4 では動的クラス名の生成が推奨されません。代わりに CSS 変数を活用する方法を採用しました。

main.css でのカラー定義

@theme {
  --color-mode-red: #ef4444;
  --color-mode-yellow: #eab308;
  --color-mode-green: #22c55e;
  --color-mode-blue: #3b82f6;
}

CSS 変数を使った実装

<template>
  <div
    class="mode-color rounded p-4"
    :style="{ '--mode-color': getModeColor(props.mode) }"
  >
    {{ props.mode }}モード
  </div>
</template>

<script setup lang="ts">
const getModeColor = (mode: string) => {
  const colors = {
    red: "var(--color-mode-red)",
    yellow: "var(--color-mode-yellow)",
    green: "var(--color-mode-green)",
    blue: "var(--color-mode-blue)",
  };
  return colors[mode];
};
</script>

<style scoped>
.mode-color {
  background-color: var(--mode-color);
}
</style>

この方法により、Tailwind CSS v4 の設計思想に沿いながら、動的なスタイル適用を実現できました。

よくある問題と解決策

max-width メディアクエリの実装

v4 では、max-width ブレークポイントが標準で提供されないため、カスタム実装が必要でした。プロジェクトでは、シンプルな@media ルールで対応しました。

@media (max-width: 1535px) {
  .app-x2l-max\:hidden {
    display: none;
  }
  .app-x2l-max\:block {
    display: block;
  }
  .app-x2l-max\:flex {
    display: flex;
  }
  .app-x2l-max\:grid {
    display: grid;
  }
}

app-プレフィックスを使用することで、Tailwind の標準クラスと明確に区別できます。この方法は標準的な CSS なので、チーム全員が理解しやすいというメリットもあります。

まとめ

Nuxt UI v3 環境での Tailwind CSS v4 統合は、自動化されている部分が多いものの、v4 の新しい概念と変更点を理解することが重要です。

移行を成功させるポイントは、まず CSS-first アプローチを理解し、検証ページで事前テストを行うことです。プロジェクト独自のクラス名規則がある場合は、grep コマンドなどで影響範囲を把握してから体系的に変更します。動的クラスについては、CSS 変数を活用した実装パターンをチーム内で統一し、段階的に移行とコミットを進めることで、問題発生時のロールバックも容易になります。

特に以下の 5 つの点が成功の鍵となります：

CSS-first アプローチの理解と活用
検証ページでの事前テスト
クラス名変更への体系的な対応
動的クラスの適切な実装パターンの選択
継続的な TypeScript エラーチェック

私たちのプロジェクトでは、この手順に従うことで大きな問題なく移行を完了させることができました。 Tailwind CSS v4 の理解を深めることで、Nuxt UI v3 の機能を最大限に活用できるようになります。

参考：Tailwind CSS v4 公式ドキュメント | Nuxt UI v3 公式ドキュメント

最後まで読んでいただき、ありがとうございました！
この記事が少しでもお役に立てれば嬉しいです。良い開発ライフを！