Library Upgrade Guide: <style> (most CSS-in-JS libs) #110

sebmarkbage · 2021-10-12T01:52:36Z

sebmarkbage
Oct 12, 2021
Maintainer

Library Upgrade Guide: `<style>`

This is an upgrade guide for CSS libraries that generate new rules on the fly and insert them with <style> tags into the document. This would be most CSS-in-JS libraries designed specifically for React today - like styled-components, styled-jsx, react-native-web etc.

NOTE: Make sure you read the section "When to Insert <style> on The Client". If you currently inject style rules "during render", it could make your library VERY slow in concurrent rendering.

This guide is not for CSS libraries that generate external CSS files ahead of time. See the <link rel="stylesheet" /> guide for that use case. Inlining <style> from pregenerated bulk stylesheets to avoid roundtrips during SSR also falls into that category.

Injecting Into the SSR Stream

Today, you might do something like this to collect all the rules that were generated during the render into one or more <style> tags that gets inlined into the HTML.

let content = renderToString(<App />);
let rules = generateStyleRules();

"<!doctype html><html><head><style>" + rules + "</style></head><body>" + content + "</body>"

This doesn't work for streaming since you won't have all the style tags up front. Instead, you'll need to collect all rules generated up until a certain point and emit them before the corresponding HTML. Then after React has rendered some more, you need to generate new rules.

To insert into the stream at the right timing, you'll need to provide an intermediate stream.

For Node.js that means creating a wrapper Writable.

class MyWritable extends Writable {
  constructor(writable) {
    super();
    this._writable = writable;
  }
  ...
  _write(chunk, encoding, callback) {
    // This should pick up any new link tags that hasn't been previously
    // written to this stream.
    let rules = generateNewStyleRulesSinceLastCall();
    if (rules) {
      // Write it before the HTML to ensure that the CSS is available and
      // blocks display before the HTML that shows it.
      this._writable.write('<style>' + rules + '</style>');      
    }
    // Finally write whatever React tried to write.
    this._writable.write(chunk, encoding, callback);
  }
  flush() {
    if (typeof this._writable.flush === 'function') {
      this._writable.flush();
    }
  }
}

Note that it's important to use a custom Writable instead of a Transform stream to support forwarding of the flush() command, to avoid GZIP buffering.

For a Web Streams, there's no GZIP flushing support anyway. Browser support is a little flaky but the principle is the same. Find a way to inject before whatever React writes.

const injectStyles = new TransformStream({
  transform(chunk, controller) {
    // This should pick up any new link tags that hasn't been previously
    // written to this stream.
    let rules = generateNewStyleRulesSinceLastCall();
    if (rules) {
      // Write it before the HTML to ensure that the CSS is available and
      // blocks display before the HTML that shows it.
      controller.enqueue(textEncoder.encode('<style>' + rules + '</style>'));
    }
    // Finally write whatever React tried to write.
    controller.enqueue(chunk);
  }
});
readable.pipeThrough(injectStyles);

Ensure that you've already written the <!doctype html><html><head> part before writing any style tags. Otherwise the style tags could be written before the doctype which would break the page.

Note: React can write fractional HTML chunks so it's not safe to always inject HTML anywhere in a write call. The above technique relies on the fact that React won't render anything in between writing. We assume that no more link tags will be collected between fractional writes. It is not safe to write things after React since there can be another write call coming after it.

Document Order Precedence

Your generated CSS might have conflicting rules and relies on document order to resolve them. In case case you might want to use a second script that reorders them in the document.

<style id="foo">
...
</style>
<script>
document.querySelector('style').before(document.getElementById('foo'));
</script>

That way you can stream in CSS rules late while still preserving document order. Most rules will hopefully be in the first call. So they're all plain HTML. This is what happens if you delay writing the React content until onAllReady for SEO purposes. So as long as you don't emit the script tag for the first call, you don't have to worry about affecting SEO.

