tailwindcss-debugging

Tailwind CSS のデバッグとトラブルシューティング

よくある問題と解決策

1. スタイルが適用されない

コンテンツ検出を確認する

v4 ではコンテンツが自動的に検出されますが、スタイルが見つからない場合：

/* Explicitly specify sources */
@import "tailwindcss";
@source "./src/**/*.{html,js,jsx,ts,tsx,vue,svelte}";

クラス名を確認する

<div class={`text-${color}-500`}>


<div class={color === 'blue' ? 'text-blue-500' : 'text-red-500'}>

ビルドプロセスを確認する

# Restart dev server
npm run dev

# Clear cache and rebuild
rm -rf node_modules/.vite
npm run build

2. v4 への移行に関する問題

PostCSS プラグインが変更された

// OLD (v3)
export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {}
  }
}

// NEW (v4)
export default {
  plugins: {
    '@tailwindcss/postcss': {}
  }
}

設定が CSS に移動した

/* v4 - Configure in CSS, not JS */
@import "tailwindcss";

@theme {
  --color-primary: oklch(0.6 0.2 250);
}

ダークモードのバリアント

/* v4 - Add if using selector strategy */
@custom-variant dark (&:where(.dark, .dark *));

3. クラスが上書きされる

詳細度を確認する

/* Browser DevTools: Inspect element → Styles panel */
/* Look for crossed-out styles */

解決策

<div class="!mt-0">


<div class="[&]:mt-0">

インポート順を確認する

/* Your custom CSS should come after Tailwind */
@import "tailwindcss";
@import "./custom.css";  /* After Tailwind */

4. タイポグラフィプラグインの問題

スタイルが適用されない

/* Ensure plugin is loaded */
@plugin "@tailwindcss/typography";

prose によってユーティリティが上書きされる

<article class="prose prose-h1:text-4xl prose-a:text-blue-600">


<article class="prose">
  <div class="not-prose">
    <CustomComponent />
  </div>
</article>

5. フォームプラグインの問題

通常の入力フィールドにスタイルが適用されない

<input type="text" />  
<input />              

クラス戦略を使用する

@plugin "@tailwindcss/forms" {
  strategy: class;
}

<input type="text" class="form-input" />

デバッグツール

VS Code 拡張機能

# Install Tailwind CSS IntelliSense
code --install-extension bradlc.vscode-tailwindcss

機能：

• クラス名の自動補完
• CSS を表示するホバープレビュー
• エラーのリンティング
• 色のデコレーター

Debug Screens プラグイン

npm install -D @tailwindcss/debug-screens

@plugin "@tailwindcss/debug-screens";

<body class="debug-screens">

ブラウザーの DevTools

1. 要素を検証 → 計算済みスタイルを確認
2. スタイルパネル → 適用されているルールを確認
3. フィルター → Tailwind クラスを検索
4. 計算済みタブ → 最終的な計算済みの値を確認

生成された CSS を確認する

# Output CSS to file for inspection
npx tailwindcss -o output.css --content './src/**/*.{html,js}'

# With verbose logging
DEBUG=tailwindcss:* npm run build

v4 固有のデバッグ

プラグインの読み込みを確認する

# Look for plugin-related errors
npm run build 2>&1 | grep -i plugin

CSS 変数の出力を確認する

/* In browser DevTools, check :root for variables */
:root {
  --color-blue-500: oklch(...);
  --spacing-4: 1rem;
}

コンテンツ検出に関する問題

/* Add explicit sources if auto-detection fails */
@source "./src/**/*.tsx";
@source "./components/**/*.tsx";

/* Exclude paths */
@source not "./src/generated/**";

よくあるエラーメッセージ

"Cannot find module '@tailwindcss/postcss'"

npm install -D @tailwindcss/postcss

"Unknown at-rule @theme"

v3 のツールを v4 の構文で使用しています。ビルド設定を更新してください：

npm install -D tailwindcss@latest @tailwindcss/postcss@latest

"Class 'X' doesn't exist"

動的クラス生成に関する問題：

// BAD
const classes = `bg-${dynamic}-500`

// GOOD
const colorMap = {
  primary: 'bg-blue-500',
  danger: 'bg-red-500'
}
const classes = colorMap[dynamic]

"Styles not updating in development"

# Restart dev server
npm run dev

# Clear Vite cache
rm -rf node_modules/.vite

# Clear Next.js cache
rm -rf .next

パフォーマンスのデバッグ

CSS 出力が大きい

# Check CSS file size
ls -lh dist/assets/*.css

# If too large, check for:
# 1. Dynamic class generation
# 2. Unnecessary safelisting
# 3. Unused plugins

ビルドが遅い

# Time the build
time npm run build

# v4 should be very fast
# Full build: <1s
# Incremental: microseconds

デバッグチェックリスト

初期設定

• 正しいインポート：@import "tailwindcss";
• PostCSS プラグイン：@tailwindcss/postcss（tailwindcss ではありません）
• Vite プラグイン：@tailwindcss/vite（Vite を使用する場合）
• エントリーポイントで CSS ファイルをインポートしている
• 変更後に開発サーバーを再起動した

スタイルが適用されない場合

• クラス名が完全である（動的生成ではない）
• ファイルがコンテンツパス内にある
• ブラウザーのキャッシュをクリアした
• CSS の詳細度に競合がない
• DevTools で上書きされたスタイルを確認した

移行後

• tailwind.config.js を削除または変換した
• カスタマイズに @theme ディレクティブを使用している
• PostCSS 設定を更新した
• セレクター戦略を使用する場合、ダークモードのバリアントを追加した
• プラグインを v4 対応バージョンに更新した

本番環境での問題

• NODE_ENV=production
• ビルド出力にスタイルが含まれている
• CSS ファイルが正しくリンクされている
• 動的クラス生成に関する問題がない

サポートを受ける

最小限の再現例を作成する

# Create fresh project
npm create vite@latest repro -- --template react-ts
cd repro
npm install -D tailwindcss @tailwindcss/vite

# Add minimal code that shows the issue
# Share on GitHub Issues or Discord

リソース

• 公式ドキュメント
• GitHub のイシュー
• Tailwind CSS Discord
• Stack Overflow