CSS Styles from unrelated pages and components are merged if they're using the same shared component

[Obvio]

Link to the code that reproduces this issue

https://github.com/Obvio/next-css-modules

To Reproduce

This issue is similar to #64773.

To Reproduce

1. build the app and start it (not reproducible in dev mode)
2. go to http://localhost:3000/
3. you should see the both .h1 from separate pages bundled into one css file.

Visit the site in https://next-css-modules.vercel.app/ looking at the console we see one that one of the css files includes all the "shapes" of .h1 even-though only one of them is called/used on the page.

I have 2 pages that share the same component, each hast its own css module and the shared component also has its own css module.

When the app is built and deployed in vercel (doesn't happen in localhost) the bundle generates a css file which includes all the places said shared component is called from with their page css.

This seem to go against the site's performance and in bigger scale causes pagespeed and lighthouse to not like (and punish) for the increased bundle size.

Current vs. Expected behavior

Currently the generated css files in the bundle "merge" all into one file.
I would expect the generated css pages in the bundle to only include the css relevant to the current page.

Provide environment information

Operating System:
  Platform: darwin
  Arch: x64
  Version: Darwin Kernel Version 23.6.0: Mon Jul 29 21:13:00 PDT 2024; root:xnu-10063.141.2~1/RELEASE_X86_64
  Available memory (MB): 32768
  Available CPU cores: 12
Binaries:
  Node: 21.1.0
  npm: 10.2.0
  Yarn: 1.22.19
  pnpm: 7.26.2
Relevant Packages:
  next: 15.0.0-canary.156 // Latest available version is detected (15.0.0-canary.156).
  eslint-config-next: 15.0.0-canary.156
  react: 19.0.0-rc-206df66e-20240912
  react-dom: 19.0.0-rc-206df66e-20240912
  typescript: 5.6.2
Next.js Config:
  output: N/A

Which area(s) are affected? (Select all that apply)

Not sure

Which stage(s) are affected? (Select all that apply)

next build (local)

Additional context

14.1.4 : OK
14.2.5 : BROKEN
15-canary: BROKEN

[samcx]

@Obvio The behavior was changed here → #63157. This is the expected behavior.

This seem to go against the site's performance and in bigger scale causes pagespeed and lighthouse to not like (and punish) for the increased bundle size.

The other side of this to consider is that more requests will also punish site performance.

https://github.com/vercel/next.js/blob/canary/packages/next/src/build/webpack/plugins/css-chunking-plugin.ts → I believe essentially what we do is we merge until a chunk is too large, then we split it is as needed.

[Obvio]

@samcx I appreciate the time you took to review this issue, this is not taken for granted, thank you!

I also understand what is the point that you're making, however i'd like to offer a third approach - which is in between the original behaviour and the changed behaviour - I don't want to have more requests per page, what I want is to have exactly 2 requests which only contain the CSS which is relevant to the current page: a layout.css and page.css (or an additional call in case something is laze loaded dynamically).

My suggestion is based on what actually happens when you run npm run dev- the generated files from css modules only have the required page styles (you can run it yourself from my repo) but here are screenshots of the generated css files:

I think this has many benefits over the current approach:

1. Builds are predictable and deterministic (at least on the css level) - people can easily optimize important and specific routes.
2. The traffic (bandwidth) is smaller (also a Vercel benefit!) - each page receives only what they need.
3. Sites load faster, underpowered devices get better User experience.
4. SEO/pagespeed is improved.

Finally, I know we're talking about relatively small sizes (my site is super optimized) however they're still flagged by Pagespeed/Lighthouse report and I'm trying to save as much as I can on all fronts as there are features i can not remove (like monitoring etc.). Here's an example from a site I work on which led me to dig into this in the first place:

As a feature suggestion may allow for optin/optout of the current behaviour and also allow optin for preloading certain routes' css using some pragma a la "user client" like "use preload"..
Thank you!

[sokra]

While your approach would work great for the initial visit, it does have problems with client side navigation between pages.

In your repo this would require the inner wrapper CSS to be duplicated into page.css and other/page.css. Duplicating CSS is a red flag, because it breaks CSS order.

In your repro page would require the page styles before the inner wrapper styles and other/page require inner wrapper styles before page styles. We must ensure that this order is correct in all scenarios.

Assume we visit other/page first, which loads other/page.css and navigate to page via client side navigation, which loads page.css. Now other/page.css and page.css are loaded on the page. This means inner wrapper styles, other page styles, page styles and inner wrapper styles are active in that order. The second inner wrapper styles effectively override the first one so the styles are actually: other page styles, page styles, inner wrapper styles. This means the CSS order is violated for other page and navigating back to that page might show incorrect styling.

In your repo it doesn't matter, as inner wrapper doesn't interact with the page styles but we can't assume that in general.

[Obvio]

@sokra Thank you for taking the time to answer. What I maybe I don't understand is how this scenario possible when css modules are used? I'm under the impression the generated class names are unique to the page they're called from, exactly as it is reproduced in my repo, so it's not really possible for styles/classnames to be overwritten (unless modules aren't used).

On a personal opinion - I feel site visitors are more inclined to stay on the site (not bounce) if the first experience is super fast (the rest of the site's css can be lazyloaded).

So, maybe as a feature suggestion if we can't bail out of this behaviour, it'd be nice to be bale to define the ax chunk size (the links above from @samcx point to the change which suggest css chunks are at most 100kb)..

Thanks again for looking into this. :)

[sokra]

Even with CSS Modules order matters in same cases. E. g. when applying styles from two different CSS modules to the same element:

import stylesA from "./a.module.css";
import stylesB from "./b.module.css";

<div className={stylesA + " " + stylesB}>

This often happens with components that allow to pass a className prop.

On a personal opinion - I feel site visitors are more inclined to stay on the site (not bounce) if the first experience is super fast (the rest of the site's css can be lazyloaded).

Agree. We usually optimize with the focus on initial page load, but here we have to make trade-offs for correctness.

There is an alternative approach for CSS we experimented with for Turbopack dev, which would keep the loaded modules in a runtime state and request different CSS bundles depending on what is already loaded, but it turned out that is a little bit harder due to the many ways of CSS being loaded (RSC, SSR, dynamic import) and state need to be maintained between them. Maybe that's an option for prod too, but not sure yet.

So, maybe as a feature suggestion if we can't bail out of this behaviour, it'd be nice to be bale to define the ax chunk size (the links above from @samcx point to the change which suggest css chunks are at most 100kb)..

There two values here: 30kb and 100kb. Both applied on the unminimised css size.

If a chunk would be smaller than 30kb, we merge it with another small chunk (usually from a different page) that has some overlap. The difference in size is usually not relevant for the initial page load performance (the request overhead is much bigger than the few extra bytes downloaded, compression is also more efficient on larger files), but it has a benefit if a user visits both pages (1 less request as that css is already loaded/cached). Often it even merges many small css files from a bunch of pages.

If a chunk would be bigger than 100kb we split it into chunks that are smaller than 100kb. This allows both chunks to be cached independently, so a small change of the application won't invalidate a big 1MB chunk, but a smaller <100kb chunk and the other chunks can stay cached.

We apply similar numbers on JS chunking.

Sounds fine to be to offer an option to change these numbers, but it's hard to measure the long term caching impact and compare that with the initial page load performance. So it's more number guessing. If you want to optimize for best initial page load you probably want to go with 0kb and ∞kb.

[Obvio]

Thank you!

[joshwcomeau]

Hey y'all!

I recently migrated my blog to Next 15, and I believe this behaviour is causing a significant performance issue. Most pages have 20-40kb of unused CSS being loaded. My homepage, for example, loads 38kb of CSS but only uses 4kb:

This is a problem since the CSS blocks rendering. It means the user spends longer staring at a blank white screen:

According to Lighthouse, the FCP has been pushed back by ~500ms on mobile, and I believe this change is responsible for the majority of that time (though I could be wrong). So it seems to me like a pretty significant regression.

I understand @sokra’s point, that out-of-order CSS is problematic and a significant challenge given the new architecture, but if I had to choose between the occasional selector issue and significantly worse initial load experience for all users, I would absolutely pick the former. I believe I have seen the out-of-order CSS issue in development, but it's rare, and easy enough to fix (I solve it by doubling up the selector when I see it happening and know one style should always be prioritized over the other).

Hopefully this can be made into an config option. Otherwise, I think this fact needs to be published much more prominently, as it's important information for anyone trying to decide whether to migrate to App Router or not.

[joshwcomeau]

@samcx Ahh, I totally missed the "usually from a different page" line! That makes sense. Excited to give it a test!

Thanks for the clarification 😄

[marko-hologram]

I believe I have seen the out-of-order CSS issue in development, but it's rare, and easy enough to fix (I solve it by doubling up the selector when I see it happening and know one style should always be prioritized over the other).

I rarely noticed this issue in development, but it would actually appear in production (although rarely as well). So development output wasn't equal to production output. This is what tripped me up few times because in development my styling would be applied a certain way and in production it would apply a different way. It doesn't happen because of CSS changes (as far as I know), it happens because of import order of components that I've used and those components imported CSS module files. So a seemingly unrelated change of importing a component somewhere or removing its import from somewhere would mess up CSS ordering and break things.

Of course, if I perfectly encapsulated styling for a component it wouldn't happen. It would usually happen if I allowed passing className to a component and using it with existing CSS module styles the component has. Yes, doubling up the passed selector works, but it's a weird issue to debug when it happens because it's not obvious what happens, but passing className into a component is just sometimes so super convenient 😅

I don't really have anything smart to say, but just wanted to say that this issue isn't an easy thing to debug and fix when it happens. Yeah when you know what's the issue it's super easy to address, but debugging it first time and finding a fix/workaround is a pain 😄

[joshwcomeau]

Yeah — I actually had my first instance yesterday of the right issues being applied in development, and the wrong ones in production. It feels like kind of a big problem to me that styles are applied in a different order between dev and prod.

[samcx]

It doesn't happen because of CSS changes (as far as I know), it happens because of import order of components that I've used and those components imported CSS module files. So a seemingly unrelated change of importing a component somewhere or removing its import from somewhere would mess up CSS ordering and break things.

The ordering of imports from components and stylesheets actually does matter—something I don't think is always completely clear → https://nextjs.org/docs/app/building-your-application/styling/css#ordering-and-merging.

Yeah — I actually had my first instance yesterday of the right issues being applied in development, and the wrong ones in production.

The merging of CSS should be consistently different from development and production, but there should not be an issue with ordering, unless you are coming across this scenario (definitely looking to fix this!) → #65480.

[marko-hologram]

The ordering of imports from components and stylesheets actually does matter

Yeah sorry I worded it a bit weirdly. I wanted to say, as a developer working on a project, you can change some component imports and your CSS would suddenly behave differently just because CSS was loaded in different order because of different order of imports now. So a seemingly unrelated change (you didn't touch any CSS code) impacts CSS. At least that's how it looked few times I've seen it happen.

I understand this isn't an easy thing to solve (with everything mentioned above) and if I didn't pass in className from parent to child component (with same selector specificity level), I wouldn't have these issues. Only issue I have with this really is the different behavior between local development and production. My styles can work well in local development and things apply the way I want them to and then in production they behave differently.

I was suspecting that locally the styles would work because fast refresh might inject them as latest styles into the DOM? So current CSS I'm working on actually gets injected last into the DOM so it applies the way I expect it to because of cascade it overrides previous CSS of same specificity, but then when built for production, it gets different ordering because it gets bundled somehow differently.

So let's say I have this code:

Parent.module.css

.componentParent {
  margin-bottom: 10px;
}

Child.module.css

.componentChild {
  margin-bottom: 50px;
}

Parent.tsx

import Child from "./Child";
import styles from "./Parent.module.css";

const Parent = () => {
  return <Child className={styles.componentParent} />
}

Child.tsx

import styles from "./Child.module.css";

const Child = ({ className }) => {
  return <div className={cx(styles.componentChild, className)}>Child component</div>
}

And now I edit Parent.module.css locally and everything works. During fast refresh all my changes get applied, but during production it might happen that .componentParent class gets overridden by .componentChild class, even though in local development it was the opposite.

This is what tripped me up a few times. As I've said, I suspected that during local development last styles being saved get injected last (maybe?) and it all works, but for production it's a different thing. Of course it can be solved by using .componentParent.componentParent {} selector to make it more specific (or not pass className at all), but it's hard to know if you'll need it in advance when during development it all looks as you expect it to.

Also, when I first ran into this issue these docs (https://nextjs.org/docs/app/building-your-application/styling/css#ordering-and-merging) didn't exist as far as I know, so I had no documentation to reference and get an idea what's happening.

---

I don't really run into this issue anymore because I use Tailwind and tailwind-merge these days, but for projects that I still maintain that are using CSS Modules, this happens sometimes, but I try to avoid passing style overrides from parent in CSS Modules scenarios. Although it happens rarely, so I don't consider it that critical, it's just that it's unpredictable and hard to debug when you encounter it the for first time.

[samcx]

Related: #71474

[joostmeijles]

@samcx thanks for your prompt reply!

Is it expected behaviour (on v14) that CSS from other pages may be added in the generated & loaded CSS file?

[samcx]

@joostmeijles Yes, this is expected in v14 (this PR). The reasons why are mentioned in this discussion. We're still looking at this (been somewhat busy with v15).

Will circle back on this when we have an update!

[joostmeijles]

Alright thanks!

Please note that for our application, a large e-commerce website, many (and large) CSS files are being generated.
This breaks our Lighthouse performance scores, as it e.g. doubles LCP time from ~2 seconds to >4 seconds on mobile.

[samcx]

@joostmeijles Are you also sharing a component(s) between the pages where the styles are being merged (the current visible page + unrelated page(s))?

[joostmeijles]

Yes, that's correct. We have quite some components that are shared, directly or indirectly, on various pages and layouts.

[samcx]

Hey everyone!

We recently shipped an experimental flag to disable the CSS Chunking Algorithm altogether → #73286, which may help with this issue (does have tradeoffs to doing this).

We also recently shipped an experimental flag to inline CSS → https://nextjs.org/docs/canary/app/api-reference/config/next-config-js/inlineCss. More improvements to come with this flag, but this can definitely improve Lighthouse scores!

[joshwcomeau]

Inlining the CSS is a great idea! It was one of my favourite things about styled-components; no secondary round-trip to fetch a stylesheet, it all comes in the HTML.

Thanks for keeping this issue in mind, and for working on solutions ❤️. Gonna test both of these options

[joshwcomeau]

Just a quick note for anyone else seeing this: the linked PR adds a "disabled" option for cssChunking, but I think since then this was changed to a boolean value. Here’s the config that worked for me:

const config = {
  experimental: {
    cssChunking: false,
  },
};

[samcx]

@joshwcomeau Agreed! There are still improvements/fixes to be made with CSS in App Router. Will keep ya'll updated!