Some CSS-in-JS solutions guarantee that there are no such conflicts and so in those cases you don't need to bother with it. You can just emit the style tag into the stream and leave it behind.

Selective Hydration

A common technique is to scan the document - once - for <style> tags upon hydration. This avoids inserting them again when the component hydrates.

It's not enough to do this only once with streaming selective hydration. Hydration can start early before the stream is complete - so it's possible for new <style> tag to be added by the server before the hydration is done.

Therefore, you need to scan once per ID that you're looking for. If a component is hydrating, it should've been inserted by the server already so you'll find it. If a new component renders and it's not found, then you'll need to add it.

It's possible that you add it on the client and then later the server stream adds the same rule again. You could add something to the inline scripts from the server that looks for an existing rules.

Since the parent that rendered the style can be hydrated first - it's also interactive - and can delete the child before it's hydrated. The typical case would be navigating to a different tab using a tab bar while the first tab is still hydrating. In this case, you would not ever delete this style tag since nothing will unmount.

Because of these two edges, it's possible that you might end up with additional rules hanging around that don't get deleted. Performance wise, this is ok since it's just the initial rules and just in an edge case.

However, if your system allows conflicting rules and relies on one component unmounting before the next one is shown then this could lead to a semantic issue where the old rules hanging around conflict with the new component. We don't really have a solution for this problem. If you're upgrading an existing site, it's probably fine though. Because this only happens once you opt-in to new Suspense features. It also only happens if the page is slow to hydrate fully before the user interacts with it.

That said, we don't recommend building a system where you can rely on conflicting rules being resolved by unmounting a previous component. For example, global rules. It makes it harder to do animations between two states. It's also not good for perf to constantly unmount and remount rules. If you avoid global rules like this, then you avoid a lot of problems like this one.

When to Insert `<style>` on The Client

When generating <style> tags on the client it's important to be aware of a particular performance issue. When you add or remove any CSS rules, you more or less have to reapply all rules that already existed to all nodes that already existed. Not just the changed ones. There are optimizations in browsers but at the end of the day, they don't really avoid this problem. People often have a hard time believing this but it's true, because implementing CSS efficiently comes with a lot of tradeoffs and this isn't one that's optimized for.

You probably won't hit this issue until you have a lot of rules and a lot of DOM nodes, but it scales poorly on even reasonable sized sites.

There are ways to avoid this. The most important is the timing. You want to make sure that you do it as the same time as other changes to the DOM such as when React mutates the DOM and before anything reads from the layout (e.g. clientWidth) and before yielding to the browser for paint.

The other thing you can do to avoid this causing problems is to batch as much of this work as possible.

The worst thing you can do is insert them during React renders. E.g. this is bad:

function css(rule) {
  if (!isInserted.has(rule)) {
    isInserted.add(rule);
    document.head.appendChild(getStyleForRule(rule));
  }
  return rule;
}
function Component() {
  return <div className={css('...')} />
}

Sometimes this can hide between layers of abstractions. Especially if the system is automatic and triggered by a module system, such as require('...').

In concurrent rendering, React can yield to the browser between renders. If you insert a new rule in a component, then React yields, the browser then have to see if those rules would apply to the existing tree. So it recalculates the style rules. Then React renders the next component, and then that component discovers a new rule and it happens again.

This effectively causes a recalculation of all CSS rules against all DOM nodes every frame while React is rendering. This is VERY slow.

This can happen even if you wait to insert the rules in a requestAnimationFrame callback, because the browser can fire these between React yields.

Another issue with doing it in render is that if it yields conflicting rules, they'll start showing up before the content they belong to.

There's a feature in React called getSnapshotBefore update. This triggers before any other mutations are done. This can be used to adjust scroll positions or manage animations etc. It's common for these to read layout. At best this will trigger recomputation of layout twice unnecessarily. E.g. Write in render, Read in snapshot (force layout), Write in React, Read in Layout Effect (force layout 2).

