keep consistent css order by jantimon · Pull Request #19012 · webpack/webpack

jantimon · 2024-11-26T10:39:34Z

What kind of change does this PR introduce?

We were struggling with the problem that the CSS ordering becomes unpredictable when webpack's side effects optimization removes barrel files (for sideEffects: false in package.json)

Looking at webpack's buildChunkGraph.js, I traced this down to how module graph building and tree-shaking interact. When webpack finds a module marked as side effect free, it tries to optimize by skipping over barrel files (activeState: false`) and connecting directly to implementation files. While great for JS tree-shaking, this changes the dependency order which affects CSS since mini-css-extract-plugin relies on postOrderIndex for ordering

Here's a concrete example from the reproduction repo I set up:

// @libraries/teaser/src/teaser.ts
import { CarouselButton } from '@segments/carousel'; // via barrel file
import styles from './teaser.module.css';

When building with sideEffects: false, webpack removes the barrel file but loses the original ordering, resulting in incorrect CSS:

.teaser { ... }  /* Should be last */
.carousel { ... } /* Should be first */

I've found this is happening because dependency indices get rewritten during side effects optimization

My fix in SideEffectsFlagPlugin.js maintains the original ordering by sorting the direct imports after their barrel files position

BEFORE THE FIX:

Initial import order in parent module:
index: 0 -> @segments/carousel/index.ts (barrel file)
index: 1 -> ./teaser.module.css

After tree-shaking removes barrel file:
index: 0 -> @segments/carousel (inactive)
index: 1 -> ./teaser.module.css
index: 2 -> @segments/carousel/slide.ts  (lost original order from barrel)

Result: CSS order is wrong because slide.ts lost its original
position relative to teaser.module.css

WITH THE FIX:

Initial import order in parent module:
index: 0 -> @segments/carousel/index.ts (barrel file)
index: 1 -> ./teaser.module.css

After tree-shaking + fix:
index: 0 -> @segments/carousel (inactive)
index: 1 -> @segments/carousel/slide.ts  (sorted next to its barrel file)
index: 2 -> ./teaser.module.css

Result: CSS ordering preserved because we restored the barrel file's position
and internal ordering before removing it

I tested this fix for the reproduction repo at: https://github.com/jantimon/reproduction-webpack-css-order

With the fix the CSS order is the same as for other bundlers like Parcel or Vite

All changes happen only inside the SideEffectsFlagPlugin and only if a barrel file was removed by that plugin

For more information about the problem please see #18961

webpack-bot · 2024-11-26T10:39:40Z

For maintainers only:

This needs to be documented (issue in webpack/webpack.js.org will be filed when merged)
This needs to be backported to webpack 4 (issue will be created when merged)

alexander-akait

Let's add a test case like in your repo

alexander-akait · 2024-11-28T12:14:36Z

lib/optimize/SideEffectsFlagPlugin.js

+									// Ignore lazy import dependencies
+									if (
+										directIncomingConnection.dependency instanceof
+										ImportDependency


Why only this? Also let's add a test case too

dynamic imports follow their own order

did I miss any other imports?

alexander-akait · 2024-11-28T12:15:41Z

test/__snapshots__/StatsTestCases.basictest.js.snap

  ./vendor.js X bytes [built] [code generated]
-  ./module_first.js X bytes [built] [code generated]
  ./common2.js X bytes [built] [code generated]
+  ./module_first.js X bytes [built] [code generated]


Can we verify is it a right change?

I don't understand this change (it's changing the order in the stats output)

This seems expected, since now we keep the order of the optimized dependencies, in this case ./first.js -> ./common.js -> ./common2.js is optimized to ./first.js -> ./common2.js, before the order is changed by side effects optimization, so this dependency is moved behind ./module_first.js

…tion-css-order

jantimon · 2024-12-10T13:00:56Z

Let's add a test case like in your repo

done - please take a look

alexander-akait · 2025-02-05T14:46:04Z

/cc @ahabhgk @h-a-n-a Will be great if you look at this (feel free to ping other developers), I think it will be useful for rspack too, so I need a couple extra eyes, thank you

ahabhgk · 2025-02-06T12:36:53Z

