vanilla-extract: TypeScript Stylesheets With No Runtime

The problem vanilla-extract solves: typed styles that compile away

Most CSS-in-JS libraries resolve styles in the browser. That means a runtime, a style injection step, and a bundle that grows with every component. vanilla-extract takes the other path: you write styles in .css.ts files, the build tool evaluates those files, and the output is a static stylesheet. The README describes it as "CSS Modules-in-TypeScript" with scoped CSS variables and more, and states plainly that none of the code in .css.ts files is included in the final bundle. Think of TypeScript as the preprocessor instead of Sass or Less.

The audience is narrow but real. If you already like CSS Modules because class names are hashed and local, but you want autocomplete on property names, compile-time errors when you misspell a value, and variables that are scoped rather than global, this is aimed at you. It also suits design-system authors, because the theme system is built on CSS variables and the README claims support for simultaneous themes with no globals. Teams that only need a few utility classes will find the setup cost hard to justify.

How .css.ts files become static CSS: the build-time mechanism

The unit of work is the .css.ts file. Inside it you import createTheme and style from @vanilla-extract/css. createTheme returns a tuple: a class name for the theme and a vars object whose properties map to CSS custom properties. Passing vars.color.brand into style() emits a var() reference in the generated CSS rather than the literal value, which is what makes theme swapping possible without regenerating styles.

The evaluation happens in the bundler plugin, not in your application code. The README says that once build tooling is configured, these files are evaluated at build time. The repository ships a packages/ directory with per-bundler plugins, and the release feed lists @vanilla-extract/vite-plugin, @vanilla-extract/turbopack-plugin and @vanilla-extract/sprinkles as separately versioned packages, so each integration has its own release cadence. The examples/ directory contains webpack-react and next projects that show the wiring in practice.

Two optional escape hatches exist. The README mentions an optional runtime version for development and testing, and an optional API for dynamic runtime theming. Those are opt-in, and reaching for them changes the zero-runtime property that gives the project its name.

Installing vanilla-extract and writing a first themed style

The README points to the documentation site for setup guides rather than listing install commands, so the package names below come from the imports shown in the README and from the workspace packages. The core package is @vanilla-extract/css. Start by adding it and the plugin for your bundler.

pnpm add @vanilla-extract/css
pnpm add -D @vanilla-extract/vite-plugin

The README does not print a Vite config, so treat the plugin registration as the step to confirm against the documentation site for your bundler before you rely on it. Once the plugin is registered, create a .css.ts file. This example is copied from the README:

// styles.css.ts
import { createTheme, style } from '@vanilla-extract/css';

export const [themeClass, vars] = createTheme({
  color: { brand: 'blue' },
  font: { body: 'arial' }
});

export const exampleStyle = style({
  backgroundColor: vars.color.brand,
  fontFamily: vars.font.body,
  color: 'white',
  padding: 10
});

Consume the exported names in your markup, again as the README shows:

// app.ts
import { themeClass, exampleStyle } from './styles.css.ts';

document.write(`
  <section class="${themeClass}">
    <h1 class="${exampleStyle}">Hello world!</h1>
  </section>
`);

What you should see after a build is a generated CSS file containing hashed class names and custom properties such as the brand colour, with no styling code left in the JavaScript bundle. If the .css.ts file is not evaluated and no CSS appears, the plugin is not registered for that bundler.

Where the build-time model breaks down

The zero-runtime promise has a cost: anything that depends on runtime state cannot be expressed as a plain style object. A colour picked from a user profile, an offset measured from a DOM node, or a value fetched from an API is not known when the build runs. The README acknowledges this by offering an optional API for dynamic runtime theming, but using it means you are no longer on the zero-runtime path, and the documentation does not describe the performance profile of that mode.

The second constraint is tooling. Every .css.ts file is inert until a bundler plugin evaluates it. That makes the build configuration part of your critical path: a misconfigured plugin produces no styles rather than an error you can see in the browser. The repository keeps separate plugins per bundler, so the integration you depend on has its own release history. The last push to the repository was on 2026-08-27, and the most recent release in the feed is @vanilla-extract/[email protected] on the same date, which tells you the project is still receiving commits, but the README does not document a support matrix for framework versions, so matching your framework to the fixtures in examples/ is on you.

vanilla-extract compared with CSS Modules and runtime CSS-in-JS

The closest comparison is CSS Modules, which the README names directly as the concept it extends. Both hash class names so styles stay local, and both produce static CSS. The difference is what you write. With CSS Modules you author .module.css and get no type checking on property names or values; with vanilla-extract you author .css.ts and the TypeScript compiler checks the object you pass to style(). The theme system is the other gap: CSS Modules variables are global by convention, while createTheme returns a scoped vars object.

Against runtime CSS-in-JS libraries, the trade is reversed. A runtime library lets you compute a style from props at render time and inject it, which vanilla-extract cannot do without the optional runtime API. In exchange, vanilla-extract ships no styling runtime, so the JavaScript bundle does not carry style objects or an injection layer. The README also points to Sprinkles, its atomic CSS framework built on top of vanilla-extract, for teams that want a utility-class workflow with the same build-time guarantees.

Maintenance, versioning and the MIT licence

The repository is a pnpm workspace with packages, examples, fixtures, tests and a site directory, and it uses Changesets for releases: the version script runs changeset version, and release runs changeset publish. That explains why @vanilla-extract/vite-plugin and @vanilla-extract/sprinkles carry independent version numbers rather than moving together. For adopters, the practical consequence is that upgrading the core package and a plugin are separate decisions, and a plugin release may land on a different date from the core.

The last push was on 2026-08-27, so the project has recent activity. The repository is not archived. Maintenance cost for you is mostly build configuration: when you change bundlers or major framework versions, the plugin is what needs checking. The licence is MIT, which permits commercial use and modification provided the copyright notice and permission notice are retained; this is a description of the licence text, not legal advice, and you should read LICENSE in the repository for the exact terms.

Editorial conclusion

Adopt vanilla-extract when you want typed, locally scoped styles and are willing to wire a build plugin into Vite, webpack, Next.js or another bundler; the README points to the documentation site for setup guides and to examples/webpack-react and examples/next for working configurations. Do not adopt it if you need styles computed from state that is only known at runtime, or if your team will not maintain build configuration, because every .css.ts file depends on that plugin being present. Before committing, verify the plugin package for your bundler exists under packages/ and is published, confirm your framework version against the fixtures in examples/, and check the docs for the escape hatch you need for dynamic values. The MIT licence imposes no distribution conditions beyond keeping the notice.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. vanilla-extract-css/vanilla-extract on GitHub