[v4] CSS bundle bloated when using @tailwindcss/vite and tailwind-merge

[maxsalven]

What version of Tailwind CSS are you using?

v4

What build tool (or framework if it abstracts the build tool) are you using?

vite 6

What version of Node.js are you using?

v20.11.1

What browser are you using?

N/A

What operating system are you using?

macOS

Reproduction URL

https://github.com/maxsalven/tw-vite-bug

Describe your issue

In the attached repro is a very basic vite app which uses tailwind-merge:

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { twMerge } from "tailwind-merge";
import "./index.css";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <div className={twMerge("text-2xl")}></div>
  </StrictMode>
);

It uses the vite plugin:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";

// https://vite.dev/config/
export default defineConfig({
  plugins: [tailwindcss(), react()],
});

The built CSS file is 32.8KB
dist/assets/index-BAs4IohO.css 32.81 kB │ gzip: 7.35 kB

and includes unused classes:

  .stacked-fractions {
    --tw-numeric-fraction: stacked-fractions;
    font-variant-numeric: var(--tw-ordinal) var(--tw-slashed-zero)
      var(--tw-numeric-figure) var(--tw-numeric-spacing)
      var(--tw-numeric-fraction);
  }

If we now remove the tailwindcss plugin:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

// https://vite.dev/config/
export default defineConfig({
  plugins: [react()],
});

and run npm run build again:
dist/assets/index-B89DnZA7.css 17.80 kB │ gzip: 5.19 kB

The CSS file is half the size and the unused classes are gone. The used classes are still in there:

@layer utilities {
  .text-2xl {
    font-size: var(--text-2xl);
    line-height: var(--tw-leading, var(--text-2xl--line-height));
  }
}

[vladkrutenyuk]

the same. everything was good when i used v3 version in vite.

[philipp-spiess]

Hey! The issue is that tailwind-merge is a npm package that contains every Tailwind utility name in its source code. Because of this, automatic source detection will create much more utilities than you'd actually need.

Note that in your example you pull this in inside a React client component so even in v3, this would create a huge JavaScript bundle for your browser.

If you can not get rid of that dependency, one idea is to disable automatic source detection and configure your input sources manually. You can find info about this here: https://tailwindcss.com/docs/detecting-classes-in-source-files

[maxsalven]

Hi Philipp,

In my mind the issue here is that you get a very different css bundle depending purely on whether tailwind is installed via the Vite plugin or not. That is surprising to me, I’d expect identical bundles regardless of how tailwind is installed, given both are the exact same version of tailwind (v4.0). Is that not to be expected? Thanks!

[skratchdot]

Sorry for the potentially off-topic post, but I figured it makes sense to post here (instead of a new issue).

I spent some time upgrading my app from v3 to v4 and everything looks good to me (from a quick visual inspection), but I did notice my build sizes increased. I spent some time evaluating v3 vs v4 (postcss) vs v4 (vite-plugin) while enabling and disabling my various plugins.

I wrote up some info and was coming to post an issue, but when I searched for is:issue state:open v4 size I found this ticket. It made me realize that maybe tailwind-merge is the issue (I am using that- but it wasn't a "plugin" in my postcss/tailwind/vite files (so I didn't try removing all the usages of it).

Anyways, in my v3 project, here are the relevant packages I'm using. My v3->v4 size analysis is below. Perhaps it will help someone else.

Relevant packages in my v3 project:

"@tailwindcss/forms": "^0.5.10",
"@tailwindcss/typography": "^0.5.16",
"autoprefixer": "^10.4.20",
"cssnano": "^7.0.6",
"postcss": "^8.5.1",
"tailwind-merge": "^2.6.0",
"tailwindcss-animate": "^1.0.7",
"tailwindcss": "^3.4.17",

tailwind v3 to v4 build stats

Overview

setup	size
tailwindcss@3.4.17 and postcss	68.77 kB
tailwindcss@4.0.0 and postcss	89.46 kB
tailwindcss@4.0.0 and vite plugin	100.15 kB

tailwindcss@3.4.17 and postcss (using postcss@8.5.1, autoprefixer@10.4.20, cssnano@7.0.6, tailwindcss@3.4.17)

postcss.config.mjs:

import autoprefixer from 'autoprefixer';
import cssnano from 'cssnano';
import tailwindcss from 'tailwindcss';

export default {
  plugins: [
    tailwindcss,
    autoprefixer,
    ...(process.env.NODE_ENV === 'production' ? [cssnano] : []),
  ],
};

tailwindcss-animate	@tailwindcss/forms	@tailwindcss/typography	size	gzip size
✗	✗	✗	40.12 kB (+ 00.00 kB)	7.93 kB
✓	✗	✗	42.85 kB (+ 02.73 kB)	8.32 kB
✓	✓	✗	48.31 kB (+ 05.46 kB)	9.35 kB
✓	✓	✓	68.77 kB (+ 20.45 kB)	11.91 kB

tailwindcss@4.0.0 and postcss (using postcss@8.5.1, @tailwindcss/postcss@4.0.0, cssnano@7.0.6)

postcss.config.mjs:

import tailwindcss from '@tailwindcss/postcss';

export default {
  plugins: [tailwindcss],
};

tailwindcss-animate	@tailwindcss/forms	@tailwindcss/typography	size	gzip size
✗	✗	✗	60.29 kB (+ 00.00 kB)	12.19 kB
✓	✗	✗	63.10 kB (+ 02.81 kB)	12.60 kB
✓	✓	✗	68.52 kB (+ 05.42 kB)	13.63 kB
✓	✓	✓	89.46 kB (+ 20.94 kB)	16.20 kB

