| name | tailwindcss-debugging |
| description | Tailwind CSS debugging and troubleshooting common issues. PROACTIVELY activate for: (1) classes not applying / no styles in browser, (2) JIT mode not picking up dynamic class names (string concatenation), (3) v3-to-v4 migration errors, (4) PostCSS configuration issues, (5) IntelliSense not autocompleting in VS Code, (6) production build missing classes (purge/content config), (7) CSS variable conflicts, (8) specificity issues with @layer, (9) prefix conflicts with other CSS frameworks, (10) HMR not updating styles. Provides: troubleshooting decision tree, dynamic-class allowlist patterns, content-config templates, IntelliSense setup, and PostCSS debugging steps. |
Tailwind CSS Debugging & Troubleshooting
Common Issues & Solutions
1. Styles Not Applying
Check Content Detection
v4 automatically detects content, but if styles are missing:
@import "tailwindcss";
@source "./src/**/*.{html,js,jsx,ts,tsx,vue,svelte}";
Verify Class Names
<div class={`text-${color}-500`}>
<div class={color === 'blue' ? 'text-blue-500' : 'text-red-500'}>
Check Build Process
npm run dev
rm -rf node_modules/.vite
npm run build
2. v4 Migration Issues
PostCSS Plugin Changed
export default {
plugins: {
tailwindcss: {},
autoprefixer: {}
}
}
export default {
plugins: {
'@tailwindcss/postcss': {}
}
}
Configuration Moved to CSS
@import "tailwindcss";
@theme {
--color-primary: oklch(0.6 0.2 250);
}
Dark Mode Variant
@custom-variant dark (&:where(.dark, .dark *));
3. Classes Being Overridden
Check Specificity
Solutions
<div class="!mt-0">
<div class="[&]:mt-0">
Check Import Order
@import "tailwindcss";
@import "./custom.css";
4. Typography Plugin Issues
Styles Not Applied
@plugin "@tailwindcss/typography";
Utilities Overridden by Prose
<article class="prose prose-h1:text-4xl prose-a:text-blue-600">
<article class="prose">
<div class="not-prose">
<CustomComponent />
</div>
</article>
5. Forms Plugin Issues
Styles Not Applied to Plain Inputs
<input type="text" />
<input />
Using Class Strategy
@plugin "@tailwindcss/forms" {
strategy: class;
}
<input type="text" class="form-input" />
Debugging Tools
VS Code Extension
code --install-extension bradlc.vscode-tailwindcss
Features:
- Autocomplete for class names
- Hover previews showing CSS
- Linting for errors
- Color decorators
Debug Screens Plugin
npm install -D @tailwindcss/debug-screens
@plugin "@tailwindcss/debug-screens";
<body class="debug-screens">
Browser DevTools
- Inspect Element → See computed styles
- Styles Panel → See which rules apply
- Filter → Search for Tailwind classes
- Computed Tab → See final computed values
Check Generated CSS
npx tailwindcss -o output.css --content './src/**/*.{html,js}'
DEBUG=tailwindcss:* npm run build
v4 Specific Debugging
Check Plugin Loading
npm run build 2>&1 | grep -i plugin
Verify CSS Variable Output
:root {
--color-blue-500: oklch(...);
--spacing-4: 1rem;
}
Content Detection Issues
@source "./src/**/*.tsx";
@source "./components/**/*.tsx";
@source not "./src/generated/**";
Common Error Messages
"Cannot find module '@tailwindcss/postcss'"
npm install -D @tailwindcss/postcss
"Unknown at-rule @theme"
Using v3 tooling with v4 syntax. Update your build setup:
npm install -D tailwindcss@latest @tailwindcss/postcss@latest
"Class 'X' doesn't exist"
Dynamic class generation issue:
const classes = `bg-${dynamic}-500`
const colorMap = {
primary: 'bg-blue-500',
danger: 'bg-red-500'
}
const classes = colorMap[dynamic]
"Styles not updating in development"
npm run dev
rm -rf node_modules/.vite
rm -rf .next
Performance Debugging
Large CSS Output
ls -lh dist/assets/*.css
Slow Builds
time npm run build
Debugging Checklist
Initial Setup
Styles Not Applying
After Migration
Production Issues
Getting Help
Create Minimal Reproduction
npm create vite@latest repro -- --template react-ts
cd repro
npm install -D tailwindcss @tailwindcss/vite
Resources
