My journey (so far) through this, very impressive, source code.

[Brendan-csel]

I've been reading through the code to try and get my head around it - mostly just out of curiosity. I thought I'd write down what I've seen to help me remember.

CAUTION: I have no idea what I'm talking about - these are just some notes from a pretty superficial wander through these files.

My journey so far

All those functions we're calling in .css.ts files don't just return a class name we can use in our application code ...well that's mostly what they do while we're typing away in our editors... but at build time they are the beginning of much more.

1. During a build, the bundler walks through the files and then comes across these special .css.ts files which the vanilla-extract plugin puts its hand up to take care of.

2. First off the plugin wraps our .css.ts file in a few lines of code so it will know the contents should be scoped to our particular file (FileScope) and then calls back to the bundler (or esbuild anyway) to compile the .ts to .js.

3. The goal of the next stage is to run that .js code during which all those functions we were calling (eg style) do more than just return class names. Before running that code the plugin prepares an Adapter which, when run, allows those functions to appendCss, accumulating a collection of records describing style "rules" that will eventually become actual css.

4. There is then a whole lot of very clever looking code in the plugin that takes that collection of rules and turns it into a "virtual" css file (stored in a memory buffer). At this point the virtual .css file is not on the bundler's to-do list and that is where the next step kicks in.

5. Keep in mind we are still processing our .css.ts file. The plugin then essentially creates a much simpler (plain .js) interpretation of that file which critically also includes an import at the top to our new virtual '.css' file along with some recipes and a simpler version of the class name and exports we always got while writing the .css.ts file in our editor.

6. The bundler then receives this simplified '.js' file and sees it now needs to import the virtual .css files that the plugin has prepared. Again the plugin puts it hand up to handle the request for that file ...which had a special namespace to distinguish it from real css files on disk... and then the bundler takes over again and processes the css just as if it had been on disk the whole time.

That's about as far as I got. Hopefully these notes might help as an orientation for someone else looking at this code ...as well as to remind me.

Finally I want to say thanks to everyone involved with putting this together. All the points listed above are massively simplified (especially the trasformCss from rules bit) and I can see there has been a huge amount of work go into this project.

Again, thanks!!