🗺️ CSS Modules

[markdalgleish]

CSS Modules

Prior art

• feat: CSS modules (early experimental support) #2489

Related issues

• Support for CSS Modules #2214
• Built in support for CSS bundling. #1302
• Runtime CSS Modules #4542

Summary

This proposal aims to add built-in support for CSS Modules via imports of *.module.css files, offered as an alternative to the existing supported styling solutions.

Motivation

CSS Modules is a widely used community standard for scoping CSS that many frameworks/meta-frameworks support out of the box. A lot of developers who come to Remix are surprised to find that there's no built-in support. This makes it difficult for them to adopt Remix, either because they're trying to migrate an existing codebase/component library that uses CSS Modules, or it's their preferred way of writing maintainable CSS.

API and tradeoffs

CSS Modules are opt-in via the community standard file extension *.module.css. Any CSS file named this way will be treated as a CSS Module.

import styles from './Example.module.css';

export function Example() {
  return <div className={styles.root} {...etc} />;
}

In order to keep things simple and get to a working version sooner, especially since esbuild doesn't support code splitting of CSS due to concerns with CSS ordering, we're opting to output a single CSS file for all CSS Modules used in the app. This will need to be clearly noted within the Remix documentation since, while this is a suitable tradeoff for many applications, it obviously has issues at much larger scales where the generated file could be quite large. Anyone who is concerned about CSS bundle size should be recommended to look at alternative solutions, particularly those that create atomic CSS.

Based on @chaance's prior work in this space, Remix can provide access to the bundled CSS URL via a separate package which should then be included in your root route.

import cssBundleHref from '@remix-run/css-bundle';

export const links = () => {
  return [
    ...(cssBundleHref ? [{ rel: "stylesheet", href: cssBundleHref }] : []),
  ];
};

A notable difference to prior work is that this package needs to be generalised beyond CSS Modules ('@remix-run/css-bundle' rather than '@remix-run/css-modules') so that we can add support for other CSS bundling solutions in the future, e.g. importing CSS within node_modules, Vanilla Extract, CSS import side effects (e.g. import "./example.css").

Open questions

• What format should we use for scoped class names and should it differ between dev and prod? e.g. it's common to have debuggable class names during development, like .Button-module__root__a4X9gs, but only emit the hash in production, like .a4X9gs.

• How should we handle named exports from CSS Modules, if at all?

  For example, let's assume the following CSS:

  .exampleClass { ... }
  .example-hyphenated-class { ... }

  It's expected that you can access these via the default export:

  import styles from './example.module.css';
  
  export default () => (
    <>
      <div className={styles.exampleClass} />
      <div className={styles['example-hyphenated-class']} />
    </>
  );

  It may also be expected that you can access classes via named exports too. For example, the following is supported in Next.js:

  import { exampleClass } from './example.module.css';
  
  export default () => (
    <div className={exampleClass} />
  );

  However, this clashes with the proposed global type for *.module.css files since it can only describe the default export ({ [key: string]: string }). This means that any attempt to access named exports (as in the example above) will be a type error. This can only be fixed by generating specific types for each CSS file. In fact, even Next.js reports a type error for this code when using TypeScript. IMO this means we probably shouldn't support named exports from CSS Modules.

  Another tradeoff with named exports is that you won't be able to access class names that are invalid JS identifiers, e.g. it's not valid to use hyphenated names like import { example-hyphenated-class } from './example.module.css' or use reserved works like import { break } from './example.module.css'.

[chaance]

Love this. One thing to consider with generalizing @remix-run/css is that some apps might have more than one bundling requirement. An app that uses CSS modules today might want to migrate to Vanilla Extract, and that could be easier with incremental refactoring.

Can you foresee any potential issues with bundling output from CSS Modules and Vanilla Extract into the same stylesheet? What about other solutions that generate atomic CSS instead of scoped selectors (a la Stylify or [one day] Stylex) where the cascade might be more relevant? That's probably out-of-scope here, but supporting it in the future could require a breaking change with a generalized virtual module.

[markdalgleish]

The way I'm thinking about this is that we're simply forwarding on the output from esbuild, which would generate a single CSS file even when mixing and matching CSS Modules, Vanilla Extract, etc.

[pcattori]

For the *.css Typescript problem, one workaround I've found is to use a named export like styles for the CSS Module classnames:¹

declare module "*.css" {
  let asset: string;
  export default asset;

  // extend the existing *.css definition to include a named export
  export const styles: Record<string, string>;
}

That way we can keep using the default import for the file's public path location. Obviously this isn't ideal as the styles export will still be available for non-CSS Modules, but an easy workaround there could be to return an empty object {} for styles. This is the approach I took for CSS Module support in the webpack demo.

Of course, if TS could simply disambiguate .module.css and .css, then we'd get better more explicit typesafety. But I think this approach is a good shim until TS can do that.

