0
# Build System
1

2
Local and remote build functionality with context support, offline capabilities, and production serving for testing built applications locally.
3

4
## Capabilities
5

6
### Local Build
7

8
Build projects locally using Netlify Build system with full context support and plugin integration.
9

10
```typescript { .api }
11
/**
12
 * Build project locally
13
 * Command: netlify build [options]
14
 */
15
interface BuildOptions {
16
  /** Deploy context for environment variables and plugins (default: production) */
17
  context?: 'production' | 'deploy-preview' | 'branch-deploy' | 'dev' | string;
18
  /** Show build instructions without executing (dry run) */
19
  dry?: boolean;
20
  /** Disable network-dependent features during build */
21
  offline?: boolean;
22
}
23
```
24

25
**Usage Examples:**
26

27
```bash
28
# Build for production context
29
netlify build
30

31
# Build for specific context
32
netlify build --context deploy-preview
33

34
# Dry run to see build commands
35
netlify build --dry
36

37
# Build offline (skip network features)
38
netlify build --offline
39

40
# Build for development context
41
netlify build --context dev
42
```
43

44
### Production Serve
45

46
Serve built applications locally to test production builds before deployment.
47

48
```typescript { .api }
49
/**
50
 * Build and serve project locally for production testing
51
 * Command: netlify serve [options]
52
 */
53
interface ServeOptions {
54
  /** Deploy context for build and serve */
55
  context?: 'production' | 'deploy-preview' | 'branch-deploy' | 'dev' | string;
56
  /** Port for local server */
57
  port?: number;
58
  /** Static files directory to serve */
59
  dir?: string;
60
  /** Functions folder */
61
  functions?: string;
62
  /** Disable network-dependent features */
63
  offline?: boolean;
64
  /** Disable edge functions */
65
  internalDisableEdgeFunctions?: boolean;
66
  /** Functions server port */
67
  functionsPort?: number;
68
  /** Geolocation mode for testing */
69
  geo?: 'cache' | 'mock' | 'update';
70
  /** Country code for geo mocking */
71
  country?: string;
72
  /** Static server port */
73
  staticServerPort?: number;
74
}
75
```
76

77
**Usage Examples:**
78

79
```bash
80
# Build and serve for production
81
netlify serve
82

83
# Serve on custom port
84
netlify serve --port 8080
85

86
# Serve with custom directory
87
netlify serve --dir dist
88

89
# Serve with functions
90
netlify serve --functions ./lambda --port 3000
91

92
# Serve for specific context
93
netlify serve --context deploy-preview
94

95
# Serve with geolocation mocking
96
netlify serve --geo mock --country US
97

98
# Serve offline
99
netlify serve --offline
100
```
101

102
### Build Configuration
103

104
Build system configuration and integration with netlify.toml:
105

106
```typescript { .api }
107
/**
108
 * Build configuration structure
109
 */
110
interface BuildConfig {
111
  /** Build settings */
112
  build: {
113
    /** Build command to execute */
114
    command?: string;
115
    /** Directory to publish (relative to repo root) */
116
    publish?: string;
117
    /** Functions directory */
118
    functions?: string;
119
    /** Base directory for build */
120
    base?: string;
121
    /** Environment variables for build */
122
    environment?: Record<string, string>;
123
    /** Build processing */
124
    processing: {
125
      /** CSS optimization */
126
      css?: {
127
        bundle: boolean;
128
        minify: boolean;
129
      };
130
      /** JavaScript optimization */
131
      js?: {
132
        bundle: boolean;
133
        minify: boolean;
134
      };
135
      /** HTML optimization */
136
      html?: {
137
        pretty_urls: boolean;
138
      };
139
      /** Image optimization */
140
      images?: {
141
        compress: boolean;
142
      };
143
    };
144
  };
145
  
146
  /** Context-specific build settings */
147
  context: {
148
    [contextName: string]: {
149
      command?: string;
150
      publish?: string;
151
      functions?: string;
152
      environment?: Record<string, string>;
153
    };
154
  };
155
  
156
  /** Branch-specific settings */
157
  [branchName: string]: {
158
    command?: string;
159
    publish?: string;
160
    functions?: string;
161
    environment?: Record<string, string>;
162
  };
163
}
164
```
165

