🚨 問題：ローカルでは動くのに本番環境でCSSが完全に崩れる

Next.js 15 + Tailwind CSS v4のプロジェクトで、以下のような症状に悩まされました：

✅ npm run dev → 正常に表示
✅ npm run build → ビルド成功
❌ Vercelデプロイ → CSSが完全に崩れる

📝 環境

{
  "dependencies": {
    "next": "15.3.3",
    "react": "^19.0.0"
  },
  "devDependencies": {
    "@tailwindcss/postcss": "^4",
    "tailwindcss": "^4"
  }
}

🔍 原因：Tailwind CSSがdevDependenciesにある

Vercelのビルド環境では、NODE_ENV=productionでビルドが実行されます。この時、devDependenciesはインストールされません。

# Vercelでの実際のビルドコマンド
npm ci --production  # devDependenciesはスキップされる！
npm run build

Tailwind CSS v4では、ビルド時にPostCSSプラグインとして動作するため、本番ビルドでも必要です。しかし、devDependenciesにあるため、Vercelのビルド環境では利用できず、CSSの処理がスキップされてしまいます。

💡 解決策：dependenciesに移動する

1. package.jsonを修正

{
  "dependencies": {
    "next": "15.3.3",
    "react": "^19.0.0",
+   "@tailwindcss/postcss": "^4",
+   "tailwindcss": "^4"
  },
  "devDependencies": {
-   "@tailwindcss/postcss": "^4",
-   "tailwindcss": "^4",
    "@types/node": "^20",
    "typescript": "^5"
  }
}

2. 依存関係を再インストール

npm install

3. 変更をコミット＆プッシュ

git add package.json package-lock.json
git commit -m "Move Tailwind CSS to production dependencies"
git push

4. Vercelで再デプロイ

vercel deploy --prod

初回は念のため--forceフラグを使用してキャッシュをクリア：

vercel deploy --prod --force

🎯 なぜこれで解決するのか？

devDependencies vs dependencies

種別	ローカル開発	本番ビルド	用途
dependencies	✅ インストール	✅ インストール	実行時に必要なパッケージ
devDependencies	✅ インストール	❌ スキップ	開発時のみ必要なパッケージ

Tailwind CSS v4の仕組み

Tailwind CSS v4は、PostCSSプラグインとしてビルド時にCSSを生成します：

@import "tailwindcss" を検出
使用されているクラスをスキャン
必要なCSSのみを生成
最適化されたCSSファイルを出力

この処理はビルド時に行われるため、本番ビルドでもTailwind CSSが必要です。

⚠️ よくある間違い

1. lightningcssを手動で追加する

// ❌ これはNG！
"optionalDependencies": {
  "lightningcss-linux-x64-gnu": "^1.30.1",
  "lightningcss-linux-arm64-gnu": "^1.30.1"
}

Tailwind CSS v4は内部でlightningcssを使用していますが、手動で追加するとバージョンの競合が発生し、CSSの処理が正しく行われません。

2. Tailwind CSS v3の設定ファイルを残す

// ❌ v4では不要！
// tailwind.config.js
module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  // ...
}

Tailwind CSS v4では設定ファイルが不要です。削除しましょう。

✅ 正しい設定

postcss.config.mjs

export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

globals.css

@import "tailwindcss";
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@100;200;300;400;500;600;700;800;900&display=swap');

/* カスタムCSS変数やスタイル */
:root {
  --background: #fafafa;
  --foreground: #0a0a0a;
}

🚀 デバッグのヒント

1. ローカルで本番ビルドをテスト

npm run build && npm run start
# http://localhost:3000 でCSSが正しく表示されるか確認

2. ビルド出力のCSSを確認

# ビルド後のCSSファイルを確認
find .next/static -name "*.css" | head -5

# Tailwindクラスが含まれているか確認
grep -E "(\.flex\{|\.text-|\.bg-)" .next/static/css/*.css | head -10

3. Vercelのビルドログを確認

vercel logs <deployment-url>

📚 まとめ

Tailwind CSS v4は本番ビルドでも必要 → dependenciesに配置
devDependenciesの罠に注意（本番ビルドではインストールされない）
lightningcssは手動で追加しない（Tailwind CSS v4が内部で管理）
設定ファイルは不要（v3からの移行時は削除）

この問題は、Tailwind CSS v4の仕組みを理解していれば簡単に解決できます。ビルド時に必要なパッケージは必ずdependenciesに配置しましょう！

🔗 参考リンク

この記事が同じ問題で悩んでいる方の助けになれば幸いです！