---

Either that or somehow generate .d.ts files for each .module.css file I guess...

Footnotes

1. Since declare modules for the same module are merged, you can even declare the styles export in a separate file than where we currently declare *.css if that turns out to be better for some reason. ↩

[sergiodxa]

What would happen with libraries using CSS Modules? It's really common people import a component from a library and that component imports its styles from a CSS Module expecting the bundler to handle that.

If in Remix CSS Modules comes as import { styles } from "~/file.module.css" and are used as styles.container it will mean the library needs to do that, but AFAIK that doesn't work this way anywhere else.

[chaance]

Some libraries may pre-process and bundle CSS modules on their own. In that case we shouldn't need to do much other than have them load those stylesheets (though that could be a pain if each module comes with a separate stylesheet).

Others may ship with the un-transpiled module imports in tact. I suspect those would end up in serverDependenciesToBundle and whatever plugin we build will handle those the same as app code.

I don't actually know which of these cases is more common, perhaps @markdalgleish has some insight here?

[markdalgleish]

My guess is that it's more common for open source libraries to ship plain CSS files rather than CSS Modules.

Publishing code to npm that requires further transformation would be much less common, likely only used for in-house libraries that can be more opinionated about the tooling their consumers use, e.g. they know all their consumers at work are using Next.js with next-transpile-modules.

[davidhousedev]

So exciting!

I have a clarifying question about the longer-term outlook. Given this RFC is taking the path currently supported by esbuild, how do you imagine CSS Module and Vanilla Extract support will change with more robust support for these tools in esbuild?

From their docs

Note that esbuild doesn't yet support CSS modules, so the set of JavaScript export names from a CSS file is currently always empty. Supporting a basic form of CSS modules is on the roadmap.

I also have a more wacky question, if you'll humor me 😅. It seems like esbuild supports bundling css based on entrypoints. Could Remix bundle CSS by treating each route component as a separate entrypoint? I suppose it wouldn't solve problems with duplicate styles loaded across routes but it would reduce app.css size.

[markdalgleish]

If esbuild introduced support for CSS code splitting, we'd need to revisit the API if we wanted to take advantage of this since it would require a change to your link tags. If esbuild adds support for CSS Modules without code splitting, it might simply mean that we can remove a plugin internally, assuming it has the same level of functionality.

Each route is already a separate entry point in the browser build. With esbuild's current approach to CSS bundling, we can easily get a separate CSS file per route but unfortunately, as you say, it introduces duplicate styles if anything is shared between routes.

[davidhousedev]

Each route is already a separate entry point in the browser build.

Oh! Okay! I'm still speculating here, but I wonder if the duplicate styles could be pruned at build time. In another thread, you proposed a compileCss step. Could that also include a pruneCss task that traversed the route tree and deleted class names which were found in a parent route? This would be coupled to the uniqueness of the class names output by CSS Modules and Vanilla Extract; in an app with heterogenous styling tools that included CSS Modules and e.g. regular CSS, other class names would need to be ignored.

[markdalgleish]

I have a couple of concerns with going down this road:

1. Removing styles that are in a parent route could work but it wouldn't be enough because you'll also have sibling routes with shared styles. What you really want here is proper support for code splitting for CSS in the bundler.
2. I'm deliberately trying to keep things simple for now and avoid inadvertently building a bundler. The primary goal for now is to unblock people who need/want CSS Modules support, albeit with some clearly noted tradeoffs.

[davidhousedev]

Makes complete sense to me. Thanks for elaborating!

[markdalgleish]

I've been experimenting a bit to see what the simplest CSS Modules implementation could look like (and also as a way to get more acquainted with Remix internals). Here's what I've got so far.

• To start with I tried esbuild-css-modules-plugin.
  • Initially it silently failed to generate any CSS. After some digging I discovered it can't handle virtual modules as entry points because it tries to read the contents of each entry point from the file system. To unblock this I hacked a workaround into node_modules.
  • It doesn't currently support composes so it would need a patch.
  • It has no way to disable emitting CSS which is something we'd probably want to do. I imagine we'd only want to emit CSS for one of our builds.
  • It has support for generating .ts files alongside each CSS Module — not .d.ts files though which is what I was expecting. I hacked a fix into node_modules to generate .d.ts files instead, so this is something we'd need to raise on their end. I also needed to patch the Remix watch logic to ignore these generated files to prevent the dev server from getting into an endless loop since the build process generates additional files which then starts another build etc.