While trying to understand the code here, I found a case that seems not work as expected: https://github.com/ahabhgk/webpack-side-effects-optimization-keep-connections-order/tree/main/reexports

In this case, dependency/index.js re-exports ./dependency2 and ./dependency, so the order of their css should be [dependency2.css, dependency.css], but the result is [dependency.css, dependency2.css]

valeryq · 2025-02-18T12:01:39Z

@jantimon hello, can you please take a look at the last comment with the wrong case?
It would be really helpful if this issue can be fixed. Thank you!

jantimon · 2025-02-18T18:04:46Z

while testing I found a bug when mixing lazy and non lazy imports

I'll add a test once I can reproduce it

alexander-akait · 2025-03-06T11:19:41Z

@jantimon Sorry for delay, can you add a test case?

Netail · 2025-03-28T15:24:12Z

If you need any help, just let us know :)
Would love to get this fixed for our design system 😅

alexander-akait · 2025-04-02T10:17:46Z

@jantimon Friendly ping

jantimon · 2025-04-04T12:25:19Z

While trying to understand the code here, I found a case that seems not work as expected: https://github.com/ahabhgk/webpack-side-effects-optimization-keep-connections-order/tree/main/reexports

In this case, dependency/index.js re-exports ./dependency2 and ./dependency, so the order of their css should be [dependency2.css, dependency.css], but the result is [dependency.css, dependency2.css]

@ahabhgk you are right - this was not intended

the problem is the way dependencies are tracked in webpack

maybe it's easier to understand by example:

import { dependency, dependency2 } from "./dependency/index.ts"; // index: 0 -> ./dependency (barrel)
import { dependency3 } from "./dependency3"; // index: 1 -> ./dependency3  (barrel)

export function component() {
	dependency3(); // index: 2 -> ./dependency3.ts
	dependency2();  // index: 3 -> ./dependency/dependency2.ts
	dependency(); // index: 4 -> ./dependency/dependency.ts
}

so with barrel files this would be

index: 0 -> ./dependency (barrel)
index: 1 -> ./dependency3 (barrel)
index: 2 -> ./dependency3.ts
index: 3 -> ./dependency/dependency2.ts
index: 4 -> ./dependency/dependency.ts

after the sorting fix it would be:

index: 0 -> ./dependency (barrel)
- index: 3 -> ./dependency/dependency2.ts
- index: 4 -> ./dependency/dependency.ts
index: 1 -> ./dependency3 (barrel)
- index: 2 -> ./dependency3.ts

and after barrel file optimization:

index: 3 -> ./dependency/dependency2.ts
index: 4 -> ./dependency/dependency.ts
index: 2 -> ./dependency3.ts

I guess this is almost perfect - the only thing which is wrong is that the order in import { dependency, dependency2 } is ignored

jantimon · 2025-04-04T12:29:59Z

@jantimon Sorry for delay, can you add a test case?

we spend another day of investigation and saw that a lazy import common chunk changes its child modules

we can see it happening one single time in our application with 17.000 modules but we did not manage to create a mini reproduction out of it

Netail · 2025-04-04T13:44:36Z

we can see it happening one single time in our application with 17.000 modules but we did not manage to create a mini reproduction out of it

That's a bummer. Was this in NextJS (As I've seen you in some PRs/Issues there too) or something else? As NextJS has some issues regarding CSS order too, related to server <-> client components. If it's not, we could investigate it separately from this part, so a big chunk is already fixed with this PR :)

Mad-Kat · 2025-04-04T14:08:47Z

we can see it happening one single time in our application with 17.000 modules but we did not manage to create a mini reproduction out of it

That's a bummer. Was this in NextJS (As I've seen you in some PRs/Issues there too) or something else? As NextJS has some issues regarding CSS order too, related to server <-> client components. If it's not, we could investigate it separately from this part, so a big chunk is already fixed with this PR :)

Yes this was within a next.js pages router project. But we're still trying to figure out why it's happening.

Netail · 2025-04-04T14:14:32Z

we can see it happening one single time in our application with 17.000 modules but we did not manage to create a mini reproduction out of it

That's a bummer. Was this in NextJS (As I've seen you in some PRs/Issues there too) or something else? As NextJS has some issues regarding CSS order too, related to server <-> client components. If it's not, we could investigate it separately from this part, so a big chunk is already fixed with this PR :)

