🗺️ Vanilla Extract

[markdalgleish]

Vanilla Extract

Summary

This proposal aims to add built-in support for Vanilla Extract, building on top of the CSS bundling architecture introduced with CSS Modules.

Motivation

Many Remix consumers have been asking for Vanilla Extract support so that they can write static CSS in TypeScript.

Typically this is achieved by installing and configuring a bundler plugin, but since Remix doesn't expose the compiler to consumers, there's no way for them to achieve this. To avoid opening up the compiler to consumers, we're opting to include built-in support so you can just start writing .css.ts/.css.js files without needing to set up any plugins.

Usage

CSS bundling would first need to be set up, if it isn't already:

npm install @remix-run/css-bundle

// root.tsx
import type { LinksFunction } from "@remix-run/node"; // or cloudflare/deno
import { cssBundleHref } from "@remix-run/css-bundle";

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

Then you'd need to install the core Vanilla Extract styling package since it's imported in your app code.

npm i -D @vanilla-extract/css

Then you'd need to enable the feature flag in your remix.config.js.

/** @type {import('@remix-run/dev').AppConfig} */
module.exports = {
  future: {
    unstable_vanillaExtract: true,
  },
  // ...
};

Vanilla Extract is then opt-in via the file extension .css.ts/.css.js. Any code within these files will be executed at build time.

// Example.css.ts
import { style } from "@vanilla-extract/css";

export const root = style({
  padding: 12,
  // etc.
 });

// Example.tsx
import * as styles from './Example.css'; // Note that `.ts` is omitted here

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

To be consistent with the rest of your app code, we need to ensure that asset imports work the same, e.g.

import { style } from "@vanilla-extract/css";
import logoUrl from "./logo.svg";

export const root = style({
  backgroundImage: `url(${logoUrl})`,
});

Open questions

Autoprefixing

How do we handle autoprefixing? This is usually achieved by providing a custom processCss function to the bundler plugin, but this option isn't exposed to consumers in our implementation.

I think the ideal would be to handle it automatically based on the presence of a browserslist config, similar to @brophdawg11's .browserslistrc support proposal. This raises questions around sequencing though—is it okay for browserslist config to only be supported for Vanilla Extract initially? Or do we need to add built-in autoprefixing before we add Vanilla Extract support? Either way, I've added a proposal for built-in CSS autoprefixing.

Alternatively, we could ship an MVP solution, e.g. autoprefix Vanilla Extract styles using the supports es6-module query, which in the future would serve as the default when a browserslist config isn't detected. Actually, scratch that, this would break styles for end users in old browsers that don't support ES modules who are being given a fallback non-JS experience.

We could also just do nothing for now and force consumers to manually prefix their styles, but this doesn't seem great to me.

[chaance]

// Example.tsx
import * as styles from './Example.css'; // Note that `.ts` is omitted here

What does the type signature of styles look like here? Is TypeScript smart enough to disambiguate this from a regular .css or .module.css import when we define those internally on the global namespace?

I think the ideal would be to handle it automatically based on the presence of a browserslist config, similar to @brophdawg11's .browserslistrc support proposal.

Agreed, though I don't think support for that should be a blocker for initial release. Consumers should be able to manually prefix things in most cases if they need it (not ideal obviously, but it's just a separate step in the release plan).

This raises questions around sequencing though—is it okay for browserslist config to only be supported for Vanilla Extract initially?

I think that config should probably be used universally for anything we bundle. That's kind of the whole idea behind browserslist -- you tell me what browsers you want to target, now your bundlers know what sort of transforms they should do. esbuild gives us the target API for this.

That said, if we wanted to support browserslist only for CSS, it seems to me we should do that for anything compiled from @remix-run/css-bundle. I can't imagine why you'd want different autoprefixing for different tools. With a few tweaks to the Remix config flag, maybe we could do something like this:

module.exports = {
  future: {
    unstable_cssBundle: {
      cssModules: true,
      vanillaExtract: true, // could also be a config option, eg: { identifiers: 'debug' },
      autoprefixer: {
        overrideBrowserslist: [], // same API as the postcss plugin here
      },
    },
  },
};

[sergiodxa]

What does the type signature of styles look like here? Is TypeScript smart enough to disambiguate this from a regular .css or .module.css import when we define those internally on the global namespace?

I think this would be a good use case for supporting import assertions, so devs could do

import styles from "./example.css" assert { type: "vanilla-extract" }

I'm not sure how TS support it but this way it would be clear that the import is a vanilla-extract import and don't a url to the CSS file

[chaance]

That would work but I'd kind of hate it as a user 😅.

Also, it might not work because you'd want the type to reflect the types from the actual TS file. You don't want a generic "vanilla-extract" type declaration here. Unless I misunderstand how import assertions work with TS (I've avoided them intentionally since there's been a lot of churn in the proposal).

[markdalgleish]

What does the type signature of styles look like here? Is TypeScript smart enough to disambiguate this from a regular .css or .module.css import when we define those internally on the global namespace?

TypeScript know's it's a .ts file, it just doesn't (currently) let you explicitly write that in the path. The types work the same as any other TS file which is super nice.

Agreed, though I don't think support for that should be a blocker for initial release.

Yeah, maybe that can be a fast follow, especially since this is behind an unstable flag.