Tailwind CSS v4

FlexiUI is built to work seamlessly with Tailwind CSS v4, leveraging the latest features and improvements. This guide covers everything you need to know about using Tailwind v4 with FlexiUI and migrating from v3.

What's New in Tailwind CSS v4

Tailwind CSS v4 represents a major evolution of the framework with groundbreaking changes:

Lightning-Fast Engine

Rebuilt in Rust - Core engine rewritten for maximum performance
10x faster builds - Significantly improved build times in development and production
Instant feedback - Near-instantaneous updates during development
Optimized memory usage - More efficient resource utilization

Unified Toolchain

Single package - All features included in one package
No PostCSS required - Built-in CSS processing
Simplified setup - Fewer dependencies and configuration files
Integrated CLI - Powerful command-line tools included

CSS-First Configuration

Native CSS variables - Configure using @theme directive
Better composition - Easier theme customization
Type-safe - Full TypeScript support
Dynamic theming - Runtime theme switching support

Developer Experience

Improved IntelliSense - Better autocomplete in VS Code
Better error messages - Clear, actionable error reporting
Automatic imports - Auto-import Tailwind directives
Source maps - Better debugging in DevTools

Installation

New Project

For new projects, install Tailwind CSS v4:

npm install tailwindcss@next @tailwindcss/postcss@next

FlexiUI Setup

Install FlexiUI packages alongside Tailwind v4:

npm install @flexi-ui/theme @flexi-ui/system tailwindcss@next

Configuration

Basic Configuration

Create a minimal tailwind.config.ts:

import type { Config } from 'tailwindcss'
import { flexiui } from '@flexi-ui/theme'
 
const config: Config = {
  content: [
    './app/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
    './node_modules/@flexi-ui/theme/dist/**/*.{js,ts,jsx,tsx}',
  ],
  plugins: [flexiui()],
}
 
export default config

CSS Configuration

In your main CSS file (e.g., globals.css):

@import 'tailwindcss';
 
@theme {
  /* Custom theme variables */
  --color-primary: #0070f3;
  --color-secondary: #7928ca;
  --font-sans: system-ui, -apple-system, sans-serif;
}

With FlexiUI Theme

FlexiUI automatically configures Tailwind with optimized defaults:

import { flexiui } from '@flexi-ui/theme'
 
export default {
  plugins: [
    flexiui({
      themes: {
        light: {
          colors: {
            primary: {
              DEFAULT: '#0070f3',
              foreground: '#ffffff',
            },
            secondary: {
              DEFAULT: '#7928ca',
              foreground: '#ffffff',
            },
          },
        },
        dark: {
          colors: {
            primary: {
              DEFAULT: '#3291ff',
              foreground: '#000000',
            },
          },
        },
      },
    }),
  ],
}

Migration from Tailwind CSS v3

Step 1: Update Dependencies

Update your package.json:

# Remove old dependencies
npm uninstall tailwindcss autoprefixer postcss
 
# Install v4
npm install tailwindcss@next

Step 2: Update PostCSS Configuration

Tailwind v4 has a simpler PostCSS setup. Update postcss.config.js:

Before (v3):

module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

After (v4):

module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

Or use the new CSS-first approach (no PostCSS config needed):

/* globals.css */
@import 'tailwindcss';

Step 3: Update CSS Files

Before (v3):

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

After (v4):

@import 'tailwindcss';

Step 4: Migrate Theme Configuration

Convert JavaScript theme config to CSS:

Before (v3):

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#0070f3',
        secondary: '#7928ca',
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
      },
    },
  },
}

After (v4):

/* globals.css */
@theme {
  --color-primary: #0070f3;
  --color-secondary: #7928ca;
  --font-sans: Inter, sans-serif;
}

Step 5: Update Content Paths

Ensure content paths are correct:

// tailwind.config.ts
export default {
  content: [
    './app/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
    // Include FlexiUI components
    './node_modules/@flexi-ui/theme/dist/**/*.{js,ts,jsx,tsx}',
  ],
}

Breaking Changes

CSS Import Syntax