166
### Build Plugins
167

168
Integration with Netlify Build plugins for extended functionality:
169

170
```typescript { .api }
171
/**
172
 * Build plugin configuration
173
 */
174
interface BuildPlugins {
175
  /** Plugin list and configuration */
176
  plugins: Array<{
177
    /** Plugin package name */
178
    package: string;
179
    /** Plugin inputs/configuration */
180
    inputs?: Record<string, any>;
181
    /** Conditions for plugin execution */
182
    conditions?: {
183
      /** Only run in specific contexts */
184
      context?: string[];
185
      /** Only run for specific branches */
186
      branch?: string[];
187
      /** Environment variable conditions */
188
      env?: Record<string, string>;
189
    };
190
  }>;
191
  
192
  /** Popular build plugins */
193
  common: {
194
    /** Essential plugins */
195
    essential: [
196
      '@netlify/plugin-essential-next',
197
      '@netlify/plugin-gatsby',
198
      '@netlify/plugin-nuxt'
199
    ];
200
    /** Optimization plugins */
201
    optimization: [
202
      'netlify-plugin-minify-html',
203
      'netlify-plugin-image-optim',
204
      'netlify-plugin-inline-critical-css'
205
    ];
206
    /** SEO and analytics */
207
    seo: [
208
      'netlify-plugin-sitemap',
209
      'netlify-plugin-lighthouse',
210
      '@netlify/plugin-google-analytics'
211
    ];
212
    /** Security plugins */
213
    security: [
214
      'netlify-plugin-csp-generator',
215
      'netlify-plugin-security-txt'
216
    ];
217
  };
218
}
219
```
220

221
### Build Process and Lifecycle
222

223
Build process stages and lifecycle hooks:
224

225
```typescript { .api }
226
/**
227
 * Build lifecycle stages
228
 */
229
interface BuildLifecycle {
230
  /** Pre-build stage */
231
  preBuild: {
232
    /** Install dependencies */
233
    install: boolean;
234
    /** Run pre-build commands */
235
    commands: string[];
236
    /** Plugin pre-build hooks */
237
    pluginHooks: string[];
238
  };
239
  
240
  /** Build stage */
241
  build: {
242
    /** Main build command */
243
    command: string;
244
    /** Build timeout */
245
    timeout: number; // seconds
246
    /** Environment variables */
247
    environment: Record<string, string>;
248
    /** Working directory */
249
    workingDirectory: string;
250
  };
251
  
252
  /** Post-build stage */
253
  postBuild: {
254
    /** Post-build commands */
255
    commands: string[];
256
    /** Plugin post-build hooks */
257
    pluginHooks: string[];
258
    /** Asset processing */
259
    assetProcessing: boolean;
260
  };
261
  
262
  /** Pre-deploy stage */
263
  preDeploy: {
264
    /** Pre-deploy commands */
265
    commands: string[];
266
    /** File transformations */
267
    transformations: string[];
268
    /** Security scans */
269
    securityScans: boolean;
270
  };
271
}
272
```
273

274
### Framework Detection and Integration
275

276
Automatic framework detection and configuration:
277

