Migrating an Angular project (with Sass) to Tailwind CSS v4

Feb 3, 2025

Jits

Tip

Update — Wed 26 Feb, 2025: since writing this, I’ve published another post on how to make Tailwind CSS v4 play nice with Angular Material, by separating the Tailwind CSS and SCSS processing out in to separate files. I highly recommend taking this approach after the manual migration steps in this post (and for any new projects, especially).

The Tailwind CSS v4 release is a big one, with a lot of changes. Unfortunately, the automated upgrade tool doesn’t work with Sass (i.e. .scss files). If you have an Angular project with Sass (e.g. one that uses Angular Material) you can’t directly use the upgrade tool.

In this post, I show you how to manually migrate an Angular project with Sass to Tailwind v4, whilst still using the automated upgrade tool to do most of the work.

Assumptions

• You’ve already upgraded to at least @angular/cli v19.1.5 (as that allows tailwindcss v4.x as a peer dependency)
• You’re using Sass with the SCSS syntax (e.g. if you’re using Angular Material with a custom theme)
• You’re using Tailwind v3

When you run npx @tailwindcss/upgrade@next — the upgrade tool — in your Angular (with Sass) project you’ll see output like the following:

≈ tailwindcss v4.0.2

│ Searching for CSS files in the current directory and its subdirectories…

│ ↳ Cannot find any CSS files that reference Tailwind CSS.
│   Before your project can be upgraded you need to create a CSS file that imports Tailwind
│   CSS or uses `@tailwind`.

│ ↳ No PostCSS config found, skipping migration.

│ Updating dependencies…

│ ↳ Updated package: `tailwindcss`

│ Verify the changes and commit them to your repository.

You can see here that the upgrade tool can’t find any CSS files that reference Tailwind CSS, as we’re using Sass (.scss). It also doesn’t detect a PostCSS config, as the Angular CLI took care of this for you for Tailwind v3.

To “force” the upgrade tool to work we’ll:

1. Create a PostCSS config file in the root — we’ll need this anyway for Tailwind v4 so it’ll stay.
2. We’ll create a temporary CSS file in the root that contains only the Tailwind specific bits from our src/styles.scss file. This is only temporary and for the upgrade tool to do its magic. We’ll inspect the changes made and apply them to our main styles file and delete this temporary one.

The manual migration process

1. Make sure you start with a clean working directory and commit any changes you have, as we’ll be using git diff to see what changes the upgrade tool makes — so we know what changes to apply manually to our src/styles.scss file, and how templates etc. have been updated.

2. Create a .postcssrc.json file in the root of your project with the following:

   {
     "plugins": {
       "tailwindcss": {},
       "autoprefixer": {}
     }
   }

3. Create a tailwind.tmp.css file in the root of your project and copy over only the Tailwind specific bits from your main src/styles.scss file. For example:

   @import 'tailwindcss/base';
   @import 'tailwindcss/components';
   @import 'tailwindcss/utilities';

   Caution

   Make sure you copy all Tailwind bits, and no Sass specific bits, and that you maintain the same structure and ordering.

4. Run the upgrade tool:

   npx @tailwindcss/upgrade@next --force

   Note

   We need --force as otherwise the tool will complain about the Git directory not being clean.

   You should see output like:

   ≈ tailwindcss v4.0.2
   
   │ Searching for CSS files in the current directory and its subdirectories…
   
   │ ↳ Linked `./tailwind.config.js` to `./tailwind.tmp.css`
   
   │ Migrating JavaScript configuration files…
   
   │ ↳ Migrated configuration file: `./tailwind.config.js`
   
   │ Migrating templates…
   
   │ ↳ Migrated templates for configuration file: `./tailwind.config.js`
   
   │ Migrating stylesheets…
   
   │ ↳ Migrated stylesheet: `./tailwind.tmp.css`
   
   │ ↳ Installed package: `@tailwindcss/postcss`
   
   │ ↳ Removed package: `autoprefixer`
   
   │ Updating dependencies…
   
   │ ↳ Updated package: `tailwindcss`
   
   │ Verify the changes and commit them to your repository.

   Caution

   There are cases where the upgrade tool will fail to do a full migration away from the tailwind.config.js file, e.g. if you’re using the important: "#foo" option. In this case, Tailwind will keep the config file and use a new (but legacy) capability of importing your config file in your CSS file. If you want to do a proper migration away from this approach at this point you’ll need to first migrate away from the now unsupported option(s) and then try again.

5. Inspect your tailwind.tmp.css file and compare it to your src/styles.scss file.

   You can use git diff to see the changes made by the upgrade tool:

   git diff tailwind.tmp.css

   You’ll need to apply these changes to your main src/styles.scss file manually to complete this migration.

   Caution

   It’s important you go through the changes properly, understand them, and apply them accurately — I’ve noticed the upgrade tools does weird things like (just as an example):

   @layer utilities {
     html,
     body {
       height: 100%;
     }
     body {
       margin: 0;
       font-family: Roboto, 'Helvetica Neue', sans-serif;
     }
   }

   … which I believe is not the right approach! These rules should be at the top level, not within a utilities layer.

6. Inspect any changes the upgrade tool may have made to template files, and run ng serve to test that your app is working as expected.

7. Once you’re happy with the changes, you can delete the tailwind.tmp.css file and commit your changes 🚀

Tags:

• Angular
• Tailwind

Make Tailwind CSS v4 play nice with Angular Material

How to keep up to date with releases - why I built Releases.news