The @tailwind directive is replaced with @import:

/* Old */
@tailwind base;
@tailwind components;
@tailwind utilities;
 
/* New */
@import 'tailwindcss';

Theme Configuration

Theme is now configured in CSS, not JavaScript:

@theme {
  /* All theme customization goes here */
  --color-primary: #0070f3;
  --breakpoint-sm: 640px;
  --font-sans: system-ui;
}

Plugin API Changes

Some plugin APIs have changed. FlexiUI handles this automatically, but if you have custom plugins:

// v3 plugin
function myPlugin({ addUtilities }) {
  addUtilities({
    '.my-utility': {
      display: 'flex',
    },
  })
}
 
// v4 plugin (similar but with enhanced features)
function myPlugin({ addUtilities }) {
  addUtilities({
    '.my-utility': {
      display: 'flex',
    },
  })
}

Removed Features

Some v3 features have been removed or replaced:

JIT mode - Now the only mode (no legacy mode)
Purge option - Replaced with content (already standard in v3)
Mode option - No longer needed

New Features

CSS Theme Configuration

Define your theme using native CSS:

@theme {
  /* Colors */
  --color-primary-50: #eff6ff;
  --color-primary-100: #dbeafe;
  --color-primary-200: #bfdbfe;
  --color-primary-500: #3b82f6;
  --color-primary-900: #1e3a8a;
 
  /* Spacing */
  --spacing-xs: 0.5rem;
  --spacing-sm: 0.75rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  --spacing-xl: 2rem;
 
  /* Typography */
  --font-sans: 'Inter', system-ui, sans-serif;
  --font-mono: 'Fira Code', monospace;
 
  /* Border radius */
  --radius-sm: 0.25rem;
  --radius-md: 0.5rem;
  --radius-lg: 1rem;
 
  /* Breakpoints */
  --breakpoint-sm: 640px;
  --breakpoint-md: 768px;
  --breakpoint-lg: 1024px;
  --breakpoint-xl: 1280px;
}

Container Queries

Native container query support:

<div className="@container">
  <div className="@lg:grid-cols-3">
    <!-- Responsive to container size -->
  </div>
</div>

Cascade Layers

Better control over CSS specificity:

@layer components {
  .btn {
    @apply px-4 py-2 rounded;
  }
}

Native Nesting

Write nested CSS without plugins:

.card {
  @apply p-4 rounded;
 
  &:hover {
    @apply shadow-lg;
  }
 
  .card-title {
    @apply text-xl font-bold;
  }
}

FlexiUI-Specific Features

Automatic v4 Support

FlexiUI automatically detects Tailwind v4 and uses optimized features:

import { flexiui } from '@flexi-ui/theme'
 
export default {
  plugins: [
    flexiui({
      // Automatically uses v4 features when available
      themes: {
        light: { /* ... */ },
        dark: { /* ... */ },
      },
    }),
  ],
}

CSS Variable Integration

FlexiUI themes work seamlessly with v4's CSS variables:

@theme {
  /* FlexiUI automatically generates these */
  --color-primary: #0070f3;
  --color-secondary: #7928ca;
 
  /* You can override them */
  --color-primary: #ff0000;
}

Component Optimization

FlexiUI components are optimized for v4's performance:

Smaller bundle sizes
Faster build times
Better tree-shaking
Optimized CSS output

Framework Integration

Next.js

For Next.js projects with Tailwind v4:

// next.config.js
const config = {
  experimental: {
    // Enable CSS optimizations
    optimizeCss: true,
  },
}
 
export default config

/* app/globals.css */
@import 'tailwindcss';
 
@theme {
  --color-primary: #0070f3;
}

Vite

For Vite projects:

// vite.config.ts
import { defineConfig } from 'vite'
 
export default defineConfig({
  css: {
    transformer: 'lightningcss',
  },
})

Remix

For Remix projects:

// remix.config.js
module.exports = {
  tailwind: true,
  postcss: true,
}

Performance Optimizations

Build Performance

Tailwind v4 offers significant performance improvements:

# v3 build time: ~3s
# v4 build time: ~0.3s (10x faster)

