Upgrading three Tailwind projects to v4 in one sprint

Upgrading three Tailwind projects to version 4 within a single sprint was the objective. The decision to move to Tailwind v4 was influenced by the new engine's performance, the desire to avoid maintaining multiple utility styles, and the urgency to avoid juggling two different utility systems for too long. The process was executed in three sequential phases: starting with a simple marketing site, followed by a shared design system, and concluding with a complex Gate Seal site featuring a custom gradient border plugin.

Before initiating any configuration changes, the reporter conducted three preliminary assessments for each project. The first involved a quick scan of the codebase to identify the extent of custom Tailwind elements. This included locating custom plugins, heavy usage of @apply directives, design tokens embedded in the Tailwind theme, and any dependencies on the older JIT behavior or file scanning. Projects with higher levels of custom Tailwind code were deferred to later stages.

The second assessment focused on the locations where Tailwind classes were defined. The reporter made a detailed inventory of Tailwind class usage across different frameworks, inline HTML fields within CMS platforms, markdown content rendered with class names, and any atypical placements such as JSON configurations or data attributes. This inventory proved invaluable when detecting missing styles post-upgrade.

The third assessment concentrated on the specific utilities being employed. The reporter did not generate a comprehensive usage report, but manually searched for commonly altered classes such as typography, spacing scales, and color utilities. Projects heavily reliant on certain utility patterns were scrutinized early after the upgrade to prevent any post-deployment issues.

The reporter meticulously removed unnecessary configuration items from each project's Tailwind configuration file. Configurations were streamlined by eliminating old purge and content scanning settings, redundant theme extensions that were either unused or redundant, and custom variants that were never implemented. This cleanup both reduced the complexity of the configuration and minimized the risk of unexpected behavior post-upgrade.

The reporter confirmed that the majority of core Tailwind utilities functioned as anticipated after the upgrade. Commonly used utilities like flexbox and grid layouts, spacing adjustments, typography basics, borders, shadows, and background colors adhered to their expected behavior. However, the upgrade introduced complications primarily due to custom plugins, specifically the gradient border plugin in the Gate Seal site.

This plugin ceased to function correctly with Tailwind v4 due to changes in how utility classes are registered and consumed.

Addressing this issue proved more time-consuming than initially anticipated. The reporter had to understand the plugin's interaction with the previous API, decide whether to patch, rewrite, or replace the plugin, and subsequently update the corresponding components. The primary takeaway from this experience was to treat custom plugins that delve into Tailwind's internal workings as bespoke framework components rather than generic utility files.