Built in support for CSS bundling.

[nicksrandall]

Intro

In order to give myself a little credibility, and to give context on where my opinions are coming from, allow me to give a brief introduction to myself. For the past several years, I've been a Tech Lead at Bloomberg LP and in that time I've managed many large scale, web based applications with millions of users and large-ish teams (15+ persons) working on them

Problem

Remix does not have great support for co-locating a component's styles along with the rest of the component (or writing component styles in isolation). The exercise is left up to the developer. This is problematic (especially in large code bases) because Remix encourages creating stylesheets based on the route so, as a developer, you need to remember every route that uses your component when you'd like to make a change to the components styles. Alternatively, you have to include everything in a single global stylesheet which is also not ideal for "network-tab" reasons.

There are some solutions to this problem in the Remix community but each has their own downsides. (BTW, I'm not against any of these solutions, I'd just like to provide an alternative solution with different trade offs).

Tailwind

Tailwind allows you to use their composable classes to co-locate styles with components. There are two major down sides to this approach:

1. you have to learn a new DSL(ish) api to use it.
2. No route based code splitting -- the recommended approach is to drop the large generated css file into the root route so that is gets loaded on every single page.

CSS-IN-JS

Many solutions exist that allow you to author styles directly in JavaScript, alongside the component. This approach also has downsides:

1. Sometimes requires a complex build step (like a babel plugin that Remix does no support)
2. You have to download a JS runtime in addition to the styles themselves so the bundle size is increased.
3. Popular solutions do not (yet) work with Edge computing platforms like Cloudflare workers.
4. SSR usually involves "double rendering" which is wasteful.

Solution

Remix should support importing css files directly in components and routes. Then, during the build process, a single, bundled CSS file should built for each route and automatically added to the page via a link tag.

What about cool things like adding the media="..." attribute to link tags?

