Tailwind CSS v3からv4へのアップグレード方法

問題点

Tailwind CSS v3からv4へのアップグレード時に、以下のエラーが発生するケースが多く報告されています：

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.

このエラーは特に、以下の環境で発生します：

• AngularプロジェクトでTailwind v3を使用中
• 既存のtailwind.config.js設定ファイルあり
• @tailwind baseなどのディレクティブをSCSSファイルで使用
• PostCSSを明示的に使用していない構成

解決策

ステップ1: 公式アップグレードツールの実行

最初にTailwind公式のアップグレードツールを実行します：

npx @tailwindcss/upgrade@next

このツールが自動で設定ファイルをv4互換に変換します。

ステップ2: 必要なパッケージのインストール

以下のコマンドで必要なパッケージをインストールします：

npm install tailwindcss @tailwindcss/postcss postcss --force

ステップ3: PostCSS設定ファイルの作成

プロジェクトルートに.postcssrc.jsonファイルを作成（先頭のドットを忘れずに）：

{
  "plugins": {
    "@tailwindcss/postcss": {}
  }
}

ステップ4: CSSインポート方法の変更

v3の@tailwindディレクティブを使用しているファイルを修正：

- @tailwind base;
- @tailwind components;
- @tailwind utilities;

+ @import "tailwindcss";

ステップ5: SCSSファイルの対応（Angularの場合）

AngularプロジェクトではSCSSからCSSへの移行が推奨されます：

1. .scssファイルを.cssにリネーム
2. ネスト構文などSCSS固有機能をネイティブCSS構文で書き換え
3. コンポーネントごとに設定を参照（必要な場合）：

@config "../../tailwind.config.cjs";

重要な注意点

SCSS/Less/Stylusのサポート終了

Tailwind v4では公式にCSSプリプロセッサのサポートが終了しています：

“Tailwind CSS v4.0は特定のワークフロー向けに設計されたCSSビルドツールであり、Sass、Less、StylusなどのCSSプリプロセッサと一緒に使用するようには設計されていません”

公式ドキュメントでは以下の理由が説明されています：

1. Tailwind自体がネストCSSや変数機能をネイティブサポート
2. プリプロセッサとの機能競合が解消不可能
3. モダンブラウザ対応で従来のプリプロセッサが不要に

設定ファイルの移行に関する注意

• tailwind.config.jsの内容は自動移行されない場合あり
• @themeディレクティブを使った新しい設定方法を採用
• カスタムテーマは手動移行が必要なケースも

module.exports = {
  // v4互換の設定形式
  theme: {
    extend: {
      colors: {
        // カスタムカラー定義
      }
    }
  }
}

トラブルシューティング

1. アップグレード後スタイルが適用されない

   • @import "tailwindcss";の記述ミスを確認
   • .postcssrc.jsonの設置場所とファイル名を再確認（先頭のドット必須）

2. 個別コンポーネントでスタイルが壊れる

   • 各コンポーネントのスタイルファイル先頭に追加：

     @config "../path/to/tailwind.config.cjs";

3. VSCodeでIntelliSenseが動作しない

   • @tailwindcss/postcssパッケージがインストールされているか確認

   • settings.jsonに以下を追加：

     "tailwindCSS.includeLanguages": {
        "plaintext": "html"
     }

ベストプラクティス

1. 段階的な移行を実施

   • 新規コンポーネントからv4の構文で実装
   • 既存コンポーネントは徐々に移行

2. 自動テストでリグレッション防止

   • ビジュアルリグレッションテストの導入を推奨
   • 主要コンポーネントのスクリーンショット比較

3. パフォーマンスモニタリング

   • ビルド時間の変化を計測
   • 本番環境CSSファイルサイズを比較

最新のアップグレード情報については、公式アップグレードガイドとAngularフレームワークガイドを常に参照してください。