Production Optimizations

Enable all optimizations in production:

// tailwind.config.ts
export default {
  // v4 automatically optimizes for production
  content: ['./app/**/*.{js,ts,jsx,tsx}'],
}

Development Performance

Lightning-fast development builds:

Instant updates - Changes reflect immediately
Incremental builds - Only rebuild what changed
Optimized watchers - Efficient file watching

Best Practices

1. Use CSS Theme Configuration

Prefer CSS configuration over JavaScript:

/* Recommended */
@theme {
  --color-primary: #0070f3;
}

// Avoid when possible
export default {
  theme: {
    extend: {
      colors: {
        primary: '#0070f3',
      },
    },
  },
}

2. Leverage Native Features

Use v4's native features instead of plugins:

/* Use native nesting */
.card {
  @apply p-4;
 
  .title {
    @apply text-xl;
  }
}

3. Optimize Content Paths

Be specific with content paths:

export default {
  content: [
    // Specific paths are faster
    './app/**/*.{js,ts,jsx,tsx}',
    // Avoid broad patterns like './**/*'
  ],
}

4. Use Container Queries

Take advantage of container queries:

<div className="@container">
  <div className="@md:flex @lg:grid-cols-2">
    <!-- Container-responsive -->
  </div>
</div>

5. Minimize Custom CSS

Let Tailwind handle styling:

<!-- Prefer utilities -->
<div className="flex items-center gap-4">
 
<!-- Avoid custom CSS when possible -->
<div style={{ display: 'flex', alignItems: 'center', gap: '1rem' }}>

Troubleshooting

Styles Not Applying

Problem: Tailwind styles not working after upgrading to v4.

Solution: Ensure you're using the new import syntax:

/* Correct */
@import 'tailwindcss';
 
/* Incorrect (v3 syntax) */
@tailwind base;
@tailwind components;
@tailwind utilities;

Build Errors

Problem: Build fails with PostCSS errors.

Solution: Update PostCSS configuration:

npm install @tailwindcss/postcss@next

// postcss.config.js
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

IntelliSense Not Working

Problem: VS Code autocomplete not working.

Solution: Update Tailwind CSS IntelliSense extension and add settings:

// .vscode/settings.json
{
  "tailwindCSS.experimental.classRegex": [
    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"],
    ["cx\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
  ],
  "tailwindCSS.includeLanguages": {
    "typescript": "javascript",
    "typescriptreact": "javascript"
  }
}

Theme Variables Not Working

Problem: CSS theme variables not applying.

Solution: Ensure theme is defined before use:

@import 'tailwindcss';
 
@theme {
  --color-primary: #0070f3;
}
 
/* Now you can use it */
.my-class {
  color: var(--color-primary);
}

FlexiUI Components Not Styled

Problem: FlexiUI components have no styles.

Solution: Include FlexiUI in content paths:

export default {
  content: [
    './app/**/*.{js,ts,jsx,tsx}',
    // Don't forget this!
    './node_modules/@flexi-ui/theme/dist/**/*.{js,ts,jsx,tsx}',
  ],
}

Performance Issues

Problem: Slow build times even with v4.

Solution: Optimize content configuration:

export default {
  content: [
    // Be specific
    './app/**/*.{js,ts,jsx,tsx}',
    // Avoid
    // './**/*' - too broad
    // './src' - missing file extensions
  ],
}

Comparison: v3 vs v4

Build Performance

Metric	v3	v4	Improvement
Dev build	3.2s	0.3s	10.6x faster
Prod build	8.5s	0.9s	9.4x faster
Rebuild	1.2s	0.1s	12x faster

Bundle Size

Project Size	v3	v4	Reduction
Small	12KB	8KB	33%
Medium	45KB	28KB	38%
Large	120KB	75KB	38%

Features

Feature	v3	v4
JIT Mode	✅	✅ (Only mode)
CSS Variables	Limited	✅ Native
Container Queries	Plugin	✅ Built-in
CSS Nesting	Plugin	✅ Native
TypeScript	✅	✅ Enhanced