or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-vanilla-extract--vite-plugin

Zero-runtime Stylesheets-in-TypeScript Vite plugin for vanilla-extract CSS processing

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@vanilla-extract/vite-plugin@5.1.x

To install, run

npx @tessl/cli install tessl/npm-vanilla-extract--vite-plugin@5.1.0

index.mddocs/

Vanilla Extract Vite Plugin

The @vanilla-extract/vite-plugin enables zero-runtime CSS-in-TypeScript within Vite-based projects. It processes .css.ts files at build time to generate static CSS while providing locally scoped class names, CSS variables, and theme support without runtime overhead.

Package Information

  • Package Name: @vanilla-extract/vite-plugin
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @vanilla-extract/vite-plugin

Core Imports

import { vanillaExtractPlugin } from "@vanilla-extract/vite-plugin";

For CommonJS:

const { vanillaExtractPlugin } = require("@vanilla-extract/vite-plugin");

Basic Usage

// vite.config.ts
import { defineConfig } from "vite";
import { vanillaExtractPlugin } from "@vanilla-extract/vite-plugin";

export default defineConfig({
  plugins: [
    vanillaExtractPlugin({
      identifiers: "short"
    })
  ]
});
// styles.css.ts
import { style } from "@vanilla-extract/css";

export const button = style({
  padding: "10px 20px",
  backgroundColor: "blue",
  color: "white",
  border: "none",
  borderRadius: "4px"
});
// component.tsx
import { button } from "./styles.css.ts";

export function Button() {
  return <button className={button}>Click me</button>;
}

Capabilities

Plugin Factory Function

Creates a Vite plugin array for vanilla-extract integration.

/**
 * Creates Vite plugins for vanilla-extract CSS-in-TypeScript processing
 * @param options - Optional configuration for the plugin
 * @returns Array of Vite plugins for vanilla-extract integration
 */
function vanillaExtractPlugin(options?: Options): Plugin[];

/** Vite plugin interface from the Vite build tool */
interface Plugin {
  name: string;
  [key: string]: any;
}

interface Options {
  /** Controls how CSS class names are generated */
  identifiers?: IdentifierOption;
  /** Filter function to control which plugins are used with vite-node compiler */
  unstable_pluginFilter?: PluginFilter;
  /** Processing mode for the plugin */
  unstable_mode?: "transform" | "emitCss" | "inlineCssInDev";
}

Plugin Filter Function

Function type for filtering plugins during compilation.

/**
 * Function type for filtering plugins during vanilla-extract compilation
 * @param filterProps - Object containing plugin name and mode
 * @returns Boolean indicating whether to include the plugin
 */
type PluginFilter = (filterProps: {
  /** The name of the plugin */
  name: string;
  /** The mode vite is running in (development/production) */
  mode: string;
}) => boolean;

Identifier Options

Controls class name generation strategy.

/** Class name identifier generation strategies */
type IdentifierOption = "short" | "debug" | CustomIdentFunction;

/** Custom identifier function for advanced class name generation */
type CustomIdentFunction = (params: {
  hash: string;
  filePath: string;
  debugId?: string;
  packageName?: string;
}) => string;

Processing Modes

The plugin supports three different processing modes:

/** Available processing modes for vanilla-extract */
type ProcessingMode = "transform" | "emitCss" | "inlineCssInDev";

Processing Mode Details:

  • "emitCss" (default): Generates and emits separate CSS files during build
  • "transform": Transforms files inline without separate CSS emission
  • "inlineCssInDev": Inlines CSS in development mode to prevent FOUC during SSR

Plugin Configuration Examples

Basic Configuration:

import { vanillaExtractPlugin } from "@vanilla-extract/vite-plugin";

export default {
  plugins: [vanillaExtractPlugin()]
};

Production-optimized Configuration:

import { vanillaExtractPlugin } from "@vanilla-extract/vite-plugin";

export default {
  plugins: [
    vanillaExtractPlugin({
      identifiers: "short"
    })
  ]
};

Development Configuration with FOUC Prevention:

import { vanillaExtractPlugin } from "@vanilla-extract/vite-plugin";

export default {
  plugins: [
    vanillaExtractPlugin({
      identifiers: "debug",
      unstable_mode: "inlineCssInDev"
    })
  ]
};

Custom Plugin Filtering:

import { vanillaExtractPlugin } from "@vanilla-extract/vite-plugin";

export default {
  plugins: [
    vanillaExtractPlugin({
      unstable_pluginFilter: ({ name, mode }) => {
        // Allow additional plugins in development
        if (mode === "development") {
          return ["vite-tsconfig-paths", "vite-plugin-react"].includes(name);
        }
        // Be more restrictive in production
        return ["vite-tsconfig-paths"].includes(name);
      }
    })
  ]
};

Custom Identifier Function:

import { vanillaExtractPlugin } from "@vanilla-extract/vite-plugin";

export default {
  plugins: [
    vanillaExtractPlugin({
      identifiers: ({ hash, filePath, debugId, packageName }) => {
        // Custom naming strategy
        return `${packageName}_${debugId}_${hash.slice(0, 8)}`;
      }
    })
  ]
};

Transform Mode Usage

For build tools that need inline transformation:

import { vanillaExtractPlugin } from "@vanilla-extract/vite-plugin";

export default {
  plugins: [
    vanillaExtractPlugin({
      unstable_mode: "transform"
    })
  ]
};

Integration Notes

File Extensions

The plugin processes files with .css.ts and .css.js extensions, transforming them into static CSS at build time.

Virtual CSS Files

The plugin creates virtual CSS files with .vanilla.css extension internally to handle generated CSS within Vite's module system.

Hot Module Replacement

Full HMR support is provided in development mode, with automatic invalidation of dependent modules when CSS files change.

SSR Compatibility

The plugin includes special handling for server-side rendering scenarios, with the inlineCssInDev mode specifically designed to prevent FOUC (Flash of Unstyled Content) during SSR.

Dependencies

The plugin depends on:

  • @vanilla-extract/compiler - Core compilation engine
  • @vanilla-extract/integration - Shared integration utilities
  • vite - The Vite build tool (peer dependency)