# Vanilla Extract — Zero-Runtime CSS-in-TypeScript

> A CSS-in-TypeScript framework that generates static CSS at build time, providing type-safe styling with zero runtime overhead.

## Install

Save as a script file and run:

# Vanilla Extract — Zero-Runtime CSS-in-TypeScript

## Quick Use
```bash
npm install @vanilla-extract/css
```
```ts
// styles.css.ts
import { style } from "@vanilla-extract/css";

export const button = style({
  backgroundColor: "blue",
  color: "white",
  padding: "8px 16px",
  borderRadius: "4px",
  ":hover": { backgroundColor: "darkblue" }
});
```
```tsx
import { button } from "./styles.css";
export default () => <button className={button}>Click me</button>;
```

## Introduction
Vanilla Extract is a CSS authoring framework that lets you write styles in TypeScript files (`.css.ts`) and compiles them to static CSS at build time. You get full type safety, autocomplete, and theming capabilities without shipping any CSS runtime to the browser.

## What Vanilla Extract Does
- Generates static CSS files from TypeScript style definitions at build time
- Provides type-safe APIs for styles, themes, and design tokens
- Supports theming via CSS custom properties with contract-based type checking
- Offers a Sprinkles utility for building type-safe atomic CSS functions
- Integrates with Vite, Webpack, esbuild, and Next.js via official plugins

## Architecture Overview
Style files (`.css.ts`) are evaluated at build time by a bundler plugin. The plugin extracts all `style()`, `globalStyle()`, and `createTheme()` calls, generates corresponding CSS, and replaces the TypeScript exports with hashed class name strings. The output is plain CSS with no runtime JavaScript, so the styles have zero impact on client bundle size.

## Self-Hosting & Configuration
- Install `@vanilla-extract/css` and the plugin for your bundler (e.g., `@vanilla-extract/vite-plugin`)
- Add the plugin to your build configuration (Vite, Webpack, or esbuild)
- Create `.css.ts` files alongside your components for co-located styling
- Define themes with `createTheme()` and `createThemeContract()` for type-safe design tokens
- Use `@vanilla-extract/sprinkles` to create utility-class functions like a typed Tailwind

## Key Features
- Full TypeScript autocomplete and compile-time error checking for all style properties
- Zero runtime cost since all CSS is extracted at build time
- Theme contracts that enforce consistent token usage across themes
- Recipes API for building variant-based component styles (similar to CVA)
- Locally scoped class names by default to prevent style collisions

## Comparison with Similar Tools
- **CSS Modules** — Also locally scoped, but no type safety or theming primitives
- **Tailwind CSS** — Utility-first approach; Vanilla Extract provides type-safe authoring in TS
- **Styled Components / Emotion** — Runtime CSS-in-JS with bundle cost; Vanilla Extract has zero runtime
- **Linaria** — Similar zero-runtime goal; Vanilla Extract has a richer theming and Sprinkles API
- **Panda CSS** — Newer utility-first zero-runtime library; Vanilla Extract is more established

## FAQ
**Q: Does Vanilla Extract work with Next.js?**
A: Yes. Use the `@vanilla-extract/next-plugin` to add support to your Next.js project.

**Q: Can I use media queries and pseudo-selectors?**
A: Yes. Nest them inside the `style()` call using keys like `@media`, `:hover`, and `:focus`.

**Q: How does theming work?**
A: Define a theme contract with `createThemeContract()`, then create concrete themes with `createTheme()`. Components reference contract variables and the active theme is applied via a class on a parent element.

**Q: Is there a performance benefit over runtime CSS-in-JS?**
A: Yes. Since all CSS is pre-generated, there is no style injection or serialization at runtime, reducing JavaScript execution and improving time-to-interactive.

## Sources
- https://github.com/vanilla-extract-css/vanilla-extract
- https://vanilla-extract.style

---
Source: https://tokrepo.com/en/workflows/asset-be1d0d8c
Author: Script Depot