Vanilla Extract and Design Systems

[rtkaaho]

Hope all is well m8. For the last 6 months or so since VE came out I have been building and deploying a design system using VE to a bunch of teams at work. Making use of sprinkles and such to find some consistency. Its been great. However, as the component library grows, we are quickly reaching bundle size problems. Not really VE's fault, just a fact of growth really. As a result I am trying to split up the components into separate packages. Prior to this change all components and styles were getting bundled, and the consuming apps needed to just import the component they need and make sure to import the styles.css at the root of the application.

However, for obvious reasons, I dont want to have to ship a giant style.css file as we continue to add more and more components. Therefore I am playing around with the model of shipping the raw .ts and .css.ts files in the packages and passing the transpilation off to the consuming app. I.e they need to download the VE plugin for their respective bundler and go from there.

In testing this methodology I am running into a couple errors. Consider the following example:

I am shipping a button component that has the following files, button.tsx and button.css.ts . The button.tsx does the import * as styles from "./button.css" like normal. However when I install this package in a consuming application and configure it with the VE plugin for vite, I am getting the following error:

[vite] Internal server error: Styles were unable to be assigned to a file. This is generally caused by one of the following:

- You may have created styles outside of a '.css.ts' context
- You may have incorrect configuration. See https://vanilla-extract.style/documentation/setup
  Plugin: vanilla-extract

Are you aware of a way to fix this? I assume it is because of the scope of the .css.ts import is in node_modules. But I haven't been able to figure out how to fix it. I came across this discussion where you mentioned that this is the preferred way for design system maintainers to distribute their VE code #102

Perhaps we should consider writing a guide informing people how to execute on this methodology? Has anyone in the discord been able to get this working ?

[adamaho]

So, I decided to attempt to create an example reproduction and couldnt figure out how to repro. So I assume there is a lot more complicated stuff going on in the repo I have at work. For those that find this and are curious. Have a look at these two repos:

1. The button component with ve styles: https://github.com/adamaho/aho-ve-button
2. The app that consumes the button component: https://github.com/adamaho/aho-ve-button-app

The above is an example of a scaleable way to distrubute components that are styled with ve without having to bundle styles

[bestickley]

@adamaho, to be clear, in the aho-ve-button repository where you're creating the library, you're simply publishing the NPM package with source code (.tsx and .css.ts), and then consuming that source code in aho-ve-button-app, right? Is it not possible to publish the aho-ve-button library with compiled code (.jsx and .css.js) and consume in aho-ve-button-app?

[bestickley]

Nevermind, confirmed with picture above. Notice node_modules/aho-ve-button/src

[rtkaaho]

Another thing I am noticing is that if your versions of vanilla-extract are not the same, you will run into this error as well.

[harisraharjo]

Do you use monorepo?

[adamaho]

Yup, for the design system. But you need to make sure that you define ve as a peer dep to make sure that teams consuming the design system only ever have one version of @vanilla-extract/css running.

So in the case of the problem I was running into, I accidentally had a component package specify ve as a dependency and then was installing ve in the consuming app at a different version. Which is what caused the error mentioned above.

[roginfarrer]

I'm not sure about the issue with the Vite plugin, but I can share how my company's design system is approaching the issue of CSS bundle size. Consuming applications aren't set-up yet to compile VE CSS, so we are precompiling components' styles "in place".

I started with their esbuild set-up guide, and modified it considerably to get this working. I treated each .css.js file as its own entry point. The build process had two processes: run esbuild against all of the .css.js files, then run esbuild again against the rest of the JS/TS files.

