0
# Main Plugin Configuration
1

2
Core plugin factory function that creates the Vite plugin array for handling Svelte files in development and build processes.
3

4
## Capabilities
5

6
### Svelte Plugin Factory
7

8
Creates an array of specialized Vite plugins that handle different aspects of Svelte file processing.
9

10
```typescript { .api }
11
/**
12
 * Returns a list of plugins to handle svelte files
13
 * plugins are named `vite-plugin-svelte:<task>`
14
 * 
15
 * @param inlineOptions - Optional configuration options
16
 * @returns Array of Vite plugins for Svelte file processing
17
 */
18
function svelte(inlineOptions?: Partial<Options>): Plugin[];
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
// Basic usage
25
import { svelte } from '@sveltejs/vite-plugin-svelte';
26

27
export default {
28
  plugins: [svelte()]
29
};
30

31
// With configuration
32
export default {
33
  plugins: [
34
    svelte({
35
      emitCss: true,
36
      compilerOptions: {
37
        dev: true,
38
        runes: true
39
      },
40
      preprocess: vitePreprocess({
41
        style: true
42
      })
43
    })
44
  ]
45
};
46

47
// Production build configuration
48
export default {
49
  plugins: [
50
    svelte({
51
      emitCss: true,
52
      hot: false,
53
      compilerOptions: {
54
        dev: false
55
      },
56
      prebundleSvelteLibraries: false
57
    })
58
  ]
59
};
60
```
61

62
## Plugin Options
63

64
### File Processing Options
65

66
Configure which files the plugin processes and how.
67

68
```typescript { .api }
69
interface FileProcessingOptions {
70
  /** A picomatch pattern or array of patterns specifying files to include */
71
  include?: Arrayable<string | RegExp>;
72
  /** A picomatch pattern or array of patterns specifying files to exclude */
73
  exclude?: Arrayable<string | RegExp>;
74
}
75
```
76

77
**Usage Examples:**
78

79
```javascript
80
svelte({
81
  include: ['src/**/*.svelte'],
82
  exclude: ['node_modules/**', 'src/**/*.test.svelte']
83
});
84

85
// Using RegExp patterns
86
svelte({
87
  include: [/\.svelte$/, /\.svelte\.ts$/],
88
  exclude: [/node_modules/, /\.test\./]
89
});
90
```
91

92
### CSS Handling Options
93

94
Control how Svelte component styles are processed and emitted.
95

96
```typescript { .api }
97
interface CssOptions {
98
  /** Emit Svelte styles as virtual CSS files for Vite and other plugins to process */
99
  emitCss?: boolean; // default: true
100
}
101
```
102

103
**Usage Examples:**
104

105
```javascript
106
// Enable CSS emission (default)
107
svelte({ emitCss: true });
108

109
// Disable CSS emission (styles remain in component)
110
svelte({ emitCss: false });
111
```
112

113
### Hot Module Replacement Options
114

115
Configure development-time hot reload behavior.
116

117
```typescript { .api }
118
interface HmrOptions {
119
  /** 
120
   * Enable or disable Hot Module Replacement
121
   * @deprecated Use compilerOptions.hmr instead
122
   * @default true for development, always false for production
123
   */
124
  hot?: boolean;
125
}
126
```
127

128
**Usage Examples:**
129

130
```javascript
131
// Preferred approach (not deprecated)
132
svelte({
133
  compilerOptions: {
134
    hmr: process.env.NODE_ENV === 'development'
135
  }
136
});
137

138
// Deprecated approach (still works)
139
svelte({
140
  hot: process.env.NODE_ENV === 'development'
141
});
142
```
143

144
### Preprocessor Integration Options
145

146
Control how the plugin interacts with preprocessors from other Vite plugins.
147

148
```typescript { .api }
149
interface PreprocessorOptions {
150
  /** 
151
   * Ignore preprocessors contributed by other Vite plugins
152
   * - true: ignore all plugin preprocessors
153
   * - string[]: ignore preprocessors from specific plugins
154
   * @default false
155
   */
156
  ignorePluginPreprocessors?: boolean | string[];
157
}
158
```
159

160
**Usage Examples:**
161

162
```javascript
163
// Ignore all plugin preprocessors
164
svelte({ ignorePluginPreprocessors: true });
165

166
// Ignore specific plugins
167
svelte({ 
168
  ignorePluginPreprocessors: ['vite-plugin-windicss', 'other-plugin'] 
169
});
170
```
171

172
### Dependency Optimization Options
173

174
Control automatic handling of Svelte library dependencies.
175

176
```typescript { .api }
177
interface DependencyOptions {
178
  /** 
179
   * Control automatic dependency reinclusion in vite.optimizeDeps
180
   * - true: disable all reinclusions
181
   * - string[]: disable reinclusions for specific dependencies
182
   * @default false
183
   */
184
  disableDependencyReinclusion?: boolean | string[];
185
  
186
  /** 
187
   * Enable dependency optimization to prebundle Svelte libraries
188
   * @default true for dev, false for build
189
   */
190
  prebundleSvelteLibraries?: boolean;
191
}
192
```
193

