{
  "id": 19291814,
  "title": "Upgrading three Tailwind projects to v4 in one sprint",
  "url": "https://urgent.news/2026/11/10/upgrading-three-tailwind-projects-to-v4-in-one-sprint",
  "topic": "tech",
  "section": "Tech",
  "published": "2026-11-10T06:01:00.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/richardlemon/upgrading-three-tailwind-projects-to-v4-in-one-sprint-5gfa"
  },
  "original_language": "en",
  "account": "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.\n\nBefore 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.\n\nThe 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.\n\nThe 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.\n\nThe 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.\n\nThe 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.\n\nAddressing 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.",
  "summary": "Why I upgraded three sites in the same week I had three client projects on Tailwind 3.x that all needed new features in the same sprint. Tailwind v4 was out, the new engine looked fast enough to justify the risk, and I did not want to maintain two different utility dialects for long. So I blocked a week and upgraded all three in one go. This is what actually mattered: the utilities that kept…",
  "key_points": [
    "Three Tailwind projects upgraded to v4 in one sprint",
    "Assessment of custom Tailwind code, class usage, and utilities conducted",
    "Custom gradient border plugin in Gate Seal site required additional work"
  ],
  "editors_take": "Phasing upgrades from simple sites to complex systems reduces technical risk, though custom plugins require treating them as bespoke framework components rather than simple utility files.",
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}