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.

[raphaelboukara]

@askoufis sorry for the delay.

I'll try to be clearer about the use case.
My issue is around webpack externals.
My webpack config includes some webpack externals.
One of those externals is a package that expose some basic UI components and some vanilla tokens via createGlobalTheme.

In my project, I import a specific token from this external package. At build time, vanilla will build the tokens for my actual package which is perfect. However, I don't need vanilla to output the css from this external. Because it's an external, somebody else in my design care about adding the css of this external to the dom.

So, when calling appendCss, there is no reason to append CSS that comes from an external package.

Am I clear? Do you see a use case where we will want to ouput CSS of a webpack external?

I would propose 3 options:

• Provide a more flexible outputCss option so I can defined my own behavior and decide when to output css.
• Update the code to be something like if (outputCss && !isExternal(fileScope.filePath)) {....
• Add a new option like outputExternalsCss.

I understand the solution you proposed, I can add an additional build to the external package so it will expose all the tokens directly from JS but I would want to avoid to have another build to maintain particularly if it makes sense to not appending external CSS.

Do you need more details about the use case or it's clear enough?