Supporting CSS-in-JS

[mayank99]

It's not super clear which CSS-in-JS libraries work, so I'm creating this issue as sort of a place to start the conversation and document the current status.

Here's a few popular libraries that I know about (will keep this list updated):

Library	Status	Notes
styled-components	🟡 Partially works	Prod build errors with: styled.div is not a function. Can be worked around with client:only or by using buildSsrCjsExternalHeuristics and ssr.noExternal (will cause FOUC).
emotion	🟡 Partially works	Prod build errors with: styled.div is not a function. Can be worked around with client:only or by using conditional default import (will cause FOUC). Can also patch @astrojs/react.
linaria	🟡 Partially works	Prod build errors with: Named export 'styled' not found. Can be worked around using buildSsrCjsExternalHeuristics and ssr.noExternal or by downgrading to v3.
stitches	🟡 Partially works	<style> tag for SSR needs to be in React component
typestyle	✅ Works	-
vanilla-extract	✅ Works	-
solid-styled	🟡 Partially works	Causes FOUC
styled-jsx	❌ Doesn't work	No vite or rollup plugin, requires babel
compiled	❌ Doesn't work	No vite or rollup plugin, requires babel

From what I understand, if a library doesn't work in astro, it's because of one or more of these reasons*:

• no support for vite/rollup
• it requires babel
• it uses context
• it requires access to the renderer for SSR styles
• it doesn't work with new react 18 apis

^{*I could be wrong so would be nice if someone can verify the above points.}

---

Additionally, here's what @FredKSchott would like to see (quote message from discord):

1. A table of which CSS-in-JS libraries are/aren't supported in Astro. If not supported, it would also list the reason. If supported, these could also have tests in the repo so that we don't break them in the future.
2. Some time to go through the ones that aren't supported and try to fix any issues that are fixable by Astro.
3. For any the css-in-JS libraries that still aren't supported after that, a clear error message inside of Astro core when it sees you try to import the package.

GitHub repo with examples:

https://github.com/mayank99/astro-css-in-js-tests

Participation

• I am willing to submit a pull request for this issue.

[matthewp]

This looks great! Is one of the goals of this to get documentation into the docs site?

[mayank99]

This looks great! Is one of the goals of this to get documentation into the docs site?

Yup! After testing everything (including some more advanced cases) and fixing anything that's fixable by Astro, I believe we want to document what works, what doesn't work, and suggest alternatives.

[mayank99]

I feel like it should be possible to fix styled-components and emotion. The big problem with both of them is that their SSR¹ strategy requires altering the html produced by react's renderToString/renderToNodeStream methods.

The styled-components docs suggest wrapping the whole <App /> with a provider but only on the server. Theoretically, it should be possible to do this for every island in astro, but we don't have access to react's render methods in userland and we cannot do this with a wrapper component.²

As for emotion, the docs suggest two strategies. The default approach is supposed to work without any additional configuration, but I'm still seeing FOUC³ (this might be worth investigating). The advanced approach is similar to styled-components in that it needs to wrap the app in a provider and do a sort of "double render" to add the styles after the first render, and hydrate the styles on the client.

@matthewp Would it be possible for Astro to allow hooking into the rendering pipeline? That might solve both of these issues.

Footnotes

1. SSR = server-side rendering but really I mean any form of prerendering, including static generation ↩

2. From sc docs: "sheet.getStyleTags() and sheet.getStyleElement() can only be called after your element is rendered. As a result, components from sheet.getStyleElement() cannot be combined with into a larger component." ↩

3. FOUC = flash of unstyled content ↩

[matthewp]

@mayank99 Since these are for React apps I think it makes the most sense that this is part of some API for the React renderer. That might also require core Astro changes, I'm not sure.

There already is a hook into the rendering pipeline via the renderer API, so it might be possible to prototype this idea as a separate renderer before plugging it into the React render (although either approach is reasonable).

You'd want it to work with streaming, it looks like styled-components has as solution for that: https://styled-components.com/docs/advanced#streaming-rendering

[nstepien]

Another lib worth trying is astroturf, which would be good fit for this project just for the name alone 🙃
https://github.com/4Catalyzer/astroturf
https://4catalyzer.github.io/astroturf/introduction/

[mayank99]

@nstepien I did look into astroturf but excluded it from the list because there is no vite/rollup plugin and the library does not look like it's maintained anymore.

[nstepien]

I've not tried it myself, but the docs do mention a rollup plugin: https://4catalyzer.github.io/astroturf/setup

[osdiab]

Also btw https://github.com/typestyle/typestyle worked fine when i tried it.

[mayank99]

@osdiab I've added an example for typestyle and updated the table. Thanks for the recommendation.

[matthewp]

@mayank99 if you have failing Stackblitz examples for the ones that are possibly bugs that would be helpful for debugging.

[mayank99]

@matthewp You should be able to open the examples repo in stackblitz.

https://stackblitz.com/github/mayank99/astro-css-in-js-tests/tree/main/styled-components
https://stackblitz.com/github/mayank99/astro-css-in-js-tests/tree/main/vanilla-extract

