Styled System

What is the styled-system folder and how does it work?

While Bamboo generates your CSS at build-time using static extraction, we still need a lightweight runtime to transform the CSS-in-JS syntax (either object or template-literal) to class names strings. This is where the styled-system folder comes in.

When running the bamboo or bamboo codegen commands, the config.outdir will be used as output path to generate the styled-system in.

This is the core of what the styled-system does:

css({ color: 'blue.300' }) // => "text_blue_300"

Since Bamboo doesn't rely on any bundler's (vite, webpack, etc) plugin, there is no code transformation happening to convert the CSS-in-JS syntax to class names at compile-time. This is why we need a lightweight runtime to do that.

The same principles applies to patterns, recipes and even jsx components, as they all use the css function under the hood.

If you look inside your styled-system folder, you should see the main entrypoints for the runtime:

styled-system

css
jsx
recipes
patterns
tokens
types
styles.css

Feel free to explore the files inside the styled-system folder to get a better understanding of how it works in details!

💡

Note: The styled-system folder is not meant to be edited manually. It is generated by Bamboo and should be treated as a build artifact. This also means you don't need to commit it to your repository.

How does it work?

When running the bamboo command or with the postcss plugin, here's what's happening under the hood:

Load Bamboo context:

Find and evaluate app config, merge result with presets.
Create bamboo context: prepare code generator from config, parse user's file as AST.

Generating artifacts:

Write lightweight JS runtime and types to output directory

Extracting used styles in app code:

Run parser on each user's file: identify and extract styles, compute CSS, write to styles.css.

That 2. Generating artifacts step is where the styled-system folder is generated, using the resolved config that contains all your tokens, patterns, recipes, utilities etc. We generate a tailored runtime for your app, so that it only contains enough code (and types!) to support the styles you're using.

Pre-rendering

If you use some way to pre-render your components to static HTML, for example using Astro or RSC, the styled-system functions like css and others will be removed at build-time and replaced by the generated class names, so that you don't have to ship the runtime to your users.