A fix for this is to put the insertion of rules into a useLayoutEffect. That ensures that it's inserted before the content is visible but not too early.

Unfortunately, reading layout and doing a second pass is one of the main use cases for useLayoutEffect.

useLayoutEffect(() => {
  if (ref.current.clientWidth < 100) {
    setCollapsed(true);
  }
});

Imagine you have some components that inserts styles and some components that reads layout. This causes the layout to be computed multiple times in a single pass. Additionally, if one hook tries to read the layout before the CSS has been inserted, it would read the wrong layout.

Therefore we're introducing a new Hook for this use case.

`useInsertionEffect`

useInsertionEffect is new in React 18. It works roughly like useLayoutEffect except you don't have access to refs to DOM nodes at this time.

The use case is specifically for inserting global DOM nodes like <style> or SVG <defs>. (Maybe global Portals.) It's not really meant to be used by anything else other than these CSS libraries.

Therefore the recommended solution is to use this Hook to insert style sheets (or ref count them if you need to remove them):

function useCSS(rule) {
  useInsertionEffect(() => {
    if (!isInserted.has(rule)) {
      isInserted.add(rule);
      document.head.appendChild(getStyleForRule(rule));
    }
  });
  return rule;
}
function Component() {
  let className = useCSS(rule);
  return <div className={className} />;
}

This effect doesn't fire on the server (just like useLayoutEffect). You may need to track the usage of a rule on the server. We recommend doing that with a separate map in render. If you need to, you can also feature test if you're on the server.

function useCSS(rule) {
  if (!canUseDOM) {
    collectedRulesSet.add(rule);
  }
  useInsertionEffect(() => {
    if (!isInserted.has(rule)) {
      isInserted.add(rule);
      document.head.appendChild(getStyleForRule(rule));
    }
  });
  return rule;
}

Future

While this technique for generating CSS is popular today, we've found that it has a number of problems that we'd like to avoid. Therefore we don't have plans for adding any solutions upstream to handle this in React. For the time being, we expect this to have to be handled by third-party libraries such as in this guide.

Our preferred solution is to use <link rel="stylesheet"> for statically extracted styles and plain inline styles for dynamic values. E.g. <div style={{...}}>. You could however build a CSS-in-JS library that extracts static rules into external files using a compiler. That's what we use at Facebook.

It's tempting to use dynamically generated style sheets since it contains only the rules that are active on the page right now. However, this comes at a cost. Usually at the expense of runtime cost. It also comes at a cost of inserting new rules frequently which invalidates a lot of the work that has already been done.

Shared stylesheets are efficient to parse and are very cacheable. By extracting them into shared styles you are also effectively batching a lot of that work up front. This lets you avoid doing that work later on as the user starts interacting with the page.

If you also use techniques like atomic CSS or other per-rule class names (e.g. tailwind), the CSS file sizes tends to plateau and not grow much in size since a lot of parts of a page tend to use similar rules for different components.

Truly dynamic rules can't be done this way but those can use inline styles (<div style={{...}}>). Inline styles doesn't suffer from invalidating the whole page's rules and only applies to the node they're applied to. Unfortunately, the performance of reparsing similar rules means that using only inline styles isn't optimal neither. However, when combined, these two techniques work well.

A possibly strategy that might help minimize these quirks in the future would be to use Shadow DOM to scope the rule invalidation, however, that currently comes with a lot of other downsides so is not a feasible strategy atm IMO.

Andarist · 2021-10-12T08:14:26Z

Andarist
Oct 12, 2021
Collaborator

nit: you have injectLinks in one of the code snippets

q: can useInsertionEffect just be used on the server (acting as noop) without maintainers going through hoops to use this conditionally (like in the case of useLayoutEffect)?

If I understand correctly the server-rendered output with streams can only look roughly like this:

