0
# Plugin Configuration
1

2
Comprehensive configuration options for controlling CSS injection behavior, asset filtering, and processing pipelines.
3

4
## Capabilities
5

6
### Main Configuration Interface
7

8
Complete configuration interface extending base options with asset filtering and processing controls.
9

10
```typescript { .api }
11
/**
12
 * Main plugin configuration interface
13
 */
14
interface PluginConfiguration extends BaseOptions {
15
  /** Filter function to exclude specific CSS assets from injection */
16
  cssAssetsFilterFunction?: (chunk: OutputAsset) => boolean;
17
  /** Filter function to specify target JavaScript files for injection */
18
  jsAssetsFilterFunction?: (chunk: OutputChunk) => boolean;
19
  /** Pre-process CSS code before injection */
20
  preRenderCSSCode?: (cssCode: string) => string;
21
  /** Enable relative CSS injection per entry point */
22
  relativeCSSInjection?: boolean;
23
  /** Suppress warnings for unused CSS assets */
24
  suppressUnusedCssWarning?: boolean;
25
}
26

27
interface BaseOptions {
28
  /** Development mode configuration (experimental) */
29
  dev?: DevOptions;
30
  /** Custom CSS injection code function */
31
  injectCode?: InjectCode;
32
  /** Custom CSS injection runtime function */
33
  injectCodeFunction?: InjectCodeFunction;
34
  /** Format for injection code generation */
35
  injectionCodeFormat?: ModuleFormat;
36
  /** Custom style element ID or generator function */
37
  styleId?: string | (() => string);
38
  /** Execute CSS injection before app code */
39
  topExecutionPriority?: boolean;
40
  /** Enable strict CSP support with nonce */
41
  useStrictCSP?: boolean;
42
}
43
```
44

45
**Usage Examples:**
46

47
```typescript
48
import { defineConfig } from "vite";
49
import cssInjectedByJsPlugin from "vite-plugin-css-injected-by-js";
50

51
// Basic configuration
52
export default defineConfig({
53
  plugins: [
54
    cssInjectedByJsPlugin({
55
      styleId: "app-styles",
56
      topExecutionPriority: false,
57
    }),
58
  ],
59
});
60

61
// Advanced configuration with filtering
62
export default defineConfig({
63
  plugins: [
64
    cssInjectedByJsPlugin({
65
      cssAssetsFilterFunction: (asset) => {
66
        // Only inject specific CSS files
67
        return asset.fileName.includes("critical");
68
      },
69
      jsAssetsFilterFunction: (chunk) => {
70
        // Target specific JavaScript files
71
        return chunk.fileName === "main.js";
72
      },
73
      preRenderCSSCode: (css) => {
74
        // Minify or transform CSS before injection
75
        return css.replace(/\s+/g, " ").trim();
76
      },
77
    }),
78
  ],
79
});
80
```
81

82
### CSS Asset Filtering
83

84
Filter function to control which CSS assets are processed for injection.
85

86
```typescript { .api }
87
/**
88
 * Filter function to exclude specific CSS assets from injection
89
 * @param chunk - Output CSS asset to evaluate
90
 * @returns true to include asset, false to exclude
91
 */
92
cssAssetsFilterFunction?: (chunk: OutputAsset) => boolean;
93
```
94

95
**Usage Examples:**
96

97
```typescript
98
// Include only specific CSS files
99
cssAssetsFilterFunction: (asset) => {
100
  return asset.fileName.includes("critical") || 
101
         asset.fileName.includes("main");
102
}
103

104
// Exclude third-party CSS
105
cssAssetsFilterFunction: (asset) => {
106
  return !asset.fileName.includes("vendor");
107
}
108
```
109

110
### JavaScript Asset Filtering
111

112
Filter function to specify which JavaScript files receive the CSS injection code.
113

114
```typescript { .api }
115
/**
116
 * Filter function to specify target JavaScript files for injection
117
 * @param chunk - Output JavaScript chunk to evaluate
118
 * @returns true to inject CSS into this chunk, false to skip
119
 */
120
jsAssetsFilterFunction?: (chunk: OutputChunk) => boolean;
121
```
122

123
**Usage Examples:**
124

