0
# Vanilla Extract Vite Plugin
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @vanilla-extract/vite-plugin
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @vanilla-extract/vite-plugin`
10

11
## Core Imports
12

13
```typescript
14
import { vanillaExtractPlugin } from "@vanilla-extract/vite-plugin";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { vanillaExtractPlugin } = require("@vanilla-extract/vite-plugin");
21
```
22

23
## Basic Usage
24

25
```typescript
26
// vite.config.ts
27
import { defineConfig } from "vite";
28
import { vanillaExtractPlugin } from "@vanilla-extract/vite-plugin";
29

30
export default defineConfig({
31
  plugins: [
32
    vanillaExtractPlugin({
33
      identifiers: "short"
34
    })
35
  ]
36
});
37
```
38

39
```typescript
40
// styles.css.ts
41
import { style } from "@vanilla-extract/css";
42

43
export const button = style({
44
  padding: "10px 20px",
45
  backgroundColor: "blue",
46
  color: "white",
47
  border: "none",
48
  borderRadius: "4px"
49
});
50
```
51

52
```typescript
53
// component.tsx
54
import { button } from "./styles.css.ts";
55

56
export function Button() {
57
  return <button className={button}>Click me</button>;
58
}
59
```
60

61
## Capabilities
62

63
### Plugin Factory Function
64

65
Creates a Vite plugin array for vanilla-extract integration.
66

67
```typescript { .api }
68
/**
69
 * Creates Vite plugins for vanilla-extract CSS-in-TypeScript processing
70
 * @param options - Optional configuration for the plugin
71
 * @returns Array of Vite plugins for vanilla-extract integration
72
 */
73
function vanillaExtractPlugin(options?: Options): Plugin[];
74

75
/** Vite plugin interface from the Vite build tool */
76
interface Plugin {
77
  name: string;
78
  [key: string]: any;
79
}
80

81
interface Options {
82
  /** Controls how CSS class names are generated */
83
  identifiers?: IdentifierOption;
84
  /** Filter function to control which plugins are used with vite-node compiler */
85
  unstable_pluginFilter?: PluginFilter;
86
  /** Processing mode for the plugin */
87
  unstable_mode?: "transform" | "emitCss" | "inlineCssInDev";
88
}
89
```
90

91
### Plugin Filter Function
92

93
Function type for filtering plugins during compilation.
94

95
```typescript { .api }
96
/**
97
 * Function type for filtering plugins during vanilla-extract compilation
98
 * @param filterProps - Object containing plugin name and mode
99
 * @returns Boolean indicating whether to include the plugin
100
 */
101
type PluginFilter = (filterProps: {
102
  /** The name of the plugin */
103
  name: string;
104
  /** The mode vite is running in (development/production) */
105
  mode: string;
106
}) => boolean;
107
```
108

109
### Identifier Options
110

111
Controls class name generation strategy.
112

113
```typescript { .api }
114
/** Class name identifier generation strategies */
115
type IdentifierOption = "short" | "debug" | CustomIdentFunction;
116

117
/** Custom identifier function for advanced class name generation */
118
type CustomIdentFunction = (params: {
119
  hash: string;
120
  filePath: string;
121
  debugId?: string;
122
  packageName?: string;
123
}) => string;
124
```
125

126
### Processing Modes
127

128
The plugin supports three different processing modes:
129

130
```typescript { .api }
131
/** Available processing modes for vanilla-extract */
132
type ProcessingMode = "transform" | "emitCss" | "inlineCssInDev";
133
```
134

135
**Processing Mode Details:**
136

137
- **`"emitCss"`** (default): Generates and emits separate CSS files during build
138
- **`"transform"`**: Transforms files inline without separate CSS emission
139
- **`"inlineCssInDev"`**: Inlines CSS in development mode to prevent FOUC during SSR
140

141
### Plugin Configuration Examples
142

143
**Basic Configuration:**
144

145
```typescript
146
import { vanillaExtractPlugin } from "@vanilla-extract/vite-plugin";
147

148
export default {
149
  plugins: [vanillaExtractPlugin()]
150
};
151
```
152

153
**Production-optimized Configuration:**
154

155
```typescript
156
import { vanillaExtractPlugin } from "@vanilla-extract/vite-plugin";
157

158
export default {
159
  plugins: [
160
    vanillaExtractPlugin({
161
      identifiers: "short"
162
    })
163
  ]
164
};
165
```
166

167
**Development Configuration with FOUC Prevention:**
168

169
```typescript
170
import { vanillaExtractPlugin } from "@vanilla-extract/vite-plugin";
171

172
export default {
173
  plugins: [
174
    vanillaExtractPlugin({
175
      identifiers: "debug",
176
      unstable_mode: "inlineCssInDev"
177
    })
178
  ]
179
};
180
```
181

182
**Custom Plugin Filtering:**
183

184
```typescript
185
import { vanillaExtractPlugin } from "@vanilla-extract/vite-plugin";
186

187
export default {
188
  plugins: [
189
    vanillaExtractPlugin({
190
      unstable_pluginFilter: ({ name, mode }) => {
191
        // Allow additional plugins in development
192
        if (mode === "development") {
193
          return ["vite-tsconfig-paths", "vite-plugin-react"].includes(name);
194
        }
195
        // Be more restrictive in production
196
        return ["vite-tsconfig-paths"].includes(name);
197
      }
198
    })
199
  ]
200
};
201
```
202

203
**Custom Identifier Function:**
204

205
```typescript
206
import { vanillaExtractPlugin } from "@vanilla-extract/vite-plugin";
207

208
export default {
209
  plugins: [
210
    vanillaExtractPlugin({
211
      identifiers: ({ hash, filePath, debugId, packageName }) => {
212
        // Custom naming strategy
213
        return `${packageName}_${debugId}_${hash.slice(0, 8)}`;
214
      }
215
    })
216
  ]
217
};
218
```
219

220
### Transform Mode Usage
221

222
For build tools that need inline transformation:
223

224
```typescript
225
import { vanillaExtractPlugin } from "@vanilla-extract/vite-plugin";
226

227
export default {
228
  plugins: [
229
    vanillaExtractPlugin({
230
      unstable_mode: "transform"
231
    })
232
  ]
233
};
234
```
235

236
## Integration Notes
237

238
### File Extensions
239

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

242
### Virtual CSS Files
243

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

246
### Hot Module Replacement
247

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

250
### SSR Compatibility
251

252
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.
253

254
### Dependencies
255

256
The plugin depends on:
257
- `@vanilla-extract/compiler` - Core compilation engine
258
- `@vanilla-extract/integration` - Shared integration utilities
259
- `vite` - The Vite build tool (peer dependency)