Runtime CSS Modules #4542

ryanflorence · 2022-10-19T03:02:25Z

ryanflorence
Oct 19, 2022
Maintainer

CSS Modules in Remix

The idea here is a way to support CSS Modules without screwing around with bundlers. Everything happens at runtime.

Setup

First, add a resource route to handle css modules from the browser:

import { cssModulesRoute } from "@remix-run/css-modules";

export default {
  routes(defineRoutes) {
    defineRoutes(route => {
      route("/_css/*", cssModulesRoute());
    });
  },
};

Next create a CSS module function to use in your loaders with the same path:

import { createCssModules } from "@remix-run/css-modules";
export const css = createCssModules("_css/*");

Now you're ready to use them:

Using CSS Modules

Define a CSS module.

.navbar {
  color: red;
}

.navLink {
  background: gray;
}

Use it in a route with your newly created css function:

import baseStyles from "./base.css";
import { css } from "~/css-modules";

export function loader() {
  // Use it in your loader and return its values
  let { links, styles } = css("./root.module.css");
  return { links, styles };
}

// Add the css links to your `links` export:
export function links({ data: { links } }) {
  return [
    {
      rel: "stylesheet",
      href: baseStyles,
    },
    ...links,
  ];
}

export default function Root() {
  // And read the styles from your loader:
  let { styles } = useLoaderData();
  return (
    <html>
      <head>
        <Meta />
        <Links />
      </head>
      <body>
        {/* use them! */}
        <nav className={styles.navbar}>
          <NavLink className={styles.navLink} />
        </nav>
        <Outlet />
      </body>
    </html>
  );
}

That seems like a lot of work!

It's definitely more steps than you're used to with css modules but there are a couple things we like about it:

You know how your CSS is applied, no magic bundlers, just reading from the file system
All other CSS Module implementations we've seen concat everything into a single file for the entire app. With Remix CSS Modules, users only download the CSS the page needs!
It follows the same workflow as nearly every other task in Remix: do work serverside in your loader, access the values in your components with useLoaderData.

How it works

`createCssModules`

The point of this is to generate class names for the server render, not produce the actual CSS asset.

The function this creates (we called it css in the code above), does the following things:

generates hrefs for file passed to it and any @imports with fingerprints (no concatting)
returns those hrefs in an array of {links}.
returns the class names from all those files in {styles}

Resource Route

The point of the resource route is to actually serve the asset.

Receives a request like /_css/root.module.css
Converts the file to a CSS module asset file
- does not follow imports or concat anything, imported files will be requested from the other links
Returns the stylesheet with content-type text/css

Questions

Caching Perf

we should be able to fingerprint the hrefs based on content so the URLs are actually /_css/root.module-[hash].css, split it at - and read the file on disk in the resource route, then sent immutable cache headers.
This will keep the origin from getting too many requests for the resource route, but note it doesn't do anything for the runtime in the loaders to generate the styles object.

Runtime Perf

Since we aren't processing the css of the entire app, performance might be acceptable.
If we need better perf, we can take a cache and read/write to it (and make the cache pluggable so you can use in-memory, file system, redis, whatever) createCssModules(routePath, cache)

Hurdles

We need to be able to pass data to links again
Netlify/Vercel take some extra config to be able to ship the source code instead of just some build output.
Netlify/Vercel don't have an obvious caching mechanism. (Fly and friends we can use LRUCache, CF we can use KV storage)

Related to #2214

sergiodxa · 2022-11-03T22:24:09Z

sergiodxa
Nov 3, 2022
Maintainer

generates hrefs for file passed to it and any @imports with fingerprints (no concatting)

Are imports going to be left untouched? So the main CSS file is going to have the @imports in the code but thanks to the <link> tags it can avoid any waterfall loading?

0 replies

sergiodxa · 2022-11-03T22:24:20Z

sergiodxa
Nov 3, 2022
Maintainer

We need to be able to pass data to links again

This would make <Link prefetch> don't be able to prefetch links, correct?

