In the context of design systems and component libraries

[TrevorRice]

Hi, all! Great work on vanilla-extract. I'm currently evaluating some zero-runtime alternatives to Emotion and have a few questions specifically around usage in design systems and component libraries that I'd love to get your (or anyone's!) opinion on and maybe how you're planning to approach things in Braid.

1. This is certainly use-case specific, but I'd be curious to know how you'd approach delivering the generated CSS file(s). Would you distribute a file per component? Bundle your entire system into a single file? Ultimately, what would/should happen when a consumer imports a single component from your system?

2. How might one approach component, theme-based overrides (think Theme UI's sx prop)? For instance, suppose I have a Button that uses 2x from a theme's spacing scale, but a consumer for whatever reason needed to use 4x. How might they access the theme values to provide such an override?

Thanks!

[mattcompiles]

Hey Bud 👋

1. I'd suggest compiling all the CSS at the time of bundling. So consumers of your design system would need to install the vanilla-extract plugin of their choice as part of an initial setup. That way the bundler can be configured to do whatever they consumer prefers for CSS. I don't think pre-compiling CSS is a very good option.

2. This would depend on the specific situation but as the styles are just data you can make any API out of them you'd like. You can also make your theme contracts public API for consumers to create their own. You could also use Sprinkles and make your atoms function part of your design API. Theirs lots of good choices here.

[MakhBeth]

Isn't better to compile the CSS?
If the design system is delivered via node_modules with compiled TS why the CSS should be compiled with the bundler? Isn't something that I've seen before. There are's example of that?

[mattcompiles]

You can do both, but I wouldn't say there is any clear precedence here. I don't think the community has ever fully agreed on how to ship CSS as part of an NPM package. It depends on your bundler configuration and it results in invalid code as writing import 'styles.css' isn't valid JS/TS. Also, you'd have to use a bundler to compile your package before shipping to NPM where most packages would just use tsc or babel.

I think vanilla-extract handles this nicely as you can ship valid JS code to NPM and the code is consumable within any JS environment (e.g. node). But you can also turn the styles into CSS via your integration of choice.

[bestickley]

You can precompile with typescript or babel. That's not an issue.

@mattcompiles , I think this is an issue. When I pre-compile my .css.ts files into .css.js files and package them up into an NPM package then try to consume the package I get the below vanilla extract error because my styles are compiled to .css.js files.

Uncaught 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/getting-started
    at getFileScope (vanilla-extract-css-fileScope.browser.esm.js:27:11)
    at generateIdentifier (vanilla-extract-css.browser.esm.js:159:7)
    at style (vanilla-extract-css.browser.esm.js:345:19)
    at FooterArea.css.js:2:27

It seems like we must include source files (.css.ts) in NPM package to consume vanilla extract library.

[mattcompiles]

We're looking to make the process easier for people shipping VE code inside packages. However, it's definitely possible currently. There must be something wrong with the setup or you're hitting a bug. If you can create a small reproduction of what you're seeing we can see what's going wrong.

[bestickley]

@mattcompiles, thanks for the response. I've documented the issue here. Please take a look when you have a moment.