🌟
Vercelデプロイ時にCSSが崩れる問題を解決！Tailwind CSS v4の依存関係の罠
🚨 問題：ローカルでは動くのに本番環境で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に配置しましょう！
🔗 参考リンク
この記事が同じ問題で悩んでいる方の助けになれば幸いです！
Discussion