<!DOCTYPE html>
<html>
  <head></head>
  <body>
    <div id="root">
      <style>
        .test {
          color: hotpink;
        }</style
      ><span class="test">Hello CodeSandbox</span>
    </div>
  </body>
</html>

where the point is - in the SSR output the <style> can appear anywhere in the body, interleaving the regular React content.

However, if we just accept this SSR output without any modifications we end up with a hydration mismatch like:

Warning: Did not expect server HTML to contain a <style> in <div>.

At least this is what happens today, a small demo can be found here: https://codesandbox.io/s/interesting-forest-wrm9b

It seems that this problem has not been addressed anyhow in the given implementation recommendations - unless I've missed it. At the moment, in Emotion, we do this hacky thing:
https://github.com/emotion-js/emotion/blob/685bbec099372b6797a7d2cfb558756faeee4f19/packages/cache/src/index.js#L97-L115

It happens roughly during the initialization of the consuming module. I understand that this is not ideal and doesn't work correctly with selective hydration - I'm mentioning this for completeness and to mention this additional problem that we are facing.

It seems that there is no good point in time in which we could manipulate the SSR html to move things out of React way. I guess we could try to experiment with emitting <style/>+<script/> but such an approach is only mentioned in the "Document Order Precedence" section while it seems to be required for more than that. We'd also have to "cleanup" both style and script before React sees them - and you only suggest to move the style in the mentioned code snippet.

8 replies

sebmarkbage Oct 12, 2021
Maintainer Author

useOpaqueIdentifier doesn’t really help you here. It really only kicks in when you need to render the same thing on the client again.

If you clean up from within the script tag you know the id that you emitted from within the tag. You can just use your own scheme for that since the client will never see it.

If you do it from the client, you need to listen to insertions use querySelectorAll. You can use some unique pattern and delete all of those.

Fwiw, React doesn’t bother removing the script tags. We just let them remain. It’s not expected to be that many and inserting more scripts slightly delays the next content. We might change this in the future and use currentScript tho.

Andarist Oct 12, 2021
Collaborator

Thank you for the explanation! It has helped me to build a better picture of how this works.

One slight problem with this is that our current solution doesn't require any setup on the user part. They can just consume any Emotion-based component from npm and it should "just work" (for the most part). With what we have here - the user has to be aware of the underlying library and they have to integrate with the stream transform that it exposes. I don't see how this could be fixed though with the proposed APIs - so I guess we should stop marketing our SSR solution as zero-config because it will stop being zero-config with React 18.

I see how the proposed APIs are more flexible and they probably allow for more cases to be handled using the same pattern but it's shifting some of the burden on the consumers (they need to configure library plumbing on their own).

sebmarkbage Oct 12, 2021
Maintainer Author

You might be able to come up with something clever. Like rendering the style tags with react and then moving them before react gets to them.

The way I see it is that you take a certain performance penalty for using this technique anyway. So you can probably get away with a slower implementation for that case.

I had an idea for how we could support rendering style tags anywhere in React built-in but in the end it made us uncomfortable to add the runtime complexity to react for everyone to pay that cost even though it’s not best for perf.

Andarist Oct 12, 2021
Collaborator

You might be able to come up with something clever. Like rendering the style tags with react and then moving them before react gets to them.

Right - this is basically what we are doing right now. I'm unsure though how we can do this with selective hydration as there is no clear signal for us to query the DOM for those newly arrived style elements. Maybe a MutationObserver would do the trick but I'm somewhat hesitant to trust the timing of its callbacks 🤔

I had an idea for how we could support rendering style tags anywhere in React built-in but in the end, it made us uncomfortable to add the runtime complexity to react for everyone to pay that cost even though it’s not best for perf.

That's an understandable stance to take 👍

sebmarkbage Oct 12, 2021
Maintainer Author

The signal you can use is by calling some method from a script tag that you insert.

return <>
<style id=“a”></style>
<script id=“b”>move(“a”); remove(“b”);</script>
</>;

