Remix and Rabbit Trails — Tailwind vs. CSS Modules
I recently decided to rebuild my portfolio site and I wanted to play around with some technologies that I don’t get to work with in my day to day as a developer. I’ve been hearing a lot of buzz about Remix so I pulled down the Indie Stack and got to work. I consider myself a traditional Front-End Developer, so it wasn’t just the “Latest, Greatest, JS Framework” I was looking forward to playing with; I was also interested in how Remix does styles!
At the time of this writing, I’m still in the middle of building the site, though, I’ve definitely settled on how I want to do CSS with Remix. It involves a journey through Tailwind before ultimately landing on a classic: “CSS Modules”.
You may have heard that CSS Modules don’t work with Remix. Well, they can if you’re willing to get a little creative! If you’re only interested in how to get CSS Modules working with Remix, then skip all the “Rabbit Trail” sections and jump to the end. Skip Link FTW!
Rabbit Trail — Step 1: My Styling Philosophy
Being largely in the React space professionally, I’ve been watching a lot of Jack Herrington / Blue Collar Coding videos to stay up-to-date with the latest that’s going on in the React Ecosystem. I think what impresses me most about Jack is his willingness to seemingly eschew any developer dogmatism by embracing a variety of tools, frameworks, etc. in the Web Development space for his videos.
It’s really motivated me to go beyond what I’m comfortable with and so I left my favorite tools behind: Astro, NextJS, and Linaria and decided to give Remix and Tailwind a go. I didn’t choose Tailwind just because it’s very popular with Remix though; I had certain requirements for my rebuild.
Rabbit Trail #1.5: Requirements
CSS-in-JS — Loosely speaking, I lump any tool into the CSS-in-JS category if there’s some sort of build that processes and/or generates my CSS. Anything from CSS Modules to styled-components to Vanilla Extract to Tailwind. There’s a slew of CSS-in-JS tools out there. I’ve even made one. I prefer not to rely solely on conventions like BEM. They’re hard for teams to follow and even hard for myself to follow personally. Plus, I want to run my CSS through a build anyway, so, why not let the tool act as my convention?
Just-in-Time CSS — I’m a bit of a code golfer and enjoy configuring my builds to bleed out every byte I can for my end users. This includes not shipping any runtimes. That’s not to say that tools like styled-components and Emotion are bad, they just don’t fit with my personal development paradigm. Why ship a runtime when you don’t have to?
If you prefer tools like styled-components and Emotion, consider looking at a JIT alternative like Linaria!
PostCSS — I’m looking forward to the day when we have a fully pluggable CSS processing toolchain built on Rust or Go. Lightning CSS, Turbopack, and Vite have modern toolchains that can do what PostCSS Modules, cssnano, and Autoprefixer can do but there are SO MANY OTHER PLUGINS out there. I have a suite of PostCSS tools I use regularly and I’m not prepared to give those up for a personal project!
I’ve been really digging PostCSS Nesting, PostCSS JIT Props, and *shameless plug* At-Rule Packer.
Considering the above and that Remix recommends Tailwind, I decided now was the time to take the plunge.
Rabbit Trail — Step 2: Tailwind
I think the jump into Tailwind for some developers can be really tough. I was already convinced that Atomic CSS makes complete sense though and had previously played with Atomic CSS tools like Atomizer. While as an input, Atomic leaves a lot to be desired, as an output you won’t really find a convention that provides a smaller footprint and that really speaks to the code golfer in me. Why ship more bytes to my users than I have to? I even based my CSS-in-JS tool around Atomic CSS as an output.
So the “why” of Tailwind was easy for me to get past. The “how” was also super easy as the Indie Stack ships with it out of the box. So with that, I set out to figure out how to tie my generated Tailwind file into PostCSS.
Rabbit Trail — Step 3: Tailwind ❤ PostCSS
So, until I started this whole process I had no idea that Tailwind had a PostCSS plugin. This makes tying the two together really simple. You replace L13 of the package.json with: postcss path_to_main.css -o ./app/styles/tailwind.css. Where “path_to_main.css” is a path to your CSS file with the Tailwind directives:
@tailwind base;
@tailwind components;
@tailwind utilities;Easy. I threw my PostCSS Config into my repo, a CSS reset into my main.css file, and was delighted to see my CSS generated as I added the predefined classes into my markup.
Does it get any easier than this? What could go wrong?
Rabbit Trail — Step 4: Trouble in Paradise
I started this post with the fact that I eventually switched from something new in Tailwind to something old in CSS Modules so this section should come as no surprise. I ran into enough issues with Tailwind that I eventually wanted to get back to something more familiar.
Some of the issues were with me and how I like to do things and some of the issues were with Tailwind. None of this is to say I wouldn’t use Tailwind again on a team project, more that it wasn’t a good fit for a small personal project of mine. Less friction the better.
Me Problem #1: I prefer CSS Properties to configs
I’ve been playing around with Open Props for awhile now. Being able to quickly leverage things a smooth transition timing function is really handy (and cheap thanks to PostCSS JIT Props!). To use Custom Props with Tailwind you either map them in the tailwind.config.js file via extend/theme or you can inline with Tailwind’s arbitrary values: ease-[var(--ease-3)]. Doing this once or twice is fine but it gets kind of annoying when you’re doing it often. Tailwind convention seems it would prefer it if I leveraged the config for custom values so this is me going against the grain.
Me Problem #2: em’s Matter
Throughout the documentation, I didn’t see a way to use em’s without using arbitrary values. When building components, it’s nice to set the the root component size to a rem value and then it’s various pieces with an em value. This builds a fully inter-relational component where you can adjust the scale by changing the root size. This is especially great for things like Buttons which often need different sizes.
With Tailwind, I was setting the root size with text-base then shifting back to arbitrary values for styling all of my relational values. It was enough of a mental model shift that I found myself defaulting to classes like py-2 out of habit then having to go back and adjust to get things how I wanted.
Me Problem #3: Property Names
Some of the Tailwind classes make a ton of sense to me. font-light makes your font-weight light. Got it. I also really like how they handle pseudo’s (though, we’re missing :has()?). However, some of the names weren’t immediately obvious. text-white makes text white but we also use text- for text-align. If you want to transform text, you use the property value: uppercase, lowercase, etc.
A lot of this isn’t Tailwind’s fault. CSS can be all over the place with its property names. Naming things is hard. However, I’ve gone through years of rote memorization with CSS property names. Not so with Tailwind and constantly referring back to the docs (intellisense in VSCode for the class names was slow/dumb for me) was a bummer.
Tailwind Problem #1: Class Name Verbosity
In the design I was testing out for my nav items, I wanted to embolden the text on :hover or :focus-visible (without shifting any nearby siblings) and I wanted the underline to slide in and out.
You can accomplish the emboldening without shifting by using a pseudo element tied to an attribute with the same content as the link. In my case, I called it data-b. The moving underline can also be accomplished with a pseudo by changing the scaleX and transform-origin.
In Sass/CSS (with nesting) it looked something like this:
.headerNavlink {
display: inline-flex;
flex-direction: column;
position: relative;
text-decoration: none;
&::before {
content: attr(data-b);
display: block;
font-weight: 600;
height: 0;
visibility: hidden;
}
&::after {
background: var(--logo-top-square);
bottom: 0;
content: "";
height: 0.1em;
left: 0;
position: absolute;
transform: scaleX(0) translateY(200%);
transform-origin: right;
transition: transform 0.115s var(--ease-in-5);
width: 100%;
}
&:focus-visible,
&:hover {
font-weight: 600;
&::after {
transform: scaleX(1) translateY(200%);
transform-origin: left;
}
}
}or in Tailwind classes, like this:
inline-flex flex-col relative no-underline before:content-[attr(data-b)] before:block before:font-semibold before:h-0 before:invisible after:bg-[var(--logo-top-square)] after:bottom-0 after:content-[''] after:h-[.1em] after:left-0 after:absolute after:scale-x-0 after:translate-y-[200%] after:origin-right after:ease-in-5 after:transition after:duration-[.115s] after:[var(--ease-in-5)] after:w-full focus-visible:font-semibold focus-visible:after:scale-x-1 focus-visible:after:translate-y-[200%] focus-visible:after:origin-left hover:font-semibold hover:after:scale-x-1 hover:after:translate-y-[200%] hover:after:origin-leftYikes… So obviously, yea, I could’ve gathered all this up and leveraged either the Tailwind config or added a semantic class to my stylesheet but I’d be cutting against the very performance of the Atomic output I was looking forward to. I mentioned Atomizer earlier and it’s very similar to Tailwind, however, the classes are abbreviated for both the property names and values. Having prior experience with Atomizer, I was surprised by how much the above bothered me and how unmaintainable it is.
Tailwind Problem #2: Prettier Integration
I absolutely love Prettier and I like it for Tailwind classes too except that it only works if it sees the classes in the className prop in my React components. I had 5 separate nav items that each needed the above classes. There’s no way I’m not putting those in a const navLinkClasses = "..." variable for reuse so I just miss out on Prettier helping me out for these classes.
Not sure what can be done here from a tooling standpoint but it’s a big bummer as some of my classes are organized and some may not be.
Tailwind Problem #3: Some Things Didn’t Seem to Work?
Again jumping back to my nav example, I was having serious trouble getting transform’s to work as expected on my pseudo’s on hover. Specifically, the scaling on my underline. I’m not sure if I fat-fingered something or I was missing some sort of framework specific gotcha, but after fighting with it for twenty or so minutes I decided I had enough.
I didn’t want to deal with all of the problems above throughout the entirety of the project so I decided to pivot.
Remix and CSS Modules
In the Remix docs for styling it states flat out that any framework that requires “direct integration with our compiler” to “automatically inject styles onto the page” doesn’t work. So any JIT tool with a CSS-in-JS style API was out. No Linaria. No Vanilla Extract.
Since we’re not doing Tailwind, why not revisit a classic? We already know that PostCSS works with Remix and PostCSS Modules may have been the original CSS-in-JS tool. There won’t be any direct integration but we can do that piece ourselves!
Configuring CSS Modules and PostCSS
Remix supports importing regular stylesheets based on routes. This is a really cool feature because it means we can tell Remix to only load the component CSS we need in order to render that page. If that same component is used on another route, the user should already have that file in their browser cache. It’s important to have a good understanding of their Route Styles and Shared Component Styles sections as our CSS modules will also be “regular stylesheets”.
Traditionally with CSS Modules, when we import a CSS file, we get a JSON object which maps the original class name to the now localized/hashed class name. Remix won’t give us that out of the box, so we have to get clever with our PostCSS config file. First, let’s start with the package.json.
package.json
Straight from the Indie Stack, the three CSS related scripts are as follows:
"build:css": "npm run generate:css -- --minify",
"dev:css": "npm run generate:css -- --watch",
"generate:css": "tailwindcss -o ./app/styles/tailwind.css",Instead, set them to:
"build:css": "npm run generate:css -- --env production",
"dev:css": "npm run generate:css -- --watch",
"generate:css": "postcss ./app/styles --dir ./app/.css --base ./app/styles",./app/styles is where I’ve put all my CSS. Replace with wherever yours is located.
./app/.css is where PostCSS drops the processed CSS.
-- --env production while not strictly necessary it’s nice to be able to adjust PostCSS settings for development/production.
Also, just to get CSS modules working you’ll need to run the following command: npm i -D postcss postcss-cli postcss-modules
postcss.config.js
const path = require("path");
const fsp = require("fs/promises");
module.exports = (ctx) => {
const isProd = ctx.env === "production";
return {
plugins: {
/* ... any other plugins here ... */
"postcss-modules": {
generateScopedName: isProd
? "[hash:base64:5]"
: "[name]__[local]___[hash:base64:5]",
getJSON: async (cssFilename, json, outputFilename) => {
// Create Directories if they don't exist
await fsp
.mkdir(path.dirname(outputFilename), { recursive: true })
.catch(() => {});
// Create .ts file for exporting both the path to CSS file as well as the JSON
const ts = `
import pathToCSSFile from '${outputFilename}';
const json = ${JSON.stringify(json)};
export const href = pathToCSSFile;
export default json;
`;
await fsp.writeFile(`${outputFilename.replace(/\.css$/, ".ts")}`, ts);
},
},
},
};
};generateScopedName — Set the module formatting with this option.
getJSON — This is where the magic happens. The outputFilename argument is where the process CSS file is being written to. The json argument is a map of the original classes and their module counterpart. So, the trick here is constructing a .ts file where we import the CSS file and export the href of the built asset as well as the json as the default export.
Using CSS Modules in our Components
Alright, we’re at the final stage. Let’s say we’ve got a shared Header component and we’ve created a CSS file at ./app/styles/components/common/header.module.css. We can start adding classes to it (like .header { color: blue }) and then, finally, we can import it into our Header component like so:
import styles, { href } from "~/.css/components/common/header.module";
export function links() {
return [{ rel: "stylesheet", href }];
}href will be a reference to our CSS file in static asset form, courtesy of Remix. We need to pass the href in an exported links function so that it’s handled properly as a “Shared Component Style”. styles will be a typed object key’d with our original classes, so we can grab the example above like so: <header className={styles.header}> … </header>.
If everything was followed as above you’ll see a Header with blue text 🎉. If something didn’t work out, here’s a working example repo that you can reference.
Wrap-Up
While not a direct integration, getting to use my full suite of PostCSS plugins with CSS-in-JS handling the scoping has me pretty content. I miss the Hot Module Reloading that many frameworks offer but I’m more than willing to trade Developer Experience for User Experience.
And with that, I think that’s it!
… but what about Atomic Styles?
So, more than once I mentioned a CSS-in-JS tool I had built…
It’s called “pre-style” and the original idea behind version 1.x was that you could author your CSS however you wanted: Sass, Less, Vanilla… whatever. You pass pre-style a configuration file with your adapter for the syntax chosen and from there, Pre-Style would process your CSS file and then atomize each property into it’s own atomic class. It leveraged a Babel Plugin to process the syntax out of your JSX file so it was an early adopter of the JIT CSS-in-JS idea. Version 1.x didn’t have a cache though so larger projects got slow pretty quick if attempting to use with say HMR.
Anyhoo, some time later I decided to play around some more with this pet project and had the realization along the way that CSS Modules could act as a “syntax” for Pre-Style to process. Instead of localizing classes… why not atomize them and return the atomized classes in the resulting JSON? So Version 2.x was born with a PostCSS plugin that can do exactly that!
If you like the idea of writing CSS Modules with the performance benefits of Atomic styles, give it a try! It’s very much in alpha but I plan on dogfooding it as I build out my portfolio.