What if, like Remix Utils, there's a LinksFunction and a DynamicLinksFunction? The first is for static links, the second for links that requires data, the first are prefetched, the dynamic links are not prefetched.

This would also let devs use the loader data to dynamically add link tags while still having prefetching for other links.

0 replies

sergiodxa · 2022-11-03T22:24:31Z

sergiodxa
Nov 3, 2022
Maintainer

The setup step seems like something that could be a config instead.

module.exports = {
  cssModules: true
}

If the idea is to let devs choose the path used for CSS modules it could be an option too

module.exports = {
  cssModules: "/_css/*"
}

Then for the css function it could be imported directly from the runtime packages

import { css } from "@remix-run/node"
import { css } from "@remix-run/cloudflare"
import { css } from "@remix-run/deno"

The css function could be configured to use the default /_css/* or the value from remix.config.js.

0 replies

penx · 2022-11-08T00:51:51Z

penx
Nov 8, 2022

This approach makes sense and I'm keen to see CSS Modules support in Remix.

It would be great to have a way to distribute React components and associated CSS modules, e.g. on npm, in a way that is compatible with Remix and other frameworks. At the moment, distribution of scoped styles as part of a package seems to be an area that runtime CSSinJS still does well at, and it would be good to see some static options that are compatible across frameworks.

I created https://github.com/govuk-react/govuk-react which uses runtime CSSinJS, and made some progress on moving towards CSS modules a few years ago in an experimental replacement.

I was hoping CSS modules support would eventually converge 😄

My understanding of the approach described here is that would not be possible? Or could this could somehow be extended to also support CSS module imports in node_modules?

8 replies

penx Nov 10, 2022

I think another option would be to do the CSS module processing in the design systems library before being published, so that in node_modules/@company/ds you have React components that

import "./styles.css"; // already hashed
import classNames from "./styles.json"; // lookup between names and hashes

...then set up Remix to bundle that, which I think is currently possible with serverDependenciesToBundle.

This doesn't work if @company/ds has some CSS in a peerDependency (which would be the case for govuk-frontend-react, if I move forwards with it), but I admit that may be a pretty niche use case.

penx Nov 10, 2022

@sergiodxa in your example, would you then need to pass the class names from your loader down to every use of Button?

wingleung Nov 10, 2022

@penx I like the thinking but you would still need to either

define your dependencies twice (in your remix app and in the config or somewhere else)
process the @company/ds components in the remix bundler

so if we would need to process it through a bundler anyway we might as well look into the developer friendly way by automatically bundling the css files, utilising the bundlers' dependency traversal which would mean remix needs to do it or allow third party bundle loaders (remix-css-modules-loader )

I'm also not sure exposing the lookup hashes in a library is a standard, if not, we would demand devs to change the way libraries with css modules are built. might be a discussion for https://github.com/css-modules/css-modules

fyi, we're using our remix app in a monorepo together with our design system where we can just import from source instead of publishing an npm package. we could still publish the ds if we want but we have no need for it because of how smart monorepos work nowadays (turborepo).

sergiodxa Nov 10, 2022
Maintainer

@penx yes, you will have to pass the class names generated by the css module to the components.

Another option is that the design system process the css modules, generates the classes used in the components and then it ships the CSS with the classes already generated, in that case you don't even need this proposal.

import { Button } from "@company/ds"
import buttonStyles from "@company/ds/button.css"

export let links: LinksFunction = () => {
  return [{ rel: "stylesheet", href: buttonStyles }]
}

sergiodxa Nov 10, 2022
Maintainer

Optionally, the ds lib could provide a single CSS file with all styles concatenated

import styles from "@company/ds/styles.css"

export let links: LinksFunction = () => {
  return [{ rel: "stylesheet", href: styles }]
}

So you could use both

Import only the CSS of the components you need
Import the CSS of all components at once

lili21 · 2022-11-08T03:07:00Z

lili21
Nov 8, 2022

I guess it would make some thing more difficult or impossible if we do it at runtime. like purging the unused css.

0 replies

chaance · 2022-11-10T16:57:20Z

chaance
Nov 10, 2022
Maintainer

Another potential issue here is the DX for those using any sort of post-processor. If I'm using Sass/PostCSS for CSS Modules and Sass/PostCSS for my plain CSS, presumably I'm already running a separate dev/pre-build process for the latter. Doing this at runtime for CSS Modules means I'd need to wire that up twice and move dev dependencies to my server build.

Also: said post-processor might depend on Node, and the user is shipping to another runtime without interop.

0 replies

markdalgleish · 2022-11-13T23:18:44Z

markdalgleish
Nov 13, 2022
Maintainer

There are another couple of concerns I have with this approach.

CSS Modules are normally treated as private implementation detail for a component, but this approach would force component styles to be part of its public API since the component would be unable to resolve its own styles anymore. It also means that there now needs to be a mechanism for passing all resolved styles objects to all route descendants.

Typically when working with CSS Modules, styles are co-located with each component, so Button.tsx would have a corresponding Button.module.css which is then resolved by the bundler via an import statement. Consumers of this component don't need to worry about its style sheet (or lack thereof).

However, with this proposed approach, styles are resolved at runtime at the route level instead. This means that if we wanted our example Button component to manage its own CSS Modules file, it would need to export the file path so that consuming routes can access it (either directly or via another component that renders Button and forwards it on) and then it would need to accept the resolved styles object via props/context so that the route is able to pass it back down, e.g.
```
export const cssModulePaths = ['./path/to/Button.module.css'];

export function Button({ styles, ...etc }) {
  return <button className={styles.root} {...etc} />;
}
```
This may be somewhat workable when the component tree is shallow, like in the example provided in this proposal, but I can see this quickly getting unworkable once components using CSS Modules are composed of other components using CSS Modules and you need to pass down all styles objects for all descendants, ensuring that each one is passed to the correct component. I would expect that most people who have worked with CSS Modules before would reject this model.
Some CSS Modules users like to set up type checking for the styles object to ensure all referenced class names actually exist, but the proposed approach would make this difficult/impossible compared to the more typical bundler integration. For example, at SEEK we wrote this webpack loader to generate a .d.ts file for each CSS file: https://www.npmjs.com/package/css-modules-typescript-loader.

0 replies

penx · 2022-11-26T22:39:23Z

penx
Nov 26, 2022

Looks like this will be superseded by #4631 - linking for anyone else subscribed here :)

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Runtime CSS Modules #4542

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Replies: 8 comments 8 replies

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

Select a reply

Runtime CSS Modules #4542

ryanflorence Oct 19, 2022 Maintainer

CSS Modules in Remix

Setup

Using CSS Modules

How it works

createCssModules

Resource Route

Questions

Caching Perf

Runtime Perf

Hurdles

Replies: 8 comments · 8 replies

sergiodxa Nov 3, 2022 Maintainer

sergiodxa Nov 3, 2022 Maintainer

sergiodxa Nov 3, 2022 Maintainer

penx Nov 8, 2022

penx Nov 10, 2022

penx Nov 10, 2022

wingleung Nov 10, 2022

sergiodxa Nov 10, 2022 Maintainer

sergiodxa Nov 10, 2022 Maintainer

lili21 Nov 8, 2022

chaance Nov 10, 2022 Maintainer

markdalgleish Nov 13, 2022 Maintainer

penx Nov 26, 2022

ryanflorence
Oct 19, 2022
Maintainer

`createCssModules`

Replies: 8 comments 8 replies

sergiodxa
Nov 3, 2022
Maintainer

sergiodxa
Nov 3, 2022
Maintainer

sergiodxa
Nov 3, 2022
Maintainer

penx
Nov 8, 2022

sergiodxa Nov 10, 2022
Maintainer

sergiodxa Nov 10, 2022
Maintainer

lili21
Nov 8, 2022

chaance
Nov 10, 2022
Maintainer

markdalgleish
Nov 13, 2022
Maintainer

penx
Nov 26, 2022