Swap out the last part of the url with the name of the library you want to debug.

https://stackblitz.com/github/mayank99/astro-css-in-js-tests/tree/main/styled-components
                                                                       ^^^^^^^^^^^^^^^^^

[dephiros]

In solidjs/solid-styled-components#27, I saw mentioning of running extractCSS or similar methods for css-in-js libs. Did anyone take a look in something similar?
This is my failed attempt at it trying to get goober working. As is, it will work only when client:load is enabled for a component: https://stackblitz.com/edit/github-rqtizn-easxa3?file=astro.config.mjs

Basically, we need to put the css from extractCss called to a style in head with id _goober but now sure how to do that with tr

[Coobaha]

We are also evaluating Astro now for SSR at @RapidAPI and this seems a huge blocker, since we rely on emotion in our ui lib

[arthur-fontaine]

vanilla-extract now supports Astro! vanilla-extract-css/vanilla-extract#796

[mayank99]

I've updated the table with the most recent status. A lot more green now 💚

In addition to official vanilla-extract support, I was able to work around the build errors in styled-components/emotion/linaria by using a combination of vite.legacy.buildSsrCjsExternalHeuristics and vite.ssr.noExternal (see commit).

styled-components/emotion will still cause FOUC so the next step would be to look into injecting styles into the SSR output (detailed in my earlier comment).

[JeroenReumkens]

Hey @mayank99
I was just giving your Stitches example a try. Am I correct in assuming that you can not abstract the head component into a layout and add the Styles component in there? When trying this I see styles from page 1 leaking into page 2, causing unnecessary styles to be in that page. So it seems that during build Astro is keeping the layout (and thus the head), and the styles will get added on top of the existing ones. Especially in bigger apps I'd rather not repeat all of the head content.

Thanks for this great overview 🙏

Edit:
Oh actually, when removing the layout and creating 2 pages with each their own head with the styles included as in the example, it still doesn't work. Somehow it now even flips the styles (eg I have a colored button on page 1, but those styles are now on page 2 and now on page 1 in the build) 🤔

[jon301]

I'm not sure if it's normal but there is some FOUC (in dev mode only) with Astro + vanilla-extract
Taking the example from @mayank99 :

CleanShot.2022-09-15.at.08.42.56.mp4

No FOUC when building the app in production mode.

[susickypavel]

@jon301 This is related to the Vanilla Vite plugin itself, same behaviour can be observed in SvelteKit.

[igorbt]

@mayank99 , thank you for great overview and for the Stackblitz examples!

I needed to make Astro work with Emotion, because I use Material UI in my website. Even if I've could use also styled-components, the default approach of Emotion seemed interesting to me, pretty simple and no big changes needed.

I tried your repo with examples and somehow the workaround for styled.div is not a function that you found (buildSsrCjsExternalHeuristics one) didn't work. I found a shameful workaround of myself just to not get stuck:

import styledImport, { CreateStyled } from '@emotion/styled';
let styled = typeof styledImport.default !== 'undefined' ? styledImport.default as any as CreateStyled : styledImport;

Then I've got it working but with FOUC. Emotion didn't render <style> tags alongside the components on the server. It was happening because Astro React integration uses renderToPipeableStreamAsync, but Emotion doesn't support it yet - it's still an open feature request. But it supports (the now deprecated) renderToNodeStream that actually does the job - full Suspense support, but without streaming (according to this ).

So my second workaround was to patch @astrojs/react server.js and replace renderToPipeableStreamAsync with renderToNodeStreamAsync (a new function with a similar implementation to renderToStaticNodeStreamAsync). Then FOUC was gone.

There are 3 ways forward for Emotion that I see:

1. Try to hook into Astro rendering to see if advanced approach works
2. Wait when emotion will support renderToPipeableStream. But it seems not so easy, and most probably it will not be available with the default approach, but only with advanced approach. So we would probably need to hook into Astro rendering anyway.
3. Somehow be able to configure Astro React integration to use renderToNodeStream. That would not do any damage, IMHO. Even if renderToNodeStream supports Suspense without streaming... astro react integration waits anyway for the whole stream to end before going forward. Of course using deprecated stuff is not OK, but making it user opt-in should be fine.

What do you think we should do?

[mayank99]

@igorbt Thanks for looking into this, great work!

the workaround for styled.div is not a function that you found (buildSsrCjsExternalHeuristics one) didn't work.

So in my repo I'm using a conditional vite config, and it doesn't seem to get the correct values. It works in prod (but not in dev) if I just do this:

vite: {
	legacy: { buildSsrCjsExternalHeuristics: true },
	ssr: { noExternal: ['@emotion/*'] },
}

I found a shameful workaround of myself just to not get stuck:

import styledImport, { CreateStyled } from '@emotion/styled';
let styled = typeof styledImport.default !== 'undefined' ? styledImport.default as any as CreateStyled : styledImport;

This is actually great! I think I tried a variation of this and couldn't get it to work, so I'm happy you were able to. This is better than buildSsrCjsExternalHeuristics imo, so I will update the table.

1. Try to hook into Astro rendering to see if advanced approach works