This is still possible. I'm imagining a process where after the route's css file is generated, we do one final processing step on it and extract all the media queries used in the file. We can then split the file into several files based on the media queries and add each one to the page with a <Link media="..." />. (I have a prototype of this already working, so it's definitely doable).

What should happen to the existing links api?

I think it should still exist for adding other types of links to the page (including stylesheets that are hosted somewhere else).

Bonus: CSS Modules (not CSS module scripts)

Once basic support for CSS is implemented, it would be trivial to also include opt-in support for css-modules. The benefit of this approach is that all css selector names are mangled for uniqueness and then exported to the javascript with their original name so that developers get a really nice developer experience, they never have to worry about clashing styles, and there would be no performance cost to the end user.

Final thoughts

While not production ready (yet), I have a fully working prototype of this working in Remix. The biggest downside to this is that it would be a breaking change. Interestingly, I believe most apps would continue to work, unmodified after an upgrade because they were importing the css anyway so the css will still end up on the page. The only thing to migrate would be removing the now empty items from the existing links() function.

[hollandThomas]

I like the general idea. I had similar ideas before, especially regarding the split into media="..." files. Some lose thoughts:

Duplicated CSS

What happens to the colocated CSS of components used throughout the entire app, particularly across multiple distinct routes? This will inevitably happen, especially in design-system focused projects where you have your Buttons, Inputs, Selects, ... reused multiple times.

1. Duplicate those styles in each route's CSS-file
   This is the proposed solution. It's easy but suboptimal. It would lead to a couple of unnecessary, duplicated bytes over the wire, and maybe most importantly: we cannot make use of HTTP caching across routes to mitigate this problem.
2. Identify "common" CSS
   This would require to have some smart, compiler-like behavior baked into Remix (good thing it already describes itself as a compiler). Have it figure out during the build process which parts of your CSS is reused, then put it in its own CSS-file common.css that will be used by each route (and can be cached by the browser). Additionally, load the styles unique to each route in a separate file.

As an aside, you can get pretty wild with this of course. Surely, not all of the common CSS will be used by the initial route, making the initial hit still load "too much" CSS. So, one could identify the common CSS used by the initial route and have it load only that at first, then defer loading all the common CSS once the page is interactive. Once the entire common CSS is loaded and cached, make sure that no more "initial common CSS" will be requested on subsequent route visits. Also, "initial route" is not necessarily / of course but any URL the user can put into their address bar, making Remix have to do this whole shebang for each top-level route.
In the end, I'm not sure if such a behavior would yield enough upside for how relatively complex it would be.

All in all, option 2 seems tricky to implement, when thought through. But it might be possible!

Interop with Tailwind, CSS-in-JS, ...

Ideally, these things would be solution-agnostic. As long as the solution in question can output a precompiled CSS file and can be statically analyzed (like Tailwind or vanilla-extract), this should be theoretically possible.

[nicksrandall]

You bring up some really good points but I think the issues you mention are already something that Remix needs to solve (even without my proposed changes). For example, the duplicated code problem already exists for each component's JS code that lives on multiple routes.

Creating a smart "common" chunk would solve this problem for both CSS and JS code.

FWIW, I consider chunk optimization out of scope for this specific proposal but since we're talking about it, I have a few ideas. At first, I think a simple heuristic like if this component lives on 3 or more routes then we move it to a "common" chunk that gets imported on all pages (IE the root route) would get us pretty far. Another option that could be more flexible would be to allow users to annotate their imports with query strings that would provide hints to the compiler on if it should be imported as a common chunk so if you wrote something like `import Button from "@design-system/button?common" then the compiler would automatically list that import as needing to go into the common chunk. There is a lot that can be done in this space but those are some simple options.

[mjackson]

The duplicated CSS and caching problems can already be avoided easily by using a separate stylesheet for shared CSS and using a separate <link> to include it in your route.

[hollandThomas]

Sure but wouldn't that require manual work?

Assuming we wanted to colocate styles with components (via .css files per component, CSS Modules, Tailwind, vanilla-extract, ...), there is no obvious way of generating a stylesheet for any given route that only includes the styles for all the components of that route, let alone identifying common styles among all the routes.

What's more, "using a separate stylesheet for shared CSS" assumes that developers maintain their own common-stylesheet, right? With the above colocation-approach, that would not be the case.

The initial proposal suggests that Remix handles the generation of separate stylesheets per route:

Then, during the build process, a single, bundled CSS file should built for each route and automatically added to the page via a link tag

The essential idea is to hand colocated CSS to Remix and have Remix figure out how to generate optimized CSS chunks (that includes splitting per route, splitting into common chunks, ...) that are added to the respective pages via <link> automatically without the developer having to think about it. Because at scale, I'm not so sure how easy it is to maintain separate files by hand.

I think that'd be a killer feature :)

[nicksrandall]

The duplicated CSS and caching problems can already be avoided easily by using a separate stylesheet for shared CSS and using a separate <link> to include it in your route.

This is still possible with this proposal -- if you have some common css you can just import it in the root route and it will get included on all pages.

I don't want this proposal to run off course taking about automatic chunk optimizations. Perhaps we should open a separate discussion to discuss that?

[hollandThomas]

Yeah sorry I did not want to crash your proposal. Just wanted to give my 2 cents since the topics are roughly connected

[nicksrandall]

UPDATE: I had a conversation with Michael, Ryan, and Kent and they agreed that supporting CSS Modules would be worthwhile for Remix and they plan to support it in some future release. There was also discussion around supporting "bare" css imports and they are going to explore that a bit further before committing to supporting it.

[hollandThomas]

FYI, I started a discussion over at Tailwind that introduces the idea of splitting generated CSS files per media

tailwindlabs/tailwindcss#6904

[tvanantwerp]

If I hadn't found this discussion just now, I was ready to create it. I've just started work translating a Next app with CSS Modules + Tailwind directives co-located with components into a Remix app, and I've been struggling to find a good way to keep styles together with components. It just creates so much less mental overhead for me when styles are alongside their components in the file structure, and I can have local scoping of those styles without having to think about it.

[ryanflorence]

Thanks for writing this up Nick, and thanks for taking the time to meet with us. We will be expanding the feature set around importing CSS files motivated by:

• The ability for React (and React Router) apps that use CSS Modules to adopt Remix
• Better DX around component/module styles

We are going to be adding some sort of support for right away for:

• Bare CSS imports
• CSS Modules

And at some point in the future we're thinking about adding direct support for:

• Vanilla Extract
• Tailwind

Of course, how things pan out once you get into implementation can always change your plan! But CSS Modules are very important for migration from React Router apps.

These features would be behind an unstable feature flags in remix.config.js enabled with something like:

// remix.config.js
module.exports {
  // ...
  unstable_cssImports: true,
  unstable_cssModules: true,
  unstable_tailwind: true,
  unstable_vanillaExtract: true
}

Bare CSS Imports

You'd be able to import css files directly into modules.

/* app/components/button.css */
.btn {
  background: blue;
}

// app/components/button.jsx
import "./button.css";

export function Button() {
  return <button className="btn" />;
}

// app/routes/index.jsx
import { Button } from "~/components/button";

export function Button() {
  return (
    <div>
      <h1>Index</h1>
      <Button />
    </div>
  );
}

Remix can automatically include the button.css file when it is in the import graph of routes that are active. No need to add them to the links export of the route component.

Because the module graph can change, the order the CSS files are included is unpredictable (or at least difficult to control), you'll need to be careful will CSS selectors. Because of that, it makes sense to add direct support for CSS modules to avoid the issue entirely.

CSS Modules

Remix could support CSS Modules directly. Files named *.module.css would be interpreted as css modules.

/* app/components/button.module.css */
.btn {
  background: blue;
}

// app/components/button.jsx
import { btn } from "./button.module.css";

export function Button() {
  return <button className={btn} />;
}

Remix would automatically include the button.css file when it is in the import graph of routes that are active. No need to add them to the links export of the route component.

Vanilla Extract

Note, we don't have this in our road map right now, just thinking about it

Vanilla extract provides a first-class CSS-in-JS developer experience, with the ability to use TypeScript to create CSS abstractions and definitions without the runtime costs of other CSS-in-JS approaches. Since it produces actual stylesheets that can be generated statically with no browser runtime, it's a great fit for Remix. Stylesheets can be cached, preloaded, and prefetched like other assets.

Name your files *.css.ts and they could be processed by vanilla extract. Remix could automatically include the generated stylesheets when they are in the import graph of routes that are active.

Tailwind

Note, we don't have this in our road map right now, just thinking about it

Remix could support Tailwind CSS directly. Simply add a tailwind.config.js file to your project and Remix could take care of the rest. It could use the tailwind standalone binary to generate the css file that will be automatically included with the <Links/> component.

Notes

One import equals one CSS file

There is no automatic concatenation or splitting involved. Some CSS bundling techniques will try to add all css imports in a module graph into a single CSS file. We could generate a CSS file for each route, but then there will be a lot of duplication across routes. Attempts at splitting and deduping can also lead to incorrect CSS rule ordering and UI bugs. Additionally, these files can become enormous. Remix will not be attempting to do this. One import equals one CSS file.

This is also in alignment with the proposed import assertions where likewise one import equals one file, no concatenation, splitting, etc. At some future day, we'll likely change all of this to import assertions instead of file name conventions.

But again, as you get into the weeds, perhaps we will change our thoughts here and just concat it all together.

Large Number of Requests

In the case of component CSS, this means a page that imports a lot of components will load a whole bunch of small stylesheets. While it's better to load 3 10kB files than 30 1kB files, the combination of Remix's resource prefetching/parallel loading and HTTP/2/3, in general, should avoid impacting the UX.

Of course, if you determine it is impacting UX, applications have complete control over the CSS files being loaded. The solution would be to categorize your CSS and define your rules together in fewer, but larger CSS files. Apps are in control of the UX/DX tradeoff (lose localization of styles, but gain fewer network requests). Instead of primary-button.css and button-link.css and submit-button.css, you can define all of those styles in button.css, turning three small requests into one larger request. All button components will share that css file w/o duplicating any CSS.

CSS Ordering

When Remix includes the CSS from css imports and your links exports, the question comes up regarding ordering. At the moment, we think that the right approach is to include CSS in the module graph first, and then the css from the route links exports. This way your rules in "app/components/button.css" can be overridden by a route. Because routes know their imports and buttons don't know their routes, this seems like the right approach.

However, we'd like to hear if you anticipate the need for css in the module graph to need to override the css in the route links export. If there are solid use cases, we have some ideas on how give apps control of the ordering.

Thanks again, we're really excited to get to work on this stuff!

[sergiodxa]

This with import assertions will be really cool

[hollandThomas]

Thanks for this, sounds promising 👍

Regarding

Attempts at splitting and deduping can also lead to incorrect CSS rule ordering and UI bugs. Additionally, these files can become enormous. Remix will not be attempting to do this. One import equals one CSS file.

Agreed, it sounds like a hard thing to really get right. Facebook has some ideas here with Stylex's design decision to utilise Atomic Styles (more in this video of a talk at React Finland last year).

Essentially, they take some class

.position-abs {
  position: absolute;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  transform: scale(0.97, 0.97);
}

and transform it into

.position-abs { position: absolute; }
.top-0 { top: 0; }
.left-0 { left: 0; }
.right-0 { right: 0; }
.bottom-0 { bottom: 0; }
.transform-097 {
  transform: scale(0.97, 0.97);
}

which actually is a pretty well performing strategy (at least at scale), as demonstrated later in the talk.

I wonder if Remix is in a unique position to do something similar, without having to subscribe to one particular CSS-in-JS solution (like Stylex). That would be a deal breaker I think. Basically, have Remix transform any given CSS to atomic styles and have it rewrite any occurences of className strings to their atomic equivalent. Admittedly, that last part sounds hard to implement correctly, especially when thinking about dynamically generated strings. However, it might be feasible?

In any case, it's probably the right call not to attempt it right now since it's not super important. Just one possible path Remix could take when thinking of it as a compiler.

[ryanflorence]

Whether devs write atomic CSS, or tools compile to atomic CSS, it is certainly the best approach for delivering CSS. It eventually caps out in size no matter how much UI you have (which is why I personally use tailwind for everything and consider the entire CSS landscape solved, for me anyway!)

[where-picturesque]

Hi @ryanflorence .Does this feature work? It seems not work yet

[nicksrandall]

@ryanflorence I like everything you've said but there is one bit that I'm confused about.. "One import equals one CSS file".

This feels wrong. We should be treating component level css files in the exact same way we handle component level JS files. If you have a page with 80 components, are we adding 80 script tags to the page? If I remember correctly, we are generating a JS bundle per route. Sure, if components exists on several routes then technically those components JS code would be duplicated across the bundles.

We should be handling the CSS in the exact same way -- generating a bundle per route.

Eventually, it would probably make sense for Remix to add in some smart deduplication techniques (like a commons chunk) but, again, we should be treating CSS in the exact same way so if we someday have a "common" js chunk then we should have a "common" css chunk.

[ryanflorence]

Sorry, last thought here. If we find that too many CSS files is a serious problem, I think in the future we can take the same approach as esbuild (concat all css for an entry) but then remove duplicate styles from child routes that are in parent routes before writing the files (since we know the hierarchy at build time the css ordering is known).

This would break compatibility with import assertions though.

Just wanted to say that "bundling/splitting/concatting/deduping" CSS is not completely off the table, but just that it's really freaking hard, error prone, and maybe doesn't matter for performance. I want to start simple (and compatible with import assertions) and then evaluate.

[nicksrandall]

@ryanflorence I understand the CSS ordering issue which is why I thought we had settled on CSS modules (or vanilla extract, or any anything that can mangle class names in a transparent way) so that it no longer becomes an issue because styles are guaranteed to be unique.

That said, I absolutely understand that this not a trivial thing to solve and I sincerely appreciate your willingness to think through all the issues. I'm sure whatever you eventually land on will be great.

[shamsup]

I think the importance of the developer being in control of how the CSS files are bundled can't be overstated, and I think that automatic concatenation/bundling would undermine that. I think this approach aligns really well to what remix has done so far for developers, which is to have strong opinions where it matters, but make them "easy", then cede control to the developer for the other things.

[dangerousdan]

With a common chunk, would you also have to take React.Lazy / dynamic imports into consideration?

Right now we're developing CMS driven sites for clients, which allow the user to publish blocks of content. The react looks roughly like this

import * as blocks from '#blocks'

export default function BlocksContent(props) {
  if (!props.blocks) return null

  return (
    <>
      {props.blocks.map((block, i) => {
        const { __component, ...props } = block
        let Block = blocks[__component] || null
        return <Block key={i} {...props} />
      })}
    </>
  )
}

Right now, we bundle everything into a single stylesheet (24kb, it's not so bad). A site might also contain similar pages (eg. a product collections page, and a product search results page) which would also result in even more content being pushed into a common chunk. It could be quite common for a common chunk to be the vast majority of the site.

My 2 cents would be to consider a simple bundle + chunk as an easy solution if too many scripts are a problem / deterrent. It's not as optimal, but it's no worse than any other existing solution and still takes advantage of http2 / prefetching and would also be a big step towards adoption (it's easy to add postcss / sass as per the docs, css-module names is the awkward part).

[mikkpokk]

@ryanflorence I'll give my vote to css-modules code splitting. I have 2 projects written in Remix. Both have grown to quite a large projects already, where "All in 1" bundled CSS causing problems already (blocking FCP for an example over 400ms on average device). Bundled CSS cannot be deferred, it will cause huge CLS otherwise. Both are big problems for UX and Google UX & speed rating.

It is possible to split CSS (using css-modules) with lazy loading on simple CRA with react-router. It should be standard in Remix too.

[maksimsemenov]

What is the status of CSS support? I'm looking at the Remix, and current solution for styling does not look very inviting (a lot of boilerplate and cognitive load). Are there any plans to implement support for bare CSS imports and CSS modules?

[electroheadfx]

it will be updated from here: #2214 (with vanilla-extract)

[osdiab]

Just want to register that whatever happens, it would be a bummer if it requires managing the link tags manually. I know that it does provide the greatest amount of control on how CSS is prefetched and what not, but this seems like the kind of thing that a sensible default ought to be able to handle. Having to export links from each component and then splat them on every route that uses them is just very easy to forget and extra boilerplate that I don't want to subject my team to. The extra coupling makes it harder to do refactors and I want that to "just work". Thanks for the movement here @ryanflorence !

[KingSora]

Good day!
I'm a bit late to the party but some thought from me:

Remix should support importing css files directly in components and routes. Then, during the build process, a single, bundled CSS file should built for each route and automatically added to the page via a link tag.

I think this will result in undesired behavior. I'm always having this picture in my head where I have two routes which share many components. With your proposal the routes have two separate stylesheets, but with almost identical content. This is bad because shared styles aren't cached but only the whole stylesheet per route is.

I personally think remix should rely on its surfacing styles strategy: https://remix.run/docs/en/v1/guides/styling#surfacing-styles only the way of how this is done should be different, because the current way is very verbose. I've written my own proposal of how this problem shoud be solved here: #4191

[mikkpokk]

I really hope this discussion is not dead. Since the discussion have started, there has been many improvements released long time ago, including css-modules 🎉.

However, developers, who use css-modules, still partialy hang on the ceiling. As many users of css-modules felt already, I'm talking about code splitting..

Missing ability to split css-modules files in large project causes longer FCP and LCP times (long blocking time in general). It means poor UX and poor performance experience for large apps built on top of the Remix which use css-modules approach

Splitting css-modules is available on most popular javascript SSR frameworks: CRA (using React.lazy - not SSR), Next.js, Gatsby, Nuxt, ...

...except Remix

This is how Next.js have solved it:

CSS Modules are an optional feature and are only enabled for files with the .module.css extension. Regular stylesheets and global CSS files are still supported.

In production, all CSS Module files will be automatically concatenated into many minified and code-split .css files. These .css files represent hot execution paths in your application, ensuring the minimal amount of CSS is loaded for your application to paint.

My question is, why Remix have decided not to apply the possibility by today?

[sergiodxa]

With the change to use Vite as compiler, everything related to CSS bundling should move to Vite itself instead of Remix, so you could customize your CSS Modules bundling however you want there.

[sergiodxa]

My question is, why Remix have decided not to apply the possibility by today?

Related to this, as far as I remember, the reason was because Remix needs to include links manually, if you wanted a single CSS file per CSS Module file, you would need to manually load the CSS file URL in the links function.

Again, with Vite, this should be solved since Vite can inject CSS files into the directly AFAIK.