• I learned the hard way that esbuild generates a CSS file for each entry point with no option to create a single CSS file containing everything. Each CSS file duplicates anything that's shared between routes which isn't ideal for us since it would cause users to repeatedly download the same styles when navigating around. I hadn't run into this behaviour during my previous work with esbuild because, even though our project had multiple entry points with code splitting enabled, I forgot that we still had a main entry point from which all CSS was reachable. I raised an issue asking whether esbuild could optionally generate a single CSS file for the entire build: Feature request: Optionally create single CSS file for all entry points evanw/esbuild#2688.
• As a workaround, I tried adding a new virtual module entry point to the browser build, along with an accompanying plugin (inspired by serverBuildVirtualModule/serverEntryModulePlugin), from which all CSS is reachable by importing all routes. This worked and created a single CSS file, but the downside of this approach is that it adds extra JS chunks to the app. This is because esbuild attempts to share code between the app code and this new CSS build entry point. Even though this seemed to be working, I didn't want to add extra network overhead.
• I tried generating CSS from the server build since it has a single entry point with access to all routes, but this meant that the generated file is called index.css rather than having a content hash in the file name. It also means we'd lose any CSS that was imported in the client entry. This felt like a dead end.
• One idea I had for another workaround was to have an additional compileCss step in the Remix compiler (alongside compileServer/compileBrowser) so that it doesn't interfere with the other builds by generating pointless JS chunks etc. This way we can configure it to include all CSS and generate a CSS file with a content hash in the name. Curious what others think of this approach.

[KingSora]

@markdalgleish In case you are open for a slightly different approach with more room for optimization, please read my suggestion here: #4191

I know this proposal doesn't explictely mention css modules, but it can be perfectly used for them. It would also play nice with the requirement of @ryanflorence (#4631 (comment)) of also importing non-css-modules.
It also describes a possible implementation strategy.

[ryanflorence]

@markdalgleish We should add a note to this RFC about handling import "./whatever.css" inside of app code as well as node_modules that we discussed in all-hands today.

[markdalgleish]

Based on my initial work and some internal discussion, I've changed the API for importing the bundled CSS:

-import { bundledCssUrl } from '@remix-run/css';
+import cssBundleHref from '@remix-run/css-bundle';

Note that it's now a default export so you can easily name it whatever you like. I also made the package name a bit less vague.

[markdalgleish]

There was an open question about how we can get types for *.module.css files and *.css files to co-exist. This was based on an assumption that this wasn't possible in our global type definitions, but luckily it turns out this assumption was wrong, we just need to declare the CSS Modules type first.

Consumers may still want to generate better types than the default ({ [key: string]: string }) since it doesn't provide proper type checking of class names, but this is still a great default.

[markdalgleish]

I've updated the RFC to add an open question about whether or not we should support named exports from CSS Modules, e.g. import { exampleClass } from './example.module.css. After thinking it through I don't think we should because it clashes with our default types for *.module.css files, but I've added a bit more detail and an explanation of my reasoning.

[AdsonCicilioti]

Hello friends!

As @ryanflorence said, don't forget to pay attention to importing css files directly - import "whatever.css".

I recently started building a library of React components and chose Vanilla Extract for styling. The motivation was to obtain components with their css files duly compiled and that did not depend on any other runtime task, being compatible with the main approaches of React 18+ applications - with their new features - and their most popular metaframeworks (Next 13, Remix, etc).

I used Rollup and its vanilla-extract plugin, and built the components bundle independently, where each component loads its own CSS file - import "./button.css".

When testing in React apps (CRA or Vite) everything works perfectly, but when importing and using my components in remix routes I have no success.

I've tried all the approaches related to my case presented on this page - https://remix.run/docs/en/1.14.3/guides/styling#css-bundling - But the best I could do was render my components without their respective css style.

I don't have enough knowledge to collaborate in the development or in proposals for solutions, but I leave this need that I believe is not just mine.

[chaance]

You can do this today with a future flag, per https://remix.run/docs/en/1.14.3/guides/styling#css-side-effect-imports. If that doesn't work then you may need to open an issue.

[AdsonCicilioti]

Thx @chaance for your reply. Really, i've test using a css file into app folder and work fine. My problem is with my ui library package on a monorepo.

See:

• 1 - Is my components library and dependencies
• 2 - Is the apps that use the ui components. cms is a Remix (v1.14.3) app.

Also i've set the ui packages on serverDependenciesToBundle:

odule.exports = {
  serverBuildTarget: "vercel",
  server: process.env.NODE_ENV === "development" ? undefined : "./server.js",
  ignoredRouteFiles: ["**/.*"],
  watchPaths: ["../../ui/react", "../../ui/styles", "../../ui/tokens"],
  serverDependenciesToBundle: [/^@arakin-ui/], // Root name of all ui packages
  future: {
    unstable_cssSideEffectImports: true,
  },
};

[AdsonCicilioti]

I found my problem with help from a fellow community member on Discord.

My problem was with the name of the file extensions of my package in which commonJs had the .cjs extension and the modules had .mjs. And the esbuild plugin responsible for capturing the CSS from the unstable_cssSideEffectImports feature doesn't recognize these formats yet.

The problem has already been reported here.

And there is already a fix to be included in the next v1.15 release.