278
```typescript { .api }
279
/**
280
 * Framework detection system
281
 */
282
interface FrameworkDetection {
283
  /** Detected framework information */
284
  detected: {
285
    /** Framework name */
286
    name: 'gatsby' | 'next' | 'react' | 'vue' | 'angular' | 'hugo' | 'jekyll' | 'eleventy' | 'svelte' | 'nuxt' | 'vite' | 'remix' | 'astro';
287
    /** Framework version */
288
    version: string;
289
    /** Detection confidence */
290
    confidence: number; // 0-1
291
    /** Detection method */
292
    detectedBy: 'package.json' | 'config-file' | 'file-structure';
293
  };
294
  
295
  /** Framework-specific settings */
296
  settings: {
297
    /** Default build command */
298
    buildCommand: string;
299
    /** Default publish directory */
300
    publishDir: string;
301
    /** Default functions directory */
302
    functionsDir?: string;
303
    /** Framework-specific environment variables */
304
    environment: Record<string, string>;
305
    /** Required plugins */
306
    plugins: string[];
307
    /** Development server settings */
308
    devCommand: string;
309
    devPort: number;
310
  };
311
  
312
  /** Framework overrides */
313
  overrides: {
314
    /** Custom build command */
315
    buildCommand?: string;
316
    /** Custom publish directory */
317
    publishDir?: string;
318
    /** Custom environment variables */
319
    environment?: Record<string, string>;
320
    /** Additional plugins */
321
    additionalPlugins?: string[];
322
  };
323
}
324
```
325

326
### Build Environment
327

328
Build environment configuration and variables:
329

330
```typescript { .api }
331
/**
332
 * Build environment configuration
333
 */
334
interface BuildEnvironment {
335
  /** System environment */
336
  system: {
337
    /** Operating system */
338
    os: 'ubuntu-20.04' | 'ubuntu-22.04';
339
    /** Node.js version */
340
    nodeVersion: string;
341
    /** npm version */
342
    npmVersion: string;
343
    /** yarn version */
344
    yarnVersion?: string;
345
    /** Python version */
346
    pythonVersion?: string;
347
    /** Ruby version */
348
    rubyVersion?: string;
349
    /** Go version */
350
    goVersion?: string;
351
    /** Available memory */
352
    memory: number; // MB
353
    /** Available disk space */
354
    diskSpace: number; // GB
355
  };
356
  
357
  /** Build-specific variables */
358
  buildVars: {
359
    /** Netlify build variables */
360
    netlify: {
361
      BUILD_ID: string;
362
      DEPLOY_ID: string;
363
      CONTEXT: string;
364
      BRANCH: string;
365
      HEAD: string;
366
      COMMIT_REF: string;
367
      REPOSITORY_URL: string;
368
      URL: string;
369
      DEPLOY_URL: string;
370
      DEPLOY_PRIME_URL: string;
371
      SITE_ID: string;
372
      SITE_NAME: string;
373
      NETLIFY: 'true';
374
      NETLIFY_BUILD_BASE: string;
375
      NETLIFY_BUILD_LIFECYCLE_TRIAL: string;
376
    };
377
    
378
    /** User-defined variables */
379
    user: Record<string, string>;
380
    
381
    /** Context-specific variables */
382
    context: Record<string, string>;
383
  };
384
  
385
  /** Cache configuration */
386
  cache: {
387
    /** Build cache directory */
388
    directory: string;
389
    /** Cache key */
390
    key: string;
391
    /** Cache dependencies */
392
    dependencies: string[];
393
    /** Cache max age */
394
    maxAge: number; // seconds
395
  };
396
}
397
```
398

399
### Build Output and Artifacts
400

401
Build output handling and artifact management:
402

