0
# Configuration Management
1

2
Utilities for loading and parsing Svelte configuration files in various build scenarios. This module provides functions to discover, load, and process Svelte configuration files that integrate with Vite's configuration system.
3

4
## Capabilities
5

6
### Svelte Config Loading
7

8
Load and parse Svelte configuration files with automatic discovery and validation.
9

10
```typescript { .api }
11
/**
12
 * Loads and parses Svelte configuration files
13
 * @param viteConfig - Optional Vite user configuration for context
14
 * @param inlineOptions - Optional inline plugin options that may affect config loading
15
 * @returns Promise resolving to parsed Svelte config or undefined if no config found
16
 */
17
function loadSvelteConfig(
18
  viteConfig?: UserConfig,
19
  inlineOptions?: Partial<Options>
20
): Promise<Partial<SvelteConfig> | undefined>;
21
```
22

23
**Usage Examples:**
24

25
```javascript
26
import { loadSvelteConfig } from '@sveltejs/vite-plugin-svelte';
27

28
// Basic usage - auto-discover config file
29
const config = await loadSvelteConfig();
30
console.log(config?.compilerOptions);
31

32
// With Vite config context
33
const viteConfig = { root: './src' };
34
const config = await loadSvelteConfig(viteConfig);
35

36
// With inline options
37
const config = await loadSvelteConfig(viteConfig, {
38
  configFile: './custom.svelte.config.js'
39
});
40

41
// Disable config file loading
42
const config = await loadSvelteConfig(viteConfig, {
43
  configFile: false
44
});
45
```
46

47
## Configuration File Discovery
48

49
### Supported Config File Names
50

51
The system automatically discovers Svelte configuration files in the following order:
52

53
```typescript { .api }
54
const knownSvelteConfigNames: string[] = [
55
  'svelte.config.js',
56
  'svelte.config.ts', 
57
  'svelte.config.mjs',
58
  'svelte.config.mts'
59
];
60
```
61

62
**File Discovery Process:**
63

64
1. Checks for custom `configFile` in inline options
65
2. Searches project root for known config file names
66
3. Uses the first found file if multiple exist (with warning)
67
4. Returns undefined if no config file found
68

69
### Custom Config File Paths
70

71
Specify custom configuration file locations:
72

73
```javascript
74
// Relative to Vite root
75
const config = await loadSvelteConfig(viteConfig, {
76
  configFile: './config/svelte.config.js'
77
});
78

79
// Absolute path
80
const config = await loadSvelteConfig(viteConfig, {
81
  configFile: '/path/to/project/svelte.config.js'
82
});
83

84
// Disable config loading entirely
85
const config = await loadSvelteConfig(viteConfig, {
86
  configFile: false
87
});
88
```
89

90
## Configuration File Formats
91

92
### JavaScript Configuration
93

94
```javascript
95
// svelte.config.js
96
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
97

98
/** @type {import('@sveltejs/vite-plugin-svelte').SvelteConfig} */
99
export default {
100
  extensions: ['.svelte'],
101
  preprocess: vitePreprocess({
102
    style: true
103
  }),
104
  compilerOptions: {
105
    runes: true,
106
    dev: process.env.NODE_ENV === 'development'
107
  },
108
  vitePlugin: {
109
    emitCss: true,
110
    inspector: true
111
  },
112
  onwarn(warning, defaultHandler) {
113
    // Custom warning handling
114
    if (warning.code === 'css-unused-selector') return;
115
    defaultHandler(warning);
116
  }
117
};
118
```
119

120
### TypeScript Configuration
121

122
```typescript
123
// svelte.config.ts
124
import type { SvelteConfig } from '@sveltejs/vite-plugin-svelte';
125
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
126

127
const config: SvelteConfig = {
128
  extensions: ['.svelte'],
129
  preprocess: vitePreprocess({
130
    style: true,
131
    script: false
132
  }),
133
  compilerOptions: {
134
    runes: true,
135
    hydratable: true
136
  },
137
  vitePlugin: {
138
    emitCss: true,
139
    hot: true,
140
    inspector: {
141
      holdMode: true,
142
      showToggleButton: 'always'
143
    }
144
  }
145
};
146

147
export default config;
148
```
149

150
### ESM Configuration
151