In your output, you will now have Component.js, Component.css.js (which just exports the CSS class hashes), and Component.css.css (the extension is weird, but it's the compiled CSS file).

Then it depends on how you expect the consuming application to bundle those discrete compiled CSS files. If the app uses Webpack or another compiler that supports importing CSS files, you could write a custom esbuild transformer to transform the imports for the VE CSS files into that style css import

So it's a little complex, but I think it's possible. I was planning to write a blog post at some point that goes into this in greater detail. But here's a snippet in the meantime (not entirely complete, but hopefully gets the point across)

await Promise.all([
    /**
     * Modular CSS Files
     * We need to compile these first because they must be bundled
     * (in order to compile @vanilla-extract out)
     * But we don't want to bundle out any other library, so this step
     * produces a css file, and the css.js file gets compiled to className hashes
     */
    esbuild
      .build({
        entryPoints: cssEntryPoints,
        bundle: true,
        plugins: [vanillaExtractPlugin()],
      }),

    // Rest of the JS/TS files
    esbuild
      .build({
        entryPoints: entryPoints.filter((path) => !path.includes('.css.ts')),
        loader: {
          '.js': 'jsx',
        },
       // plugin that injects the `import 'Component.css.css';` line
        plugins: [inlineCssPlugin],
      })
      .catch((e) => {
        console.error(e);
        if (!watch) {
          process.exit(1);
        }
      }),
  ]);

[roginfarrer]

If you swap out Vite for esbuild or webpack in the app, does the problem go away? I don't think we had any issues with the webpack plugin

[rtkaaho]

Yeah vite works great. I must have not explained myself very well. The example repos I posted above is a working example of how you could go about compiling ve on the app side instead of the library side. I am just working through getting that working in the design system at work. Which is obviously much more complicated then a single button. I am just sharing my thoughts in this thread so others can learn from the mistakes im making lol.

[roginfarrer]

Ahhh I see, your solution was having the app compile all of the styles. Yeah I think that's the ideal case, it solves a lot of the packaging challenges, but it does add to the application's build time (if that's not an issue, then it's moot)

[adamaho]

Yeah for sure. I mean the consuming application will have its own styles. And ideally, your design system provides 80ish% of the styles required to build an application via sprinkles. So most of the style will be reused and therefore the resulting css style sheet is small. So there shouldnt be much of an impact on build times. It will only transpile the things you need at build time.

[graup]

I like this approach. Looking forward to your blog post. Curious how cssEntryPoints and inlineCssPlugin are defined.

[mattcompiles]

Thanks for the examples and different solutions raised here. I'd love to smooth over packaging of VE styles more but all the approaches here sounds pretty reasonable for different use-cases.

Personally, I'm a fan of compiling the styles within the consuming application for the most part. However it can be difficult and limits your bundling/transpiling options at the package level. We're working on a tool for braid that will hopefully allow bundling and TS -> JS transpiling to happen ahead of time at the package level while still letting the styles be compiled to .css in the consuming application.

[adamaho]

This sounds exciting! I am curious to what solution you have come up with. Will it be sku based? Or webpack/vite for bundling and such ? This is really the only problem that is left to solve when it comes to bundling and distributing design systems at scale. Its not unique to ve. Same thing happens with css modules, sass, etc. One approach that I find interesting is the emotion/styled-components approach, where the styles actually get bundled into the js. But that obviously comes with other performance related tradeoffs.

Plus ve is the best :P

[mattcompiles]

We're looking at building on top of Vite library mode, which is essentially an opinionated version of Rollup.

[adamaho]

NIce, that is what all of my libs are using right now. That is good to hear.

[mihkeleidast]

I recently created a small POC that does the "TS -> JS transpiling ahead of time at the package level while still letting the styles be compiled to .css in the consuming application" thingy. It seemed to work well - is there anything I might've missed that would not work with this approach very well at this time?

The POC repo: https://github.com/mihkeleidast/vanilla-extract-component-library-example

[graup]

I'd prefer to build inside the design system first and only import js/css in my app. I think that's way cleaner as it doesn't require installing and managing VE in the apps. It should also be faster if you have multiple apps, because you only need to build the design system once.

As far as I understand, VE already builds every .css.ts file separately, but the issue is that bundlers like Vite/Esbuild combine all css into one file. Is that right?

Output that I want:

index.js (export * from ./Button)
Button/index.js (component, imports .css.js and .css)
Button/index.css.js (ve runtime and class names)
Button/index.css (compiled styles)

So I want to compile but not bundle the CSS.

I tried a few combinations but none of them seem to work.

• Esbuild + VE Esbuild plugin: doesn't work because esbuild doesn't support preserveModules, it always bundles everything.
• Rollup: supports preserveModules but there's no VE plugin for rollup :(
• Vite/Rollup + VE Vite plugin: building separate modules works but CSS is still combined into one file.

So maybe we can try A) making a VE rollup plugin or B) finding a way to tell Vite to not bundle CSS?

// vite config
import { defineConfig } from 'vite';
import { resolve } from 'path';
import { vanillaExtractPlugin } from '@vanilla-extract/vite-plugin';

export default defineConfig({
  plugins: [
    vanillaExtractPlugin(),
  ],
  build: {
    lib: {
      entry: resolve(__dirname, 'lib/index.ts'),
      formats: ['es'],
    },
    rollupOptions: {
      external: ['react'],
      output: {
        preserveModules: true,
        preserveModulesRoot: 'lib',
      }
    }
  }
})

[mattcompiles]

Have you tried playing with the manualChunks option for get CSS splitting the way you'd like?

[AndrewLeedham]

I have been tackling this same problem today.

CSS code splitting can be achieved by enabling build.cssCodeSplit. However, all the created assets will have the same name which seems to be based on what is set as the root in your vite config. (if you don't have hashes enabled, it may only show up as 1 file as they will have the same name)

manualChunks is not compatible with preserveModules it throws

Invalid value for option "output.manualChunks" - this option is not supported for "output.preserveModules".

I tried using output.assetFileNames but you just get information about the current asset name and its contents, not where it was imported.

@mattcompiles Any ideas on where the asset name is derived from, is that a Vite thing? The virtual file path seems to include the importer, but that information is lost somewhere in the pipeline.

[AndrewLeedham]

Looking into this further. It seems Vite is using chunk.name (when build.cssCodeSplit is enabled, otherwise it uses "style.css") which is essentially the path.basename of the virtual file path. Which is generated here in VE: https://github.com/seek-oss/vanilla-extract/blob/6eb27b534cbb8b2cb24fdac6b07e720003607ee3/packages/vite-plugin/src/index.ts#L152 where fileId is https://github.com/seek-oss/vanilla-extract/blob/6eb27b534cbb8b2cb24fdac6b07e720003607ee3/packages/integration/src/processVanillaFile.ts#L18

Meaning for every CSS file, the emitted asset is the actual name of your npm package. From what I can tell this is an unintentional side-effect. I can think of 2 possible solutions:

1. re-order the virtual file extension so the importer file is last rather than the package name.
2. Add a config option along the lines of cssFileNames to the VE vite plugin which is given fileScope and you can generate your own file name like rollup does for assets/chunks/entries. This would then be added after the virtual prefix.

Happy to create an issue and take a swing at the implementation for one of the above, if you think it would make sense @mattcompiles?

[AndrewLeedham]

@graup Looks like build.cssCodeSplit alongside rollupOptions.output.preserveModules should do the trick. However, the above naming issue seems to be a bug when using a scoped package name. See the issue here: #631 if you are not using a scope you should be fine 😃