403
```typescript { .api }
404
/**
405
 * Build output configuration
406
 */
407
interface BuildOutput {
408
  /** Output directories */
409
  directories: {
410
    /** Main publish directory */
411
    publish: string;
412
    /** Functions output directory */
413
    functions?: string;
414
    /** Edge functions directory */
415
    edgeFunctions?: string;
416
    /** Static assets directory */
417
    assets?: string;
418
  };
419
  
420
  /** File processing */
421
  processing: {
422
    /** Files to include in deploy */
423
    include: string[];
424
    /** Files to exclude from deploy */
425
    exclude: string[];
426
    /** File transformations */
427
    transforms: Array<{
428
      from: string;
429
      to: string;
430
      transform: 'minify' | 'compress' | 'optimize' | 'rename';
431
    }>;
432
  };
433
  
434
  /** Build artifacts */
435
  artifacts: {
436
    /** Build logs */
437
    logs: {
438
      path: string;
439
      level: 'error' | 'warn' | 'info' | 'debug';
440
      format: 'text' | 'json';
441
    };
442
    /** Test results */
443
    tests?: {
444
      path: string;
445
      format: 'junit' | 'tap' | 'json';
446
    };
447
    /** Coverage reports */
448
    coverage?: {
449
      path: string;
450
      format: 'lcov' | 'json' | 'html';
451
    };
452
    /** Bundle analysis */
453
    bundleAnalysis?: {
454
      path: string;
455
      format: 'json' | 'html';
456
    };
457
  };
458
}
459
```
460

461
### Build Performance and Optimization
462

463
Build performance monitoring and optimization features:
464

465
```typescript { .api }
466
/**
467
 * Build performance configuration
468
 */
469
interface BuildPerformance {
470
  /** Performance monitoring */
471
  monitoring: {
472
    /** Build time tracking */
473
    timing: {
474
      enabled: boolean;
475
      breakdown: boolean; // per-stage timing
476
    };
477
    /** Resource usage tracking */
478
    resources: {
479
      memory: boolean;
480
      cpu: boolean;
481
      disk: boolean;
482
    };
483
  };
484
  
485
  /** Optimization settings */
486
  optimization: {
487
    /** Parallel processing */
488
    parallel: {
489
      enabled: boolean;
490
      maxWorkers: number;
491
    };
492
    /** Incremental builds */
493
    incremental: {
494
      enabled: boolean;
495
      cacheStrategy: 'aggressive' | 'conservative';
496
    };
497
    /** Dependency optimization */
498
    dependencies: {
499
      /** Dependency caching */
500
      cache: boolean;
501
      /** Install optimization */
502
      optimizeInstall: boolean;
503
    };
504
  };
505
  
506
  /** Build limits */
507
  limits: {
508
    /** Maximum build time */
509
    timeout: number; // minutes
510
    /** Maximum log size */
511
    maxLogSize: number; // MB
512
    /** Maximum output size */
513
    maxOutputSize: number; // MB
514
  };
515
}
516
```
517

518
### Error Handling and Debugging
519

520
Build error handling and debugging capabilities:
521

522
```typescript { .api }
523
/**
524
 * Build error handling configuration
525
 */
526
interface BuildErrorHandling {
527
  /** Error detection */
528
  detection: {
529
    /** Exit code monitoring */
530
    exitCodes: boolean;
531
    /** Log pattern matching */
532
    logPatterns: string[];
533
    /** Timeout detection */
534
    timeouts: boolean;
535
  };
536
  
537
  /** Error reporting */
538
  reporting: {
539
    /** Error categorization */
540
    categorize: boolean;
541
    /** Stack trace capture */
542
    stackTraces: boolean;
543
    /** Context information */
544
    contextInfo: boolean;
545
  };
546
  
547
  /** Recovery options */
548
  recovery: {
549
    /** Automatic retry */
550
    autoRetry: {
551
      enabled: boolean;
552
      maxAttempts: number;
553
      backoffStrategy: 'linear' | 'exponential';
554
    };
555
    /** Fallback builds */
556
    fallback: {
557
      enabled: boolean;
558
      strategy: 'previous-successful' | 'minimal';
559
    };
560
  };
561
  
562
  /** Debug features */
563
  debug: {
564
    /** Debug mode */
565
    enabled: boolean;
566
    /** Verbose logging */
567
    verbose: boolean;
568
    /** Build shell access */
569
    shellAccess: boolean;
570
    /** Environment inspection */
571
    envInspection: boolean;
572
  };
573
}
574
```