[v4] - Inquiry About Behavior Change in Tailwind CSS v4 Regarding Unused Custom Classes

[c0nstanc]

Hello Tailwind Team and community,

I’ve recently upgraded from Tailwind CSS v3 to v4 and observed a notable change in how unused custom classes within @layer utilities or @layer components are handled.

In Tailwind v3, any custom classes defined within @layer utilities or @layer components that were not used in the project were automatically purged and excluded from the final CSS bundle. For example:

@layer utilities {
  .my-custom-class {
    background-color: red;
  }
}

In this case, if .my-custom-class was not used anywhere in the project, it would not appear in the final output.

However, in Tailwind v4, it appears that unused custom classes defined within @layer utilities or @layer components are no longer purged and are included in the final bundle. For instance:

@layer utilities {
  .my-custom-class {
    background-color: red;
  }
}

Even if .my-custom-class is not used anywhere in the project, it is still included in the final CSS bundle. This behavior is also consistent when using the @utility at-rule to create custom utilities (they are also included in the final CSS bundle even when not used anywhere in the project).

Details to reproduce the issue:
The playground project was in angular v19 having tailwind v3(3.4.17) and migrated/upgraded using the instructions:
Below the project dependencies:

"dependencies": {
    "@angular/animations": "^19.1.6",
    "@angular/common": "^19.1.6",
    "@angular/compiler": "^19.1.6",
    "@angular/core": "^19.1.6",
    "@angular/forms": "^19.1.6",
    "@angular/platform-browser": "^19.1.6",
    "@angular/platform-browser-dynamic": "^19.1.6",
    "@angular/router": "^19.1.6",
    "@tailwindcss/postcss": "^4.0.6",
    "rxjs": "~7.8.1",
    "tslib": "^2.8.1",
    "uuid": "^11.0.5",
    "zone.js": "~0.15.0"
  },
  "devDependencies": {
    "@angular-devkit/build-angular": "^19.1.7",
    "@angular/cli": "^19.1.7",
    "@angular/compiler-cli": "^19.1.6",
    "@types/jasmine": "~5.1.6",
    "autoprefixer": "^10.4.20",
    "jasmine-core": "~5.6.0",
    "karma": "~6.4.4",
    "karma-chrome-launcher": "~3.2.0",
    "karma-coverage": "~2.2.1",
    "karma-jasmine": "~5.1.0",
    "karma-jasmine-html-reporter": "~2.1.0",
    "ng-packagr": "^19.1.2",
    "postcss": "^8.5.2",
    "tailwindcss": "^4.0.6",
    "typescript": "~5.7.3"
  }

Questions:

1. Is this change in behavior intentional (i.e., a breaking change) in Tailwind v4?
2. If this is by design, could you provide insight into the rationale behind this decision?
3. If this is unintended, is there a plan to address it in a future update?

Any clarification on this matter would be greatly appreciated. Thank you for your time and continued work on Tailwind CSS!

[wongjn]

1. Is this change in behavior intentional (i.e., a breaking change) in Tailwind v4?
2. If this is by design, could you provide insight into the rationale behind this decision?

It is intentional. The rationale is:

In v4 we are using native cascade layers and no longer hijacking the @layer at-rule, so we've introduced the @utility API as a replacement:

[c0nstanc]

Thank you for your quick response @wongjn.
I am supporting the decision to use the native cascade layers as intended.

In this case, I would expect that the declared classes using @utility at-rule to be purged and be removed from the bundle if they are not used anywhere in the code. Right? However, currently it is not the case.

For example:

@utility my-custom-class {
  background-color: red;
}

Even if .my-custom-class is not used anywhere in the project, it is still included in the final CSS bundle.

Is the above a bug or could It be that I am missing something?

---

Background - Why I am asking the above

I found out about the @layer not deleting/purging the unused classes in V4 due to my setup in v3.

In tailwind v3 which was supporting scss we could use mixins to generate automatically multiple style-guide classes which we could include/generate under the @layer utilities.

This setup in tailwind v3 had 2 advantages:

1. Each generated utility class was working out of the box with tailwind variants.
2. All not used utility classes were purged.

Using Tailwind V4:
In V4 per my understanding, in order to achieve batch generation of custom style-guide classes, I can do it based on the instructions here. The generation of the custom classes is not as powerful as using scss mixins - but maybe this is intentional, or it can be something that will be evolved in the future. Not a real issue at the time.

In regards of purging the unused custom utility classes, I did not find any way to achieve that. This is either a bug of the @utility at-rule or maybe I am missing something.

---

[wongjn]

Is the above a bug or could It be that I am missing something?

It could be a bug - could you provide a reproduction to confirm please?

[c0nstanc]

After further investigation, I can confirm that there is no bug in the current behavior. Specifically, the custom class .my-custom-class, when created using @utility, is not included in the final build if it remains unused.

To ensure clarity and reproducibility, I created a playground project in Angular to test this scenario.

Initially, my method of verifying whether the class was purged was flawed. I relied on browser developer tools and attempted to apply the utility class dynamically at runtime. What I discovered is that when using a live server in development mode, if a custom class is added to the code and later removed, it may still persist in the server context even if it is no longer used in the codebase. This behavior led me to mistakenly believe that unused classes were not being purged from the final bundle. However, after restarting the development server, the utility class was correctly excluded, confirming that the purging mechanism works as expected.

By directly inspecting the resulting CSS output, I could have been able to avoid drawing incorrect conclusions.

Thank you @wongjn for your prompt responses and support—it’s greatly appreciated!