125
```typescript
126
// Inject into main entry point only
127
jsAssetsFilterFunction: (chunk) => {
128
  return chunk.fileName === "index.js";
129
}
130

131
// Inject into multiple specific files
132
jsAssetsFilterFunction: (chunk) => {
133
  return chunk.fileName === "main.js" || 
134
         chunk.fileName === "app.js";
135
}
136
```
137

138
### CSS Pre-processing
139

140
Transform CSS code before it's injected into JavaScript.
141

142
```typescript { .api }
143
/**
144
 * Pre-process CSS code before injection
145
 * @param cssCode - Raw CSS code extracted from build
146
 * @returns Modified CSS code to be injected
147
 */
148
preRenderCSSCode?: (cssCode: string) => string;
149
```
150

151
**Usage Examples:**
152

153
```typescript
154
// Minify CSS before injection
155
preRenderCSSCode: (css) => {
156
  return css
157
    .replace(/\/\*[\s\S]*?\*\//g, "") // Remove comments
158
    .replace(/\s+/g, " ") // Collapse whitespace
159
    .trim();
160
}
161

162
// Add custom CSS transformations
163
preRenderCSSCode: (css) => {
164
  // Add custom prefix or modifications
165
  return `:root { --injected: true; }\n${css}`;
166
}
167
```
168

169
### Relative CSS Injection
170

171
Enable per-entry-point CSS injection based on import relationships.
172

173
```typescript { .api }
174
/**
175
 * Enable relative CSS injection per entry point
176
 * Requires build.cssCodeSplit to be true
177
 */
178
relativeCSSInjection?: boolean;
179
```
180

181
**Usage Examples:**
182

183
```typescript
184
// Enable relative injection for multi-entry builds
185
export default defineConfig({
186
  build: {
187
    cssCodeSplit: true, // Required for relative injection
188
    rollupOptions: {
189
      input: {
190
        main: "src/main.ts",
191
        admin: "src/admin.ts",
192
      },
193
    },
194
  },
195
  plugins: [
196
    cssInjectedByJsPlugin({
197
      relativeCSSInjection: true,
198
      suppressUnusedCssWarning: true,
199
    }),
200
  ],
201
});
202
```
203

204
### Style Element Configuration
205

206
Configure the injected style element's ID and attributes.
207

208
```typescript { .api }
209
/**
210
 * Custom style element ID or generator function
211
 */
212
styleId?: string | (() => string);
213
```
214

215
**Usage Examples:**
216

217
```typescript
218
// Static style ID
219
styleId: "my-app-styles"
220

221
// Dynamic style ID (useful with relative injection)
222
styleId: () => `styles-${Date.now()}`
223

224
// Random style ID for each injection
225
styleId: () => `app-${Math.random().toString(36).substr(2, 9)}`
226
```
227

228
### Execution Priority
229

230
Control when CSS injection code executes relative to application code.
231

232
```typescript { .api }
233
/**
234
 * Execute CSS injection before app code
235
 * @default true
236
 */
237
topExecutionPriority?: boolean;
238
```
239

240
**Usage Examples:**
241

242
```typescript
243
// Inject CSS after app initialization
244
topExecutionPriority: false
245

246
// Inject CSS before app code (default)
247
topExecutionPriority: true
248
```
249

250
### Content Security Policy Support
251

252
Enable CSP-compliant CSS injection with nonce support.
253

254
```typescript { .api }
255
/**
256
 * Enable strict CSP support with nonce
257
 * Requires <meta property="csp-nonce" content="nonce-value" /> in HTML
258
 */
259
useStrictCSP?: boolean;
260
```
261

262
**Usage Examples:**
263

264
```typescript
265
// Enable CSP support
266
useStrictCSP: true
267

268
// HTML page must include:
269
// <meta property="csp-nonce" content="your-nonce-here" />
270
```
271

272
### Code Format Configuration
273

274
Specify the format for generated injection code.
275

276
```typescript { .api }
277
/**
278
 * Format for injection code generation
279
 * @default "iife"
280
 */
281
injectionCodeFormat?: ModuleFormat;
282
```
283

284
**Usage Examples:**
285

286
```typescript
287
// Use IIFE format (default)
288
injectionCodeFormat: "iife"
289

290
// Use ES modules format
291
injectionCodeFormat: "es"
292

293
// Use CommonJS format
294
injectionCodeFormat: "cjs"
295
```