This script will always execute right after inserting the style so nothing else can observe it. Including React.

(Although keep in mind that with Trusted Types, this might end up needing some configuration from the user if they already had those on.)

Andarist · 2021-10-24T20:22:39Z

Andarist
Oct 24, 2021
Collaborator

This effect doesn't fire on the server (just like useLayoutEffect). You may need to track the usage of a rule on the server. We recommend doing that with a separate map in render. If you need to, you can also feature test if you're on the server.

Is collectedRulesSet meant to showcase how to implement the mentioned "separate map in render"? Is generateNewStyleRulesSinceLastCall from the example supposed to check the content of a chunk, scan for class= and grab rules from that "global" map? Is the expectation here that such a global map shouldn't be a memory concern because the generated amount of rules should "plateau" over time?

useInsertionEffect is new in React 18. It works roughly like useLayoutEffect except you don't have access to refs to DOM nodes at this time.

It indeed works like useLayoutEffect when it comes to the execution order of those new hooks within the tree. The order is bottom-> up: https://codesandbox.io/s/awesome-brown-2ncv7?file=/src/App.js

This changes the injection order for most of the current CSS-in-JS libraries because most of them inject in render and that happens in the top->down order. This means that, most likely, this won't be a smooth migration for a lot of applications and that we can't feature-detect the new hook to use it when it's available. This requires a major version of a CSS-in-JS library.

This is problematic because the injection order might affect what rules are applied through descendant selectors etc. I'm personally not a fan of those and I'm against using them but people tend to use them and a lot of CSS-in-JS libraries allow those to be used.

4 replies

sebmarkbage Oct 25, 2021
Maintainer Author

Is collectedRulesSet meant to showcase how to implement the mentioned "separate map in render"?

Yea.

Is generateNewStyleRulesSinceLastCall from the example supposed to check the content of a chunk, scan for class= and grab rules from that "global" map?

No, no need to scan the chunk. Just grab all the rules that was added since last call. In practice you might want to add them to a set which ones have been seen before and an array of ones that still need to be written. Then you clear the array each time.

Is the expectation here that such a global map shouldn't be a memory concern because the generated amount of rules should "plateau" over time?

It could use a Context or whatever you do currently to track these things.

sebmarkbage Oct 25, 2021
Maintainer Author

This is problematic because the injection order might affect what rules are applied through descendant selectors etc.

For backwards compat you can add them to a temporary global array in render and insert them in the document in the first useInsertEffect.

That said, once you start suspending in render methods the render order can change. When React tries the next sibling and then back to the previous sibling again. So the render order isn’t reliable anyway.

Once you add conditional rendering (such as suspense boundaries) this order gets somewhat unpredictable regardless.

Some libraries use precedence “categories”. But really the best is to enforce a system where this order doesn’t matter.

Andarist Oct 26, 2021
Collaborator

It could use a Context or whatever you do currently to track these things.

Hm, OK - so the solution here is to create a per-request context value, provide that throughout the tree and use that provided value in the stream transformer. So the stream transformer has to also be created per request, to use the same "instance"/closure values there. Is that correct?

For backwards compat you can add them to a temporary global array in render and insert them in the document in the first useInsertEffect.

Thank you for the suggestion, it makes sense - although, obviously, it complicates things a little bit for us. We'll be giving the whole implementation on our side more thought next Tuesday. But so far it looks like we should be able to migrate to this somewhat easily - we need to get creative about our 0-config approach though or ditch it and require manual setup from our users.

Some libraries use precedence “categories”. But really the best is to enforce a system where this order doesn’t matter.

Totally agree 👍 This is a heavy footgun with most of the current, popular, CSS-in-JS libraries - people usually don't realize this though as it's not pointed out enough as a tradeoff anywhere.