194
**Usage Examples:**
195

196
```javascript
197
// Disable all dependency reinclusion
198
svelte({ disableDependencyReinclusion: true });
199

200
// Disable for specific hybrid packages
201
svelte({ 
202
  disableDependencyReinclusion: ['@routify/router', 'some-hybrid-package'] 
203
});
204

205
// Control prebundling
206
svelte({
207
  prebundleSvelteLibraries: process.env.NODE_ENV === 'development'
208
});
209
```
210

211
### Inspector Integration Options
212

213
Configure Svelte Inspector for development debugging.
214

215
```typescript { .api }
216
interface InspectorOptions {
217
  /** 
218
   * Toggle or configure Svelte Inspector
219
   * @default unset for dev, always false for build
220
   */
221
  inspector?: InspectorOptions | boolean;
222
}
223
```
224

225
**Usage Examples:**
226

227
```javascript
228
// Enable inspector (default in development)
229
svelte({ inspector: true });
230

231
// Disable inspector
232
svelte({ inspector: false });
233

234
// Configure inspector options
235
svelte({
236
  inspector: {
237
    toggleKeyCombo: 'control-shift',
238
    holdMode: true,
239
    showToggleButton: 'always'
240
  }
241
});
242
```
243

244
### Dynamic Compilation Options
245

246
Provide per-file dynamic compiler configuration.
247

248
```typescript { .api }
249
interface DynamicCompileOptions {
250
  /** 
251
   * Function to update compilerOptions before compilation
252
   * @param data - Compilation context data
253
   * @returns Partial compiler options to merge
254
   */
255
  dynamicCompileOptions?: (data: {
256
    filename: string;
257
    code: string;
258
    compileOptions: Partial<CompileOptions>;
259
  }) => Promise<Partial<CompileOptions> | void> | Partial<CompileOptions> | void;
260
}
261
```
262

263
**Usage Examples:**
264

265
```javascript
266
svelte({
267
  dynamicCompileOptions({ filename, compileOptions }) {
268
    // Enable runes mode for specific files
269
    if (filename.includes('.runes.svelte')) {
270
      return { runes: true };
271
    }
272
    
273
    // Different settings for test files
274
    if (filename.includes('.test.svelte')) {
275
      return { 
276
        dev: true,
277
        hydratable: false 
278
      };
279
    }
280
  }
281
});
282

283
// Async dynamic options
284
svelte({
285
  async dynamicCompileOptions({ filename, code }) {
286
    const config = await loadFileSpecificConfig(filename);
287
    return config.compilerOptions;
288
  }
289
});
290
```
291

292
### Configuration File Options
293

294
Control Svelte configuration file loading.
295

296
```typescript { .api }
297
interface ConfigFileOptions {
298
  /** 
299
   * Path to svelte config file, absolute or relative to Vite root
300
   * Set to false to ignore svelte config file
301
   */
302
  configFile?: string | false;
303
}
304
```
305

306
**Usage Examples:**
307

308
```javascript
309
// Use custom config file path
310
svelte({ configFile: './config/svelte.config.js' });
311

312
// Use absolute path
313
svelte({ configFile: '/path/to/project/custom.svelte.config.js' });
314

315
// Ignore svelte config file completely
316
svelte({ configFile: false });
317
```
318

319
## Experimental Features
320

321
### Experimental Options
322

323
Features that may have breaking changes in future releases.
324

325
```typescript { .api }
326
interface ExperimentalOptions {
327
  /** Send websocket message with svelte compiler warnings during dev */
328
  sendWarningsToBrowser?: boolean;
329
  /** Disable svelte field resolve warnings */
330
  disableSvelteResolveWarnings?: boolean;
331
  /** Disable api.sveltePreprocess deprecation warnings */
332
  disableApiSveltePreprocessWarnings?: boolean;
333
  /** Module compilation configuration */
334
  compileModule?: CompileModuleOptions;
335
}
336

337
interface CompileModuleOptions {
338
  /** Infix that must be present in filename (default: ['.svelte.']) */
339
  infixes?: string[];
340
  /** Module extensions (default: ['.ts', '.js']) */
341
  extensions?: string[];
342
  /** Include patterns */
343
  include?: Arrayable<string | RegExp>;
344
  /** Exclude patterns */
345
  exclude?: Arrayable<string | RegExp>;
346
}
347
```
348

349
**Usage Examples:**
350

351
```javascript
352
svelte({
353
  experimental: {
354
    // Send warnings to browser console during development
355
    sendWarningsToBrowser: true,
356
    
357
    // Suppress specific warning types
358
    disableSvelteResolveWarnings: true,
359
    disableApiSveltePreprocessWarnings: true,
360
    
361
    // Configure module compilation
362
    compileModule: {
363
      infixes: ['.svelte.', '.component.'],
364
      extensions: ['.ts', '.js', '.mjs'],
365
      include: ['src/modules/**'],
366
      exclude: ['**/*.test.*']
367
    }
368
  }
369
});
370
```