Linaria vs Vanilla-Extract

[silviogutierrez]

Currently Reactivated supports two zero-runtime CSS-in-JS solutions. Because these require tooling, they are built-in to the compilation process and require special plugins.

The goal is to support only one.

Some good background reading: https://github.com/andreipfeiffer/css-in-js#linaria and https://github.com/andreipfeiffer/css-in-js#vanilla-extract

Background

Below is some background and high level overview of each library. Afterwards there's more open-ended thoughts on both.

Linaria

Linaria is basically styled-components but statically compiled to a plain CSS files.

Pros

• Colocation. You don't need to name things, you can just use the css tag inside className and style things.
• styled API allows creating components easily.
• Familiar API that matches styled-components.

Cons

• Tooling is slow and requires the entire babel toolchain. Reactivated abstracts this, but it's there behind the scenes.
• Sourcemaps for React components are incorrect. See esbuild plugin produces incorrect JSX source maps callstack/linaria#898
• Documentation isn't great.
• Lack of type-checking for CSS properties. You are writing plain CSS inside a template literal.

This last point is a major concern for Reactivated, as we promote type-safety everywhere. Though there are workarounds.

Vanilla-Extract

Vanilla Extract is a newer library with similar principles to Linaria, but a different approach.

Pros

• Minimal tooling with first-class esbuild support.
• Polished documentation.
• Static typing everywhere.

Cons

• No colocation. Styles must be in a separate file and each require their own names.
• No styled.div or similar API for quickly creating components.
• No nested selectors. This ends up being far more annoying than the docs imply. But we can write a utility function to work around it.

Thoughts

Basically, what we want is a mix of these two libraries. Obviously, it doesn't exist. I cannot stress enough how pleasant colocation is. Being able to apply styles directly on elements without having to name things is a dream come true. Of course, for often-enough used components you can abstract them away and give them proper names. But a separate file is a pain.

The best example of this is spacing around a element, using the gap property.

// HomePage.tsx
import {css} from "@linaria/core";

export const HomePage = () => (
    <div
        className={css`
            display: flex;
            gap: 5;
        `}
    >
        <div>First feature</div>
        <div>Second feature</div>
        <div>Third feature</div>
    </div>
);

That's with Linaria. With Vanilla Extract we would need two files:

// HomePage.css.ts
import { style } from '@vanilla-extract/css';

export const features = style({display: "flex", gap: 5});

// HomePage.tsx
import * css from "./HomePage.css"

export const HomePage = () => <div className={css.features}>
   <div>First feature</div>
   <div>Second feature</div>
   <div>Third feature</div>
</div>

It's nicely typed. But we also had to come up with the name features. This is very annoying. Doesn't seem like a big deal, right? You're listing features after all, just name it features. Imagine we need to create a second row, for more features, with a different gap.

With colocation and linaria just add another div, css call, and you're done.

With Vanilla Extract, you now need to think for a synonym. Is it... highlights? Is it... moreFeatures?

Not all is rosy with Linaria

Conversely, trying to type Linaria code is ugly. Real ugly.

On my projects, I have a helper defined as such:

import * as CSS from "csstype";

type Styles = CSS.Properties<string | number> & {
    $mobile?: CSS.Properties<string | number>;
    $desktop?: CSS.Properties<string | number>;
    $nest?: {[name: string]: CSS.Properties<string | number>};
};

export function style(...objects: Styles[]) {
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    let merged: Record<string, any> = {};

    for (const arg of objects) {
        const {$nest, $mobile, $desktop, ...styleProp} = arg;
        merged = Object.assign({}, merged, styleProp, $nest);

        if ($mobile) {
            merged["@media (max-width: 1200px)"] = $mobile;
        }
        if ($desktop) {
            merged["@media (min-width: 1201px)"] = $desktop;
        }
    }
    return merged;
}

Which lets me call a "typed" version of linaria using this hack:

// HomePage.tsx
import {css} from "@linaria/core";
import {style} from "@client/style";

export const HomePage = () => <div className={css`${style({display: "flex", gap: 5)}`}>
   <div>First feature</div>
   <div>Second feature</div>
   <div>Third feature</div>
</div>

It's even uglier if you need conditional classes, due to sibling css calls:

export const HomePage = () => (
    <div
        className={classNames(
            css`
                ${style({display: "flex", gap: 5})}
            `,
            showFeatures === true &&
                css`
                    ${style({display: "none"})}
                `,
        )}
    >
        <div>First feature</div>
        <div>Second feature</div>
        <div>Third feature</div>
    </div>
);

And of course, it's a convention. Other than writing a linter rule, there's no way to enforce it.

Our options

It seems near impossible to make Vanilla Extract support colocation. The tailwind-like approach they recommend is interesting though.

On the other hand, Linaria will probably always need Babel. However, extending Linaria to support calling style() directly seems realtively easy to do. If you know how do this, contact me directly. I'll happily pay for for your contributions.

Then again, maybe it's best to encourage Vanilla Extract and utility classes in a single, global file. For very specific styles, yes, create a HomePage.css and have to deal with naming things. The speed and first-class typing should help lessen the pain.

[silviogutierrez]

Latest update, unless something drastically changes with Linaria's babel usage: I've settled on vanilla-extract and will explore also integrating Tailwind. Lack of colocation is a problem, but the sprinkles API helps a lot.

[silviogutierrez]

Removed support for linaria in #311