152
```javascript
153
// svelte.config.mjs
154
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
155

156
export default {
157
  preprocess: vitePreprocess(),
158
  compilerOptions: {
159
    runes: true
160
  }
161
};
162
```
163

164
### Dynamic Configuration
165

166
```javascript
167
// svelte.config.js
168
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
169

170
const isDev = process.env.NODE_ENV === 'development';
171
const isProd = process.env.NODE_ENV === 'production';
172

173
export default {
174
  preprocess: vitePreprocess({
175
    style: {
176
      css: {
177
        devSourcemap: isDev,
178
        minify: isProd
179
      }
180
    }
181
  }),
182
  compilerOptions: {
183
    dev: isDev,
184
    hydratable: isProd,
185
    runes: true
186
  },
187
  vitePlugin: {
188
    emitCss: true,
189
    hot: isDev,
190
    inspector: isDev,
191
    prebundleSvelteLibraries: isDev
192
  },
193
  onwarn(warning, defaultHandler) {
194
    // Ignore certain warnings in production
195
    if (isProd && ['css-unused-selector', 'a11y-missing-attribute'].includes(warning.code)) {
196
      return;
197
    }
198
    defaultHandler(warning);
199
  }
200
};
201
```
202

203
## Configuration Validation
204

205
### Error Handling
206

207
The configuration loader includes comprehensive error handling:
208

209
```javascript
210
try {
211
  const config = await loadSvelteConfig(viteConfig, options);
212
  if (!config) {
213
    console.log('No Svelte config found, using defaults');
214
  }
215
} catch (error) {
216
  console.error('Failed to load Svelte config:', error.message);
217
  // Handle configuration loading errors
218
}
219
```
220

221
### Configuration Validation
222

223
The loader validates configuration structure and provides meaningful error messages for common issues:
224

225
- Invalid export format (must export default)
226
- Missing or malformed configuration objects  
227
- File system errors (missing files, permission issues)
228
- Module resolution errors
229

230
## Integration Patterns
231

232
### Build Tool Integration
233

234
Integrate configuration loading into custom build tools:
235

236
```javascript
237
// Custom build script
238
import { loadSvelteConfig } from '@sveltejs/vite-plugin-svelte';
239

240
async function buildProject() {
241
  const viteConfig = await loadViteConfig();
242
  const svelteConfig = await loadSvelteConfig(viteConfig);
243
  
244
  // Use configuration to customize build process
245
  const shouldMinify = !svelteConfig?.compilerOptions?.dev;
246
  const preprocessors = svelteConfig?.preprocess || [];
247
  
248
  // Custom build logic here
249
}
250
```
251

252
### Testing Configuration
253

254
Load configuration in test environments:
255

256
```javascript
257
// test-utils.js
258
import { loadSvelteConfig } from '@sveltejs/vite-plugin-svelte';
259

260
export async function setupSvelteTest() {
261
  const config = await loadSvelteConfig({
262
    root: process.cwd()
263
  }, {
264
    configFile: './svelte.config.test.js'
265
  });
266
  
267
  return config;
268
}
269
```
270

271
### Development Tools Integration
272

273
Use configuration loading in development tools:
274

275
```javascript
276
// dev-tool.js
277
import { loadSvelteConfig } from '@sveltejs/vite-plugin-svelte';
278

279
async function analyzeSvelteProject() {
280
  const config = await loadSvelteConfig();
281
  
282
  // Analyze project based on configuration
283
  const extensions = config?.extensions || ['.svelte'];
284
  const hasPreprocessors = Boolean(config?.preprocess);
285
  const isRunesEnabled = config?.compilerOptions?.runes;
286
  
287
  return {
288
    extensions,
289
    hasPreprocessors,
290
    isRunesEnabled
291
  };
292
}
293
```
294

295
## Configuration Merging
296

297
The configuration system merges options from multiple sources in priority order:
298

299
1. **Inline options** (highest priority)
300
2. **Svelte config file** 
301
3. **Default values** (lowest priority)
302

303
This allows for flexible configuration overrides while maintaining sensible defaults.
304

305
```javascript
306
// Example of configuration precedence
307
const finalConfig = {
308
  // Defaults
309
  extensions: ['.svelte'],
310
  emitCss: true,
311
  
312
  // Overridden by svelte.config.js
313
  ...svelteConfigFile,
314
  
315
  // Overridden by inline options
316
  ...inlineOptions
317
};
318
```