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

• [x] 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[^1] 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.[^3]

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[^2] (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.

[^1]: SSR = server-side rendering but really I mean any form of prerendering, including static generation [^2]: FOUC = flash of unstyled content [^3]: 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."

[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

[mayank99]

I was starting to look into customizing the renderer when I decided to try the prod build (which I had not tried before), and unfortunately the situation is even worse. See updated chart in issue description.

styled-components and emotion both fail with: styled.div is not a function. Adding them to vite.ssr.noExternal does not seem to help. @linaria/css works fine but @linaria/react fails with: Cannot use import statement outside a module.

There are existing issues in all three repos (https://github.com/styled-components/styled-components/issues/3601, https://github.com/emotion-js/emotion/issues/2730, https://github.com/callstack/linaria/issues/1054) but I couldn't get the suggested workarounds to work. 🙁

Edit: these can be worked around using buildSsrCjsExternalHeuristics.

[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 https://github.com/solidjs/solid-styled-components/issues/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

[kevinseabourne]

If you guys can get styled components to work with Astro I am totally going to make the switch. I love styled components, works perfectly with component based styling and makes your code so easy to read.

[arthur-fontaine]

vanilla-extract now supports Astro! https://github.com/seek-oss/vanilla-extract/pull/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 :

https://user-images.githubusercontent.com/122108/190333357-c55ec618-a10a-4af9-bab6-3e5fc2de15d7.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: https://github.com/reactwg/react-18/discussions/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