Core Code
Core Code Modern Dev Handbook

Tailwind with Frameworks (React/Next/Vite)

Integration patterns and common gotchas.
On this page

The real problem: competing styling systems

Integrating Tailwind into an existing framework is less about installation and more about preventing conflicts: CSS order, resets, component libraries, and class naming conventions. In production, the goal is to make Tailwind the system of record for new UI while safely coexisting with legacy styles during migration.

Pick an integration strategy

  • Greenfield inside a legacy app: new pages/components use Tailwind; legacy CSS remains for older areas.
  • Incremental migration: replace UI area by area; define token mapping and remove dead CSS continuously.
  • Framework UI coexistence: keep the framework components for some features, but stop expanding their usage.

Prevent CSS order surprises

Order matters. Make Tailwind’s base/components/utilities predictable, and keep legacy CSS clearly separated. Avoid mixing framework CSS and Tailwind in random order across pages.

Reset and typography alignment

Frameworks often ship aggressive resets and typography defaults. Decide which system owns base styles. If Tailwind (or its preflight) owns base, ensure the framework resets do not override it. If legacy owns base, tailor Tailwind usage to utilities and component extraction without fighting global defaults.

Contain legacy styles during migration

If a framework’s CSS is hard to remove immediately, scope it. A practical pattern is to wrap legacy UI in a container class and scope framework CSS to that container when possible. This reduces accidental overrides in Tailwind areas.

Component boundaries: templates beat custom CSS

In PHP projects, the cleanest boundary is at the template level: Tailwind markup lives inside partials/components. This keeps UI patterns consistent and avoids bleeding framework styling into new components.

Icons, forms, and third-party widgets

Framework ecosystems often include form styles and widgets that come with strong CSS opinions. For production, treat third-party widgets as integration zones: either accept their styling as-is, or wrap and restyle them with explicit Tailwind utilities and minimal overrides.

Design tokens as a bridge

When migrating from a framework, define a token layer (colors, spacing, radius, shadow). Map legacy variables to new tokens where possible. This reduces visual drift and makes parallel systems manageable while you transition.

Audit and remove dead CSS continuously

Migration fails when old CSS accumulates forever. Add a routine: track which pages still depend on framework styles, remove unused bundles, and measure final CSS size regularly. A smaller CSS surface area reduces bugs and speeds up iteration.

Production checklist

  • Is CSS ordering consistent across all pages?
  • Who owns base styles: Tailwind preflight or legacy reset?
  • Are legacy styles scoped or clearly separated?
  • Do new components live in reusable PHP partials?
  • Is there an active plan to remove framework CSS over time?
Performance Optimization →