Why CSS from externals packages is appended to my CSS bundle?

[raphaelboukara]

Hi,

The vanilla extract plugin includes an externals option.

Where can we find documentation about this feature? I'm trying to understand its exact functionality.

Specifically, when I define a package as "external", I expect the CSS variables from this package not to be included in my CSS bundle. However, this doesn't seem to be the case.

From my understanding, defining a package as "external" should signal to Webpack to exclude all exposed content from this package in the bundle.

However, it appears that the externals option only affects JavaScript files and does not consider CSS. Could you provide some clarification on this behavior and how we can achieve the desired outcome for CSS?

I played with it locally and I get it work by enriching the filter in the appendCss function of the css adapter:

vanilla-extract/packages/integration/src/processVanillaFile.ts

Lines 82 to 91 in e7d79f2

	appendCss: (css, fileScope) => {
	if (outputCss) {
	const serialisedFileScope = stringifyFileScope(fileScope);
	const fileScopeCss = cssByFileScope.get(serialisedFileScope) ?? [];
	fileScopeCss.push(css);
	cssByFileScope.set(serialisedFileScope, fileScopeCss);
	}
	},

Something like:

- if (outputCss) {
+ if (outputCss && !fileScope.filePath.includes('my_external_dep')) {

Maybe we can change the outputCss option to possibly be a function that receives the actual fileScope and return a boolean? If it's ok for you, can I send a PR? It will help me a lot to decrease CSS bundle size.

Something like:

- if (outputCss) {
+ if (typeof outputCss === 'function' ? outputCss(fileScope) : outputCss) {

My use case is that I have a page with multiple CSS bundle. Each CSS bundle uses CSS from some "external" package.

[askoufis]

We've documented externals in a few other plugins, it usually just connects to esbuild's externals build option.

We haven't done this for the webpack plugin though, and it's not exactly the same as the esbuild option anyway, but probably achieves a very similar effect. I'll make a PR to fix this.

I'm a bit confused as to what you expect the outcome to be. Are you using CSS variables from a separate package, but don't want them to be included in the CSS bundle? Or do you not expect CSS variables defined with Vanilla Extract to be included in the CSS bundle?

[raphaelboukara]

Thanks for your answer!

I have a package X containing CSS variables defined with Vanilla Extract.
In my page, 5 bundles. Each of them uses the package X.

When I bundle each of those bundles, I said webpack to set X as externals.
It works perfectly for the JS bundle, however, my CSS bundle includes CSS from X.

Because of that, I proposed to provide a more flexible outputCss option.

[raphaelboukara]

@askoufis you think it's envisageable? Sending a PR can help here?

[askoufis]

I'm not sure if your suggestion aligns with how outputCss was intended to be used. I'm hesitant to change how it works without first understanding your problem better.

Maybe the issue is with how your package is built. If you want your package to be external in both your JS and CSS bundles, then I'd suggest that the package itself should be bundled with separate JS and CSS entrypoints, instead of just exporting .css.ts files. That way, instead of needing to configure webpack (or VE) to make the CSS external, it's just external by default, and you have to explicitly import the CSS if you want it in your bundle.

Let me know if that makes sense. Otherwise, maybe a simple reproduction of your issue could help me better understand it.