Skip to main content

TailwindCSS v4 Migration Guide

Overview​

Ring platform has been successfully migrated to TailwindCSS v4, which introduces significant architectural changes including a faster engine, CSS-first configuration, and enhanced features. This migration was completed to leverage the latest performance improvements and modern web features.

Key Changes Made​

1. CSS Configuration Migration​

Before (v3):

/* Old tailwind.config.ts file + CSS imports */
@tailwind base;
@tailwind components;
@tailwind utilities;

After (v4):

/* All configuration now in CSS */
@import "tailwindcss";

@theme {
  --font-inter: var(--font-inter), sans-serif;
  --color-purple-500: #8B5CF6;
  --color-purple-600: #7C3AED;
  --radius: 0.5rem;
  /* ... */
}

2. Configuration File Changes​

  • βœ… Removed: tailwind.config.ts (replaced by CSS-first config)
  • βœ… Updated: postcss.config.cjs to use @tailwindcss/postcss
  • βœ… Added: VS Code settings for TailwindCSS v4 support

3. Build System Updates​

PostCSS Configuration:

module.exports = {
  plugins: {
    '@tailwindcss/postcss': {
      theme: {
        extend: {
          colors: {
            background: 'var(--background)',
            foreground: 'var(--foreground)',
            // Enhanced CSS variable support
          }
        }
      }
    },
    autoprefixer: {}
  }
}

New Features Available​

1. CSS-First Theme Configuration​

@theme {
  /* Custom colors */
  --color-brand: #3b82f6;
  --color-accent: #8b5cf6;
  
  /* Custom fonts */
  --font-display: "Satoshi", sans-serif;
  
  /* Custom spacing */
  --spacing-18: 4.5rem;
}

2. Enhanced Color Opacity Syntax​

v3 β†’ v4 Migration:

/* Before */
.example { @apply bg-blue-500 bg-opacity-50; }

/* After */
.example { @apply bg-blue-500/50; }

3. Updated Shadow Utilities​

/* Shadow naming changes */
shadow-xs    /* Previously shadow-sm */
shadow-sm    /* Previously shadow */
shadow       /* New default */

VS Code Integration​

Settings Configuration​

{
  "css.customData": [
    {
      "version": 1.1,
      "atDirectives": [
        {
          "name": "@theme",
          "description": "TailwindCSS v4 theme configuration directive"
        },
        {
          "name": "@apply",
          "description": "TailwindCSS utility application directive"
        }
      ]
    }
  ],
  "css.lint.unknownAtRules": "ignore",
  "files.associations": {
    "*.css": "tailwindcss"
  }
}

Breaking Changes Handled​

1. Removed Opacity Utilities​

  • bg-opacity-* β†’ bg-[color]/[opacity]
  • text-opacity-* β†’ text-[color]/[opacity]
  • border-opacity-* β†’ border-[color]/[opacity]

2. Renamed Utilities​

  • shadow-sm β†’ shadow-xs
  • shadow β†’ shadow-sm
  • rounded-sm β†’ rounded-xs
  • rounded β†’ rounded-sm

3. Default Behavior Changes​

  • Border colors now default to currentColor
  • Ring width defaults to 1px (was 3px)
  • Enhanced button cursor behavior

Migration Checklist​

  • Replace @tailwind directives with @import "tailwindcss"
  • Migrate theme configuration from JS to CSS @theme block
  • Remove old config file (tailwind.config.ts)
  • Update PostCSS configuration for v4 compatibility
  • Configure VS Code settings for proper syntax highlighting
  • Test build process to ensure compatibility
  • Verify component styles work correctly

Best Practices​

1. Theme Organization​

@theme {
  /* Colors first */
  --color-*: values;
  
  /* Typography */
  --font-*: values;
  
  /* Spacing */
  --spacing-*: values;
  
  /* Custom properties */
  --radius: 0.5rem;
}

2. CSS Variable Usage​

/* Leverage CSS variables for dynamic theming */
:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
}

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
}

3. Component Layer Organization​

@layer components {
  .button {
    @apply px-4 py-2 rounded-sm bg-primary text-primary-foreground;
  }
  
  .card {
    @apply bg-card text-card-foreground shadow-sm rounded-lg border;
  }
}

Performance Benefits​

  • ⚑ Faster Build Times: Up to 10x faster than v3
  • πŸ“¦ Smaller Bundle Size: More efficient CSS generation
  • πŸ”„ Better Hot Reload: Instant style updates during development
  • 🎨 Enhanced DX: Improved IntelliSense and tooling support

Troubleshooting​

Common Issues​

1. CSS Linting Warnings

// .vscode/settings.json
{
  "css.lint.unknownAtRules": "ignore"
}

2. Build Errors

  • Ensure @tailwindcss/postcss is installed
  • Check PostCSS configuration syntax
  • Verify CSS import order

3. Style Not Applied

  • Check for syntax errors in @theme block
  • Verify CSS variable names
  • Ensure proper @layer usage

Resources​

Migration completed on: 2024-12-XX
Status: βœ… Production Ready
Performance Impact: +10x faster builds