That being said - there are, unfortunately, a lot of applications relying on this at the moment. So being conservative about this (trying to preserve the top->down order) can help them migrate more gradually, at their own pace. The tradeoff here is that they will suffer from the injection order issues without realizing that they are there - as this is often hard to test against and verify.

sebmarkbage Oct 26, 2021
Maintainer Author

One tricky I learned from react-helmet, is that you can simulate top-down order if you insert a previous sibling.

E.g. since most existing libraries that are affected by this uses wrapper components and not hooks, they can insert previous siblings that does the insertion.

function StyleSheet({ id }) {
  useInsertionEffect(() => {
     if (notInserted(id)) {
       document.head.appendChild(prepareStyleNode(id));
     }
  });
  return null;
}
function MyStyle({ style, children }) {
  return <>
    <StyleSheet id={prepareStyle(style)} />
    {children}
  </>;
}

That's a bit more resilient than doing it in render since it'll be in order of commits.

sophiebits · 2021-10-25T21:29:17Z

sophiebits
Oct 25, 2021
Collaborator

If style tags end up interspersed at random-ish points within a stream, might you inadvertently remove rules in use if you unmount a component that is an (incidental) ancestor of one of the style tags?

1 reply

sebmarkbage Oct 25, 2021
Maintainer Author

No, not if used as instructed because you end up between React writes and React only yields once it has written all the way back to the root.

The exception to this, atm, is that the first write is a little tricky to get right since it likely should go into the head but if you stream it to the middle of the page it can end up in the beginning of the container node and then it gets deleted when it’s hydrated. So you have to figure out that.

Library Upgrade Guide: <style> (most CSS-in-JS libs) #110

Uh oh!

Uh oh!

sebmarkbage Oct 12, 2021 Maintainer

Library Upgrade Guide: <style>

Injecting Into the SSR Stream

Document Order Precedence

Selective Hydration

When to Insert <style> on The Client

useInsertionEffect

Future

Replies: 3 comments · 13 replies

Uh oh!

Uh oh!

Andarist Oct 12, 2021 Collaborator

Uh oh!

sebmarkbage Oct 12, 2021 Maintainer Author

Uh oh!

Andarist Oct 12, 2021 Collaborator

Uh oh!

Uh oh!

sebmarkbage Oct 12, 2021 Maintainer Author

Uh oh!

Andarist Oct 12, 2021 Collaborator

Uh oh!

Uh oh!

sebmarkbage Oct 12, 2021 Maintainer Author

Uh oh!

Andarist Oct 24, 2021 Collaborator

Uh oh!

sebmarkbage Oct 25, 2021 Maintainer Author

Uh oh!

Uh oh!

sebmarkbage Oct 25, 2021 Maintainer Author

Uh oh!

Andarist Oct 26, 2021 Collaborator

Uh oh!

Uh oh!

sebmarkbage Oct 26, 2021 Maintainer Author

Uh oh!

sophiebits Oct 25, 2021 Collaborator

Uh oh!

sebmarkbage Oct 25, 2021 Maintainer Author

sebmarkbage
Oct 12, 2021
Maintainer

Library Upgrade Guide: `<style>`

When to Insert `<style>` on The Client

`useInsertionEffect`

Replies: 3 comments 13 replies

Andarist
Oct 12, 2021
Collaborator

sebmarkbage Oct 12, 2021
Maintainer Author

Andarist Oct 12, 2021
Collaborator

sebmarkbage Oct 12, 2021
Maintainer Author

Andarist Oct 12, 2021
Collaborator

sebmarkbage Oct 12, 2021
Maintainer Author

Andarist
Oct 24, 2021
Collaborator

sebmarkbage Oct 25, 2021
Maintainer Author

sebmarkbage Oct 25, 2021
Maintainer Author

Andarist Oct 26, 2021
Collaborator

sebmarkbage Oct 26, 2021
Maintainer Author

sophiebits
Oct 25, 2021
Collaborator

sebmarkbage Oct 25, 2021
Maintainer Author