I think this would help with styled-components too (as I mentioned earlier). I'm not sure what would be the best way to expose this to users, outside of asking them to make a customized version of the react integration.

3. Somehow be able to configure Astro React integration to use renderToNodeStream. That would not do any damage, IMHO. Even if renderToNodeStream supports Suspense without streaming... astro react integration waits anyway for the whole stream to end before going forward. Of course using deprecated stuff is not OK, but making it user opt-in should be fine.

I agree, it should be opt-in if astro decides to use renderToNodeStream. But I also feel like patch-package might be enough since this is a small change.

@matthewp What do you think?

[igorbt]

It seems advanced approach for Emotion SSR only works with ReactDOM. renderToString, so I guess it will not work with current Astro React integration.

[igorbt]

For styled-componets situation is almost the same as with emotion - there is no support for new React SSR API renderToPipeableStream (here is the open issue for this). There are some signs that authors are working towards it. And there is a workaround, that basically buffers the stream, so no real support for streaming. Probably we could use that workaround, but hooking into Astro rendering.

Actually React team stated pretty clear that the architectural changes for v18 will make it pretty hard for CSS-in-JS libs to get along: reactwg/react-18#110 and they even advice for "You could however build a CSS-in-JS library that extracts static rules into external files using a compiler".

On a more pragmatic note, because Astro mainly uses SSG, the streaming support is not important, and using (deprecated) renderToNodeStream might be a temporary solution. But for Astro SSR use-case I'm not sure how important the streaming support is.

[guiguan]

I can confirm that the astro + solid-styled-components (goober solid wrapper) + twin.macro works nicely in both SSR and CSR mode, and also in both dev and prod settings

[osdiab]

@mayank99 btw I've been using Panda CSS and it also has been really nice. And they have explicit Astro support

https://panda-css.com/docs/installation/astro

[mayank99]

If you want to submit a PR to my github repo with an example of pandaCSS, feel free. But tbh I'm not sure what the point of this thread is anymore. When i first opened the issue, there were clear goals, which don't seem to apply anymore.

[kmesic]

How does Astro still not support CSS-in-JS via SSR easily??? I am using styled-components currently. I tried a couple of ways, but run into FOUC issue. If anyone has an example with styled-components with SSR would greatly appreciate!

I want to also try Linaria in Astro, but there seems to be limited documentation to integrate with Astro. Anyone try?

[ematipico]

These kinds of comments aren't helpful, at all. I suggest to upvote the discussion .

[mayank99]

I just realized I never shared that I built my own CSS-in-JS library specifically for Astro and as a direct result of this issue. https://www.ecsstatic.dev/

I don't like promoting my own stuff, especially in an issue I opened myself, but I'm sharing it here because it looks like folks are still trying to find a solution to this day (I hope that's ok).

It's not 1:1 to Styled-components, but it's zero runtime and very similar to the Emotion/Linaria css API, so it might fit your needs.

[kireerik]

My Emotion based solution in Refo (https://github.com/kireerik/refo) also worked with Astro as well:

• https://github.com/kireerik/refo/tree/main/index/module/style
• https://github.com/kireerik/refo#simple-page-example-source-code

This one doesn't depend on Vite and it is for build (or server run) time.
It has class name minification feature (like a, b, c, ..., aa, ab, ...) and class name labels in development mode (this later one is planned to be improved).

[vvaldesc]

Hello, I was doing a project in Astro and I decided to use certain Material UI components that I think are unique and very necessary for my project until I realized that Material isn't supported by Astro.

Since there is a Material component that is really important to my project, I have devised an alternative using self-redirect on-load.

At least for me, the components in Material are rendered correctly on the first load or display of the website, if I reload the page the CSS styles disappear. After trying a rendertostring and rendertopipeable without success, I decided that reload page really is the best option right now if you want to keep the component's java script.

Another problem is the operation of the scripts in Astro, because it emulates a SPA I think their operation is quite confusing, sometimes they only work the first time they are loaded (like Material components) instead of every time you view the site, and script threads are not killed on page change, I think This should be improved, and this is why for this solution I use a svelte or react component.

Svelte:

<script>
  import { onMount } from "svelte";
  onMount(() => {
    setTimeout(() => {
      console.log("onload");
      var url = new URL(window.location.href); // get the current url of page into variable
      var render = url.searchParams.get("render"); // get the 'render' parameter from the url
      if (!render) {
        // 'reloaded' parameter does not exist
        url.searchParams.set("render", "true"); // add the 'render' parameter to the url
        console.log(url.href);
        window.location = url.href; // "reload" the page
      }
    }, 40);
  });
</script>

The 40ms could be better, the page could be refreshed right when the page is initialized.
I use an url parameter to reload page once.

then i use the component:

<Refresh client:only="svelte" />

And material components should be client:idle to get better performance

[jcayzac]

I don't see it mentioned in the list at the top, but the standard import attributes don't work in Astro:

import 'something/something.js' with { type: 'css' }

// will be imported as a javascript module, not css, even
// on Node 21+ which has support for `with`, so no css
// gets injected into the component.