0
# Configuration Management
1

2
Snowpack configuration management provides flexible configuration loading, validation, and customization for tailoring build behavior to your project needs. Configuration can be provided via files, programmatic API, or command-line flags.
3

4
## Capabilities
5

6
### Configuration Loading
7

8
Load and validate Snowpack configuration from the file system with automatic discovery and validation.
9

10
```typescript { .api }
11
/**
12
 * Load and validate Snowpack configuration from file system
13
 * @param overrides - Optional configuration overrides to merge
14
 * @param configPath - Optional path to specific config file
15
 * @returns Promise resolving to validated complete configuration
16
 */
17
function loadConfiguration(overrides?: SnowpackUserConfig, configPath?: string): Promise<SnowpackConfig>;
18
```
19

20
```typescript
21
import { loadConfiguration } from "snowpack";
22

23
// Load configuration from default locations
24
const config = await loadConfiguration();
25

26
// Load with overrides
27
const config = await loadConfiguration({
28
  devOptions: { port: 3000 },
29
  buildOptions: { out: 'build' }
30
});
31

32
// Load from specific file
33
const config = await loadConfiguration({}, './custom.config.js');
34
```
35

36
### Configuration Creation
37

38
Create configuration objects programmatically with defaults applied.
39

40
```typescript { .api }
41
/**
42
 * Create a Snowpack configuration object with defaults
43
 * @param config - Optional partial configuration to merge with defaults
44
 * @returns Complete configuration object with all defaults applied
45
 */
46
function createConfiguration(config?: SnowpackUserConfig): SnowpackConfig;
47
```
48

49
```typescript
50
import { createConfiguration } from "snowpack";
51

52
// Create minimal configuration with defaults
53
const config = createConfiguration();
54

55
// Create configuration with custom options
56
const config = createConfiguration({
57
  root: './src',
58
  mount: {
59
    'src': '/',
60
    'public': { url: '/', static: true }
61
  },
62
  devOptions: {
63
    port: 8080,
64
    hostname: '0.0.0.0'
65
  }
66
});
67
```
68

69
### CLI Flag Expansion
70

71
Convert command-line flags to configuration overrides.
72

73
```typescript { .api }
74
/**
75
 * Expand CLI flags into configuration overrides
76
 * @param flags - CLI flags object
77
 * @returns Configuration overrides from flags
78
 */
79
function expandCliFlags(flags: CLIFlags): SnowpackUserConfig;
80

81
/**
82
 * CLI flags interface
83
 */
84
interface CLIFlags {
85
  /** Display help text */
86
  help?: boolean;
87
  /** Display version */
88
  version?: boolean;  
89
  /** Clear cache */
90
  reload?: boolean;
91
  /** Project root path */
92
  root?: string;
93
  /** Config file path */
94
  config?: string;
95
  /** Environment variables */
96
  env?: string[];
97
  /** URLs to open */
98
  open?: string[];
99
  /** Enable HTTPS */
100
  secure?: boolean;
101
  /** Verbose logging */
102
  verbose?: boolean;
103
  /** Quiet logging */
104
  quiet?: boolean;
105
  [flag: string]: any;
106
}
107
```
108

109
```typescript
110
// Example CLI flag processing
111
const flags = {
112
  root: './my-app',
113
  port: 3000,
114
  open: ['chrome'],
115
  verbose: true
116
};
117

118
const cliConfig = expandCliFlags(flags);
119
const config = await loadConfiguration(cliConfig);
120
```
121

122
## Configuration Structure
123

124
### Main Configuration Interface
125

126
```typescript { .api }
127
/**
128
 * Complete Snowpack configuration object
129
 */
130
interface SnowpackConfig {
131
  /** Project root directory */
132
  root: string;
133
  /** Build mode */
134
  mode: 'test' | 'development' | 'production';
135
  /** Workspace root directory */
136
  workspaceRoot?: string | false;
137
  /** Configuration to extend */
138
  extends?: string;
139
  /** Glob patterns to exclude */
140
  exclude: string[];
141
  /** Environment variables */
142
  env?: Record<string, string | boolean | undefined>;
143
  /** Directory mount points */
144
  mount: Record<string, MountEntry>;
145
  /** Import path aliases */
146
  alias: Record<string, string>;
147
  /** Loaded plugin instances */
148
  plugins: SnowpackPlugin[];
149
  /** Package dependencies */
150
  dependencies: Record<string, string>;
151
  /** Development server options */
152
  devOptions: DevOptions;
153
  /** Build system options */
154
  buildOptions: BuildOptions;
155
  /** Test runner options */
156
  testOptions: TestOptions;
157
  /** Package source options */
158
  packageOptions: PackageOptionsLocal | PackageOptionsRemote;
159
  /** Production optimization options */
160
  optimize?: OptimizeOptions;
161
  /** Route configuration */
162
  routes: RouteConfigObject[];
163
  /** Experimental features */
164
  experiments: {};
165
  /** Internal file extension mappings */
166
  _extensionMap: Record<string, string[]>;
167
}
168
```
169