tailwindcss@4.0.0 and vite plugin (using @tailwindcss/vite)

deleted my postcss.config.mjs and added @tailwindcss/vite to my vite.config.mts file in the plugins section.

tailwindcss-animate	@tailwindcss/forms	@tailwindcss/typography	size	gzip size
✗	✗	✗	70.91 kB (+ 00.00 kB)	13.55 kB
✓	✗	✗	73.79 kB (+ 02.88 kB)	14.00 kB
✓	✓	✗	79.21 kB (+ 05.42 kB)	15.05 kB
✓	✓	✓	100.15 kB (+ 20.94 kB)	17.79 kB

Questions / Thoughts

I'm curious if the increase from v3 (postcss) 40.12 kB to v4 (postcss) 60.29 kB (or v4 (vite-plugin) 70.91 kB) is due to tailwind-merge or if this is an expected increase for a v3 -> v4 migration?

EDIT (01/26/2025):

I did some more testing today. Even if I rip out my tailwind-merge usage in v4, I still see a much larger build:

• v3 (with tailwind-merge): 68.77 kB
• v3 (without tailwind-merge): 68.77 kB
• v4 vite-plugin (with tailwind-merge): 100.15 kB
• v4 vite-plugin (without tailwind-merge): 91.46 kB

It is interesting that v3 with and without tailwind-merge doesn't change my overall bundle size. So there does appear to be some issues. Hopefully they will be fixed when tailwind-merge gets v4 support: dcastil/tailwind-merge#513

[dcastil]

@philipp-spiess Does this mean that the Tailwind Vite plugin tries to read Tailwind classes out from all code that gets bundled into the app, even when it's coming from node_modules?

Getting rid of tailwind-merge as a dependency won't be feasible since it's used by over a third of all Tailwind CSS users.

Would it make sense to change the automatic source detection to omit any files from node_modules?

[skratchdot]

Based on the detecting-classes-in-source-files link from @philipp-spiess I was able to get my build a little smaller than actually removing tailwind-merge.

So this worked for me (in my ./src/index.css file):

@import 'tailwindcss' source('../src');

[philipp-spiess]

Hey all! Quick update after some investigation but it seems that the Vite dev mode (which uses the Vite module graph to scan for class candidates) currently does not follow the same heuristics that the CLI does and as such it follows .gitignoreed folders. This is not expected and we're looking into fixing it.

[philipp-spiess]

Okay another update: I was wrong. We have a different heuristics for what to exclude when using Vite's module graph on purpose because we want to make it very easy to import third-party modules without any additional setup.

This means that we'll likely not make Vite follow .gitignore like the CLI does because all modules in the module graph are already a much higher quality signal for potential classes that you want in your CSS than the file system scanning that we do in the CLI/postcss.

However, we still want to fix this problem so we're currently thinking about how to best approach this. I think conceptually it would be great if the dependency, in this case tailwind-merge, has a way to say that it doesn't contain any potential class names or so. 🤔

[dcastil]

@philipp-spiess I also thought a comment similar to /* eslint-disable */ would be interesting. E.g. /* tailwindcss-disable-source-detection */?

Would also be much easier for users to put at the top of a file they want to exclude rather than maintaining paths in a config file, especially when those files get moved around.

[maxsalven]

Thanks for the investigation and update @philipp-spiess. Just chiming back in with some unsolicited feedback; I think it’s an unusual decision to have two different css outputs based on how tailwind is installed. I think calculating the module graph should be controlled by a declaration (@source ?) in your css file(/config). Anything else is surprising to me as a Tailwind consumer. I appreciate I don’t have the full behind the scenes picture here however!

[skratchdot]

Sorry for adding more to this thread, but here's a project with some different example setups:

• https://github.com/skratchdot/tailwind-v4-example-sizes

CSS Output (tailwindcss@4.0.0)

css file	size	gzip size	build time
v3-postcss-merge	4.88 kB	1.44 kB	612ms
v3-postcss-no-merge	4.88 kB	1.44 kB	564ms
v4-postcss-merge	17.98 kB	5.26 kB	553ms
v4-postcss-no-merge	17.98 kB	5.26 kB	536ms
v4-vite-merge	32.96 kB	7.38 kB	428ms
v4-vite-no-merge	19.76 kB	5.62 kB	446ms

[maxsalven]

@skratchdot are you sure that’s correct? In my example repo in my initial comment I got 32KB v4-vite-merge and 18KB v4-postcss-merge.

[skratchdot]

@skratchdot are you sure that’s correct? In my example repo in my initial comment I got 32KB v4-vite-merge and 18KB v4-postcss-merge.

I think it's right. There might be a bug in:

• https://github.com/skratchdot/tailwind-v4-example-sizes/tree/main/packages/v4-postcss-merge

I did add a few extra classes to the "simple" html. So I'm using:

<h1 className={twMerge('text-3xl font-bold underline')}>Hello World!</h1>

vs

<h1 className={'text-3xl font-bold underline'}>Hello World!</h1>

in all my examples

EDIT: there might be an issue with how I set things up as a pnpm workspace. I also don't have the build folder in my gitignore like I usually would (b/c I wanted to check in the files). So I might clean that up and see if it changes anything

[skratchdot]

@maxsalven - thank you! you were right. i added rimraf packages/*/dist; before building all the files and that fixed the issue. i'm not sure what was up- but i guess it was picking up class names from my dist folder from when i initialized all the projects.