Yes this was within a next.js pages router project and our primary goal is to fix the CSS order issues with this PR 😅 . But we're still trying to figure out why it's happening.

As I noticed the following in NextJS; https://github.com/Netail/repro-app-dir-css-order, but I don't think it's Webpack, else it would have been wrong in both a server as client component. The only difference is the client directive

Netail · 2025-05-07T14:40:10Z

Friendly ping @jantimon / @Mad-Kat :)
Any update?? 👀

Netail · 2025-06-10T21:19:58Z

Should we get this in? Then, fix the remaining CSS issues in follow-up PRs, as the CSS order in the current release is completely broken with sideEffects. This should at least fix a big chunk of the current CSS issues (cc: @alexander-akait)

alexander-akait · 2025-07-14T10:57:43Z

Fixed by #19686, thank you for your test cases and ideas how to improve our behavior, feel free to feedback

alexander-akait · 2025-07-14T10:57:43Z

Fixed by #19686, thank you for your test cases and ideas how to improve our behavior, feel free to feedback

keep consistent css order

a877eae

webpack-bot added the PR: unreviewed label Nov 26, 2024

don't resort lazy imports

e7a5253

jantimon force-pushed the side-effects-optimization-css-order branch from 95e1dcd to e7a5253 Compare November 27, 2024 11:07

alexander-akait reviewed Nov 28, 2024

View reviewed changes

jantimon added 2 commits December 6, 2024 02:08

add test

ceceb1f

Merge remote-tracking branch 'origin/main' into side-effects-optimiza…

040e420

…tion-css-order

Netail mentioned this pull request Jan 21, 2025

fix(build): fix css modules out of order issue from libraries vercel/next.js#70087

Open

alexander-akait mentioned this pull request Mar 6, 2025

Fix: Preserve CSS order when using tree-shaking #19285

Closed

sos0 mentioned this pull request Jun 11, 2025

Cannot find module sonner/dist/styles.css?url after upgrading to v2.0.4 emilkowalski/sonner#648

Closed

xiaoxiaojx mentioned this pull request Jul 11, 2025

fix: keep the module graph traversal order consistent #19686

Merged

alexander-akait closed this Jul 14, 2025

Uh oh!

Conversation

jantimon commented Nov 26, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

webpack-bot commented Nov 26, 2024

Uh oh!

alexander-akait left a comment

Choose a reason for hiding this comment

Uh oh!

alexander-akait Nov 28, 2024

Choose a reason for hiding this comment

Uh oh!

jantimon Dec 10, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexander-akait Nov 28, 2024

Choose a reason for hiding this comment

Uh oh!

jantimon Dec 10, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ahabhgk Feb 6, 2025

Choose a reason for hiding this comment

Uh oh!

jantimon commented Dec 10, 2024

Uh oh!

alexander-akait commented Feb 5, 2025

Uh oh!

ahabhgk commented Feb 6, 2025

Uh oh!

valeryq commented Feb 18, 2025

Uh oh!

jantimon commented Feb 18, 2025

Uh oh!

alexander-akait commented Mar 6, 2025

Uh oh!

Netail commented Mar 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alexander-akait commented Apr 2, 2025

Uh oh!

jantimon commented Apr 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jantimon commented Apr 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Netail commented Apr 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Mad-Kat commented Apr 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Netail commented Apr 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Netail commented May 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Netail commented Jun 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alexander-akait commented Jul 14, 2025

Uh oh!

alexander-akait commented Jul 14, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

jantimon commented Nov 26, 2024 •

edited

Loading

jantimon Dec 10, 2024 •

edited

Loading

jantimon Dec 10, 2024 •

edited

Loading

Netail commented Mar 28, 2025 •

edited

Loading

jantimon commented Apr 4, 2025 •

edited

Loading

jantimon commented Apr 4, 2025 •

edited

Loading

Netail commented Apr 4, 2025 •

edited

Loading

Mad-Kat commented Apr 4, 2025 •

edited

Loading

Netail commented Apr 4, 2025 •

edited

Loading

Netail commented May 7, 2025 •

edited

Loading

Netail commented Jun 10, 2025 •

edited

Loading