vanilla-extract — Zero-Runtime Type-Safe CSS in TypeScript

Introduction

vanilla-extract is a CSS-in-TypeScript authoring framework that runs entirely at build time. You write styles in .css.ts files using TypeScript, and the compiler generates plain CSS files with locally scoped class names. There is no runtime JavaScript for styling—just static CSS. The project was created by Mark Dalgleish, co-creator of CSS Modules.

What vanilla-extract Does

• Generates static CSS at build time from TypeScript style definitions
• Provides type-safe APIs for styles, themes, and design tokens with full autocomplete
• Supports theming through type-safe theme contracts and CSS variables
• Offers Sprinkles, an optional utility-class API similar to Tailwind but type-checked
• Produces standard CSS files compatible with any server or client rendering setup

Architecture Overview

vanilla-extract uses a build plugin (available for Webpack, Vite, esbuild, and Next.js) to evaluate .css.ts files at compile time. The plugin runs the TypeScript in a sandboxed context, collects the generated styles, and emits plain .css files. Class names are locally scoped by default through hashing. The Sprinkles package pre-generates atomic utility classes from a configured design system, enabling conditional styles without runtime computation.

Self-Hosting & Configuration

• Install the core package and the bundler integration for your build tool (Vite, Webpack, Next.js, or esbuild)
• Create .css.ts files alongside your components; the build plugin picks them up automatically
• Define a theme contract with createThemeContract and implement variants with createTheme
• Use Sprinkles to generate a type-safe utility-class system from your design tokens
• No special deployment steps; output is standard CSS files served like any stylesheet

Key Features

• True zero runtime: no JavaScript is injected for styling at any point
• Full TypeScript type safety with autocomplete for every CSS property and value
• Theme contracts enforce that every theme implements the same set of variables
• Sprinkles API enables Tailwind-like utility classes with compile-time type checking
• 10k+ GitHub stars with integrations for every major bundler

Comparison with Similar Tools

• CSS Modules — also locally scoped but uses plain CSS without type safety; vanilla-extract adds TypeScript types and theming
• Tailwind CSS — utility classes in HTML; vanilla-extract keeps styles in TypeScript with type-checked tokens
• styled-components — runtime CSS-in-JS with a small overhead; vanilla-extract has zero runtime
• Panda CSS — also zero-runtime with utility classes; vanilla-extract focuses on explicit style definitions over atomic utilities

FAQ

Q: Does vanilla-extract work with Next.js App Router? A: Yes. The official @vanilla-extract/next-plugin integrates with both Pages and App Router.

Q: Is there any JavaScript added to my bundle for styling? A: No. All CSS is generated at build time and shipped as static .css files. The only JS is the class name imports.

Q: Can I use media queries and pseudo-selectors? A: Yes. The style function supports @media, @supports, selectors, and pseudo-classes through a nested object syntax.

Q: How does it compare to Emotion or styled-components in bundle size? A: vanilla-extract adds zero bytes of runtime JavaScript. Emotion and styled-components add 8-15 KB gzipped of runtime.

Sources

• https://github.com/vanilla-extract-css/vanilla-extract
• https://vanilla-extract.style/