TailwindCSS v4 Upgrade in Angular Projects

Problem Statement

When upgrading TailwindCSS from v3 to v4 in an Angular project, developers frequently encounter the error:

Error: It looks like you're trying to use `tailwindcss` directly as a PostCSS plugin.
The PostCSS plugin has moved to a separate package,
so to continue using Tailwind CSS with PostCSS
you'll need to install `@tailwindcss/postcss` and update your PostCSS configuration.

This occurs because Tailwind v4 introduced significant architectural changes:

• Deprecated @tailwind directives in CSS
• Eliminated built-in Sass/Less support
• Requires explicit PostCSS configuration

Preprocessor Compatibility

Tailwind v4 no longer supports Sass, Less, or Stylus. The official documentation states:

"Tailwind CSS v4.0 is a full-featured CSS build tool designed for a specific workflow, and is not designed to be used with CSS preprocessors like Sass, Less, or Stylus."

You must convert existing .scss files to standard .css for full compatibility.

Recommended Upgrade Process

1. Convert SCSS to CSS

Since Tailwind v4 handles modern CSS features like nesting and variables, convert your Angular component styles:

- component-name.component.scss
+ component-name.component.css

2. Run Tailwind Upgrade Tool

npx @tailwindcss/upgrade@next

This automatically migrates your tailwind.config.js and flags necessary file changes.

3. Install Required Packages

npm install tailwindcss @tailwindcss/postcss postcss --force

4. Configure PostCSS

Create .postcssrc.json in your project root:

{
  "plugins": {
    "@tailwindcss/postcss": {}
  }
}

Critical Detail

The file must be named exactly .postcssrc.json including the leading dot. Angular requires this specific filename.

5. Update Tailwind Imports

In your primary styles file (typically styles.css):

- @tailwind base;
- @tailwind components;
- @tailwind utilities;
+ @import "tailwindcss";

6. Handle Component-level @apply Directives

For components using @apply, add a config reference at the top of their CSS files:

@config "../path/to/tailwind.config.js";

Angular-Specific Configuration

File Structure Example

src/
├── styles.css
├── themes/
│   └── _tailwind.css  # Optional for theme separation
└── tailwind.config.js

In styles.css:

@import "tailwindcss";
/* Optional theme imports */
@import "themes/tailwind";

In themes/_tailwind.css (if used):

@import "tailwindcss/theme";
@import "tailwindcss/utilities";

Verify Installation

1. Remove any tailwindcss: {} references from postcss.config.js
2. Ensure angular.json references your primary CSS file correctly
3. Start the development server:

npm start

Troubleshooting Common Issues

PostCSS Errors

Symptom: Build errors mentioning PostCSS
Solution: Verify .postcssrc.json exists in the project root with leading dot

@apply Not Working

Symptom: Custom utilities missing in components
Solution: Add config reference to component CSS:

@config "../../tailwind.config.js";

VS Code IntelliSense Failure

Solution: Ensure your tailwind.config.js is properly configured. Restart VS Code and TailwindCSS IntelliSense extension.

Key Architectural Changes in v4

• No preprocessor support: Built-in handling of modern CSS replaces Sass
• Direct import model: @import "tailwindcss" replaces @tailwind directives
• Config-driven theming: Advanced customization via tailwind.config.js
• Improved bundling: Native CSS bundling without additional tools

Migration Strategy

1. Convert all SCSS → CSS
2. Run official upgrade tool
3. Verify imports and PostCSS config
4. Incrementally address component-level issues

Additional Resources

• Official Angular + Tailwind Guide
• v3 → v4 Upgrade Documentation
• Core Compatibility Documentation