170
### User Configuration Interface
171

172
```typescript { .api }
173
/**
174
 * User-provided configuration (all fields optional)
175
 */
176
interface SnowpackUserConfig {
177
  /** Project root directory */
178
  root?: string;
179
  /** Build mode */
180
  mode?: SnowpackConfig['mode'];
181
  /** Workspace root directory */
182
  workspaceRoot?: string;
183
  /** Packages to install */
184
  install?: string[];
185
  /** Environment variables */
186
  env?: Record<string, string>;
187
  /** Configuration to extend */
188
  extends?: string;
189
  /** Glob patterns to exclude */
190
  exclude?: string[];
191
  /** Directory mount points */
192
  mount?: Record<string, string | Partial<MountEntry>>;
193
  /** Import path aliases */
194
  alias?: Record<string, string>;
195
  /** Plugin configurations */
196
  plugins?: (string | [string, any])[];
197
  /** Package dependencies */
198
  dependencies?: Record<string, string>;
199
  /** Development server options */
200
  devOptions?: Partial<SnowpackConfig['devOptions']>;
201
  /** Build system options */
202
  buildOptions?: Partial<SnowpackConfig['buildOptions']>;
203
  /** Test runner options */
204
  testOptions?: Partial<SnowpackConfig['testOptions']>;
205
  /** Package source options */
206
  packageOptions?: Partial<SnowpackConfig['packageOptions']>;
207
  /** Production optimization options */
208
  optimize?: Partial<SnowpackConfig['optimize']>;
209
  /** Route configuration */
210
  routes?: Pick<RouteConfigObject, 'src' | 'dest' | 'match'>[];
211
  /** Experimental features */
212
  experiments?: {};
213
}
214
```
215

216
## Development Options
217

218
```typescript { .api }
219
/**
220
 * Development server configuration
221
 */
222
interface DevOptions {
223
  /** HTTPS configuration */
224
  secure: boolean | {
225
    cert: string | Buffer;
226
    key: string | Buffer;
227
  };
228
  /** Server hostname */
229
  hostname: string;
230
  /** Server port number */
231
  port: number;
232
  /** URL to open in browser */
233
  openUrl?: string;
234
  /** Browser to open */
235
  open?: string;
236
  /** Output display mode */
237
  output?: 'stream' | 'dashboard';
238
  /** Enable hot module replacement */
239
  hmr?: boolean;
240
  /** HMR connection delay */
241
  hmrDelay: number;
242
  /** HMR WebSocket port */
243
  hmrPort: number | undefined;
244
  /** Show HMR error overlay */
245
  hmrErrorOverlay: boolean;
246
  /** Tailwind config file path */
247
  tailwindConfig?: string;
248
}
249
```
250

251
```typescript
252
// Example development options
253
const config = createConfiguration({
254
  devOptions: {
255
    hostname: 'localhost',
256
    port: 3000,
257
    secure: false,
258
    hmr: true,
259
    hmrDelay: 0,
260
    hmrErrorOverlay: true,
261
    open: 'chrome',
262
    output: 'dashboard'
263
  }
264
});
265
```
266

267
## Build Options
268

269
```typescript { .api }
270
/**
271
 * Build system configuration
272
 */
273
interface BuildOptions {
274
  /** Output directory */
275
  out: string;
276
  /** Base URL for assets */
277
  baseUrl: string;
278
  /** Meta URL path */
279
  metaUrlPath: string;
280
  /** Cache directory path */
281
  cacheDirPath: string;
282
  /** Clean output before build */
283
  clean: boolean;
284
  /** Source map generation */
285
  sourcemap: 'inline' | false | undefined;
286
  /** Enable watch mode */
287
  watch: boolean;
288
  /** Generate HTML fragments */
289
  htmlFragments: boolean;
290
  /** JSX factory function */
291
  jsxFactory: string | undefined;
292
  /** JSX fragment function */
293
  jsxFragment: string | undefined;
294
  /** JSX import injection */
295
  jsxInject: string | undefined;
296
  /** Enable SSR */
297
  ssr: boolean;
298
  /** Resolve proxy imports */
299
  resolveProxyImports: boolean;
300
}
301
```
302

303
```typescript
304
// Example build options
305
const config = createConfiguration({
306
  buildOptions: {
307
    out: 'dist',
308
    baseUrl: '/',
309
    clean: true,
310
    sourcemap: false,
311
    watch: false,
312
    ssr: false,
313
    jsxFactory: 'React.createElement',
314
    jsxFragment: 'React.Fragment'
315
  }
316
});
317
```
318

319
## Mount Configuration
320

321
```typescript { .api }
322
/**
323
 * Directory mount point configuration
324
 */
325
interface MountEntry {
326
  /** URL path to mount directory */
327
  url: string;
328
  /** Serve files statically */
329
  static: boolean;
330
  /** Enable import resolution */
331
  resolve: boolean;
332
  /** Include dotfiles */
333
  dot: boolean;
334
}
335
```
336

