Proposal: resolveStyleSheets and extractStyleSheets APIs

[dbanisimov]

I want to open a discussion for two possible additions to the vanilla-extract API that will help with use cases where the generated stylesheet need to be used at runtime.

resolveStyleSheets

resolveStyleSheets(): string[] - produces a list of URLs that could be used for injecting styles as <link /> elements at runtime, fetching them with JS, or giving them to third-party iframes, etc. The list of stylesheets include the compiled .css.ts file itself, as well as it's dependencies, e.g. if sprinkles were used.

extractStyleSheets

extractStyleSheets(): string[] - similar to resolveStyleSheets, but gives the stylesheet content that could be directly used or injected as a <style /> element.

Motivation

vanilla-extract generates the stylesheets, but offloads the final handling to the bundler. It works well most of the time, but presents challenges when a tighter control is needed for dynamically using the generated styles.

One example is using vanilla-extract with Remix. Remix needs to have the URL of a stylesheet in order to dynamically load them on route transitions, while taking advantage of long-term caching. It does expect this URL to come as a string in their route loader definition.

Another use case is injecting specific critical styles directly into the head part of the document. For example one might have a fonts.css.ts file that they want to be injected in the server-rendered document response. In webpack it is possible to do that with specific loaders configs, but it might be even trickier in other bundlers.

Possible implementation

vanilla-extract compiler already has the stylesheet content, as well as it controls how it's being imported into the final module.

For esbuild it simply generates import filescope.vanilla.css?source=base64content and for other bundlers it delegates the generation via serializeVirtualCssPath function.

vanilla-extract compiler can detect the presence of resolveStyleSheets or extractStyleSheets calls and generate appropriate exports and imports for them. The generated imports then will be resolved and loaded appropriately by the bundler plugin, with the addition of some hints for the plugins.

For example, in case of esbuild a file like this:

// style.css.ts
import { resolveStyleSheets, style } from '@vanilla-extrac/css';
export const red = style({ color: red });
export default resolveStyleSheets();

Will be compiled into:

import 'style.vanilla.css?source=base64content';
import stylesheet_randomHash from 'style.vanilla.css?source=base64content&loader=file';
export {
  red: 'style_randomHash',
};
export default [stylesheet_randomHash];

And the esbuild plugin in the onLoad callback will read the loader path parameter and tell esbuild to treat the generated css content as an asset file and generate a URL for it that will be available as the default export.

Other bundlers plugins can follow the similar idea. Implementing extractStyleSheets should be similar with different loaders used by the bundlers.

Ceveats

The bundlers support for this may vary and will require some testing.

These two proposed APIs also deviates from vanilla-extract approach of separating the compilation from bundling, as the specifics of handling generated CSS are now exposed through its own API plane.

The correct handling of all the dependent CSS files may have some challenges.

[mattcompiles]

Hi,

I think this is a pretty good idea for trying to fit into the constraints of remix. However, it's a lot of custom work just to (maybe) be able to work on their platform. Even if we added this API, remix would still need to add the @vanilla-extract/esbuild-plugin to their compiler, which I'm not sure they're are willing to do. I'm pretty hesitant to do any compatibility work with remix as our philosophies on writing CSS seem to be so different.

Now that's not to say we'll never support remix, but I feel like we'd need to discuss the integration with them, and have them be keen/on-board before doing a bunch of work.

[knoefel]

@mattcompiles Are there maybe any updates on this? It would be really cool using vanilla-extract in remix!!!

[AndrewLeedham]

Outside of Remix support I think this touches on an interesting point of exposing generated stylesheets. For example with the vite-plugin (especially since #631 landed 🎉) we can generate stylesheets for each component. However, we can't get a reference to said stylesheets as they are just generated as assets, and there is no URL exposed.

[AndrewLeedham]

Seems like exposing the css file reference from here could be useful. Perhaps in Vite land something like export stylesheetUrl from "${id}?url";, a problem I can forsee with this approach however is typings. Since stylesheetUrl is not actually exported from the .css.ts file and using declare module "*.css.ts" would negate the actual types coming from .css.ts files :/