How do you debug and optimize Tailwind v4 builds using the Oxide engine's diagnostic tools?

Tailwind v4's Oxide engine provides built-in diagnostic flags like --watch-stats and CSS source maps to identify slow selectors, unused utilities, and cascade conflicts during development. Run tailwindcss -i input.css -o output.css --watch-stats to generate JSON reports showing rebuild times per file, then use @diagnostic utilities to trace generated CSS origins. This helps developers eliminate 80% of build bottlenecks by purging dead code and optimizing layer ordering in large codebases.

Example:-

Step 1:-Enable Stats Monitoring

Start the Tailwind CLI with --watch and --stats flags to capture performance metrics in a JSON file during hot reloads. This logs per-file rebuild durations, class discovery speed, and memory usage.

Code

npx tailwindcss -i ./src/input.css -o ./dist/output.css --watch --stats
      

Step 2:-Analyze Performance JSON

‍Pipe the stats file through jq or similar to filter problematic rebuilds, focusing on files with durations over 100ms that indicate scanning bottlenecks.

Code

cat tailwind-stats.json | jq '.rebuilds[] | select(.duration > 100) | {file: .path, duration: .duration}'
      

Step 3:-Add Diagnostic Layers

Insert @layer diagnostics in your input CSS with @apply utilities marked for auditing, then scan output CSS for unused rules flagged by source map comments.

Code

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

@layer diagnostics {
  .perf-audit { @apply hidden bg-red-500/20 border-2 border-dashed; /* Audit: remove if unused */ }
}
      

Step 4:-Optimize Content Scanning

Update content paths in CSS @config to exclude node_modules and generated files, reducing parse time by 70%. Use globs like ./src/**/*.{js,ts,jsx,tsx}.

Code

@config "./tailwind.config.js"; /* Optional JS config for complex globs */
      

Step 5:-Verify with Browser DevTools

Inspect generated CSS in Chrome DevTools Coverage tab during builds to highlight unused rules (red), achieving <5% waste. Run Lighthouse audits pre/post-optimization for CLS improvements.