337
```typescript
338
// Example mount configuration
339
const config = createConfiguration({
340
  mount: {
341
    // Process src/ files and mount to root
342
    'src': { url: '/', static: false, resolve: true, dot: false },
343
    // Serve public/ files statically
344
    'public': { url: '/', static: true, resolve: false, dot: false },
345
    // Mount assets to /assets/
346
    'assets': { url: '/assets', static: true, resolve: false, dot: false }
347
  }
348
});
349
```
350

351
## Package Options
352

353
```typescript { .api }
354
/**
355
 * Local package source configuration
356
 */
357
interface PackageOptionsLocal {
358
  /** Package source type */
359
  source: 'local' | 'remote-next' | {[key: string]: string};
360
  /** External packages to exclude */
361
  external: string[];
362
  /** Known package entry points */
363
  knownEntrypoints: string[];
364
}
365

366
/**
367
 * Remote package source configuration  
368
 */
369
interface PackageOptionsRemote {
370
  /** Package source type */
371
  source: 'remote';
372
  /** External packages to exclude */
373
  external: string[];
374
  /** Known package entry points */
375
  knownEntrypoints: string[];
376
  /** Remote package origin */
377
  origin: string;
378
  /** Cache configuration */
379
  cache: string;
380
  /** Include type definitions */
381
  types: boolean;
382
}
383
```
384

385
```typescript
386
// Local package configuration
387
const config = createConfiguration({
388
  packageOptions: {
389
    source: 'local',
390
    external: ['fsevents'],
391
    knownEntrypoints: ['react', 'react-dom']
392
  }
393
});
394

395
// Remote package configuration
396
const config = createConfiguration({
397
  packageOptions: {
398
    source: 'remote',
399
    origin: 'https://pkg.snowpack.dev',
400
    cache: '.snowpack',
401
    types: true,
402
    external: [],
403
    knownEntrypoints: []
404
  }
405
});
406
```
407

408
## Route Configuration
409

410
```typescript { .api }
411
/**
412
 * Route configuration for development server
413
 */
414
interface RouteConfigObject {
415
  /** Source pattern */
416
  src: string;
417
  /** Destination or handler function */
418
  dest: string | ((req: http.IncomingMessage, res: http.ServerResponse) => void) | undefined;
419
  /** WebSocket upgrade handler */
420
  upgrade: ((req: http.IncomingMessage, socket: net.Socket, head: Buffer) => void) | undefined;
421
  /** Route matching mode */
422
  match: 'routes' | 'all';
423
  /** Internal regex for matching */
424
  _srcRegex: RegExp;
425
}
426
```
427

428
```typescript
429
// Example route configuration
430
const config = createConfiguration({
431
  routes: [
432
    // Proxy API requests
433
    { src: '/api/.*', dest: 'http://localhost:4000$1', match: 'routes' },
434
    // SPA fallback
435
    { src: '/.*', dest: '/index.html', match: 'routes' }
436
  ]
437
});
438
```
439

440
## Environment Variables
441

442
```typescript
443
// Environment variable configuration
444
const config = createConfiguration({
445
  env: {
446
    NODE_ENV: 'development',
447
    PUBLIC_URL: '/',
448
    CUSTOM_VAR: 'value'
449
  }
450
});
451

452
// Variables prefixed with SNOWPACK_PUBLIC_ are available client-side
453
process.env.SNOWPACK_PUBLIC_API_URL = 'https://api.example.com';
454
```
455

456
## Configuration Files
457

458
Snowpack looks for configuration in these files (in order):
459

460
1. `snowpack.config.js`
461
2. `snowpack.config.mjs` 
462
3. `snowpack.config.json`
463
4. `package.json` (snowpack field)
464

465
```javascript
466
// snowpack.config.js
467
export default {
468
  mount: {
469
    src: '/',
470
    public: { url: '/', static: true }
471
  },
472
  plugins: [
473
    '@snowpack/plugin-typescript',
474
    '@snowpack/plugin-react-refresh'
475
  ],
476
  devOptions: {
477
    port: 3000,
478
    hmr: true
479
  },
480
  buildOptions: {
481
    out: 'build'
482
  }
483
};
484
```
485

486
```json
487
// package.json
488
{
489
  "snowpack": {
490
    "mount": {
491
      "src": "/",
492
      "public": {"url": "/", "static": true}
493
    },
494
    "devOptions": {
495
      "port": 3000
496
    }
497
  }
498
}
499
```
500

501
## Configuration Validation
502

503
Configuration is automatically validated with helpful error messages:
504

505
```typescript
506
try {
507
  const config = await loadConfiguration();
508
} catch (error) {
509
  if (error.name === 'CONFIG_VALIDATION_ERROR') {
510
    console.error('Configuration validation failed:');
511
    console.error(error.message);
512
  }
513
}
514
```