1. Home
2. web
3. Tailwind CSS v4.0 Release and Pure CSS Configuration

Introduction

Tailwind CSS v4.0 marks a paradigm shift from JavaScript-based configuration to a CSS-first architecture. The tailwind.config.js file is gone; design tokens are now defined directly in CSS using @theme. This release also integrates Lightning CSS for blazing-fast builds, adopts modern CSS features like CSS nesting and @layer, and ships a completely rewritten engine. This article breaks down the key changes and provides a practical migration guide from v3.

CSS-First Configuration with @theme

In v3, customizing design tokens required JavaScript:

// tailwind.config.js (v3)
module.exports = {
  theme: {
    extend: {
      colors: { brand: '#0f172a' },
      fontFamily: { display: ['Inter', 'sans-serif'] },
    },
  },
};

In v4, the same configuration lives entirely in your main CSS file:

@import "tailwindcss";

@theme {
  --color-brand: #0f172a;
  --font-family-display: 'Inter', sans-serif;
}

The @theme directive generates the corresponding utility classes (bg-brand, font-display) automatically. No JavaScript build step needed for tokens.

@import-Based Setup and Lightning CSS

Tailwind v4 is imported as a single CSS layer:

@import "tailwindcss";
@import "./custom-components.css" layer(components);

The framework uses Lightning CSS as its underlying CSS parser and minifier, replacing the PostCSS + Autoprefixer chain. This yields 3–10× faster build times compared to v3 on large projects.

To enable Lightning CSS features like native nesting and vendor prefixing:

@import "tailwindcss" source(none);
@import "./src/input.css" source("src");

Modern Reset and @layer Support

Tailwind v4 uses a modern CSS reset based on box-sizing: border-box globally, margin: 0 on all elements, and improved form element defaults. It also respects @layer cascade layers, allowing you to interleave Tailwind utilities with your own layered styles:

@layer base, components, utilities;
@import "tailwindcss" layer(base);
@import "./my-components.css" layer(components);

Key Utility Changes

Several utility classes saw breaking improvements:

The @variant directive allows custom state variants:

@variant supports-hover {
  @media (hover: hover) { @content; }
}

Migration Guide from v3

1. Remove tailwind.config.js and postcss.config.js.
2. Install the v4 package: npm install tailwindcss@next.
3. Replace your main CSS entry point to use @import "tailwindcss".
4. Move theme values into @theme blocks.
5. Replace @apply with regular CSS or @layer where possible (v4 still supports @apply but recommends plain CSS for complex cases).
6. Update changed utility names (shadow-sm → shadow-xs).
7. Test with npx tailwindcss --input src/input.css --output dist/output.css.

Conclusion

Tailwind CSS v4.0 eliminates the JavaScript build dependency for configuration, embraces native CSS features, and delivers a dramatically faster developer experience via Lightning CSS. The CSS-first @theme system makes design tokens more transparent and portable. Teams migrating from v3 should plan for the configuration overhaul but will benefit from reduced build complexity and improved runtime performance.