0
# Build System
1

2
The RequireJS r.js build system provides sophisticated optimization and bundling capabilities for AMD-based JavaScript applications. It can combine modules, minify code, optimize CSS, and generate production-ready builds with advanced dependency analysis.
3

4
## Capabilities
5

6
### Build Configuration
7

8
The build system is configured through a comprehensive set of options that control every aspect of the optimization process.
9

10
```javascript { .api }
11
/**
12
 * Main build configuration interface
13
 */
14
interface BuildConfig {
15
    // Basic build options
16
    appDir?: string;                    // Application root directory
17
    baseUrl?: string;                   // Base URL for modules
18
    dir?: string;                       // Output directory
19
    mainConfigFile?: string | string[]; // Main config file(s)
20
    
21
    // Module definitions
22
    modules?: ModuleConfig[];           // Modules to build
23
    
24
    // Optimization options
25
    optimize?: 'uglify' | 'uglify2' | 'closure' | 'closure.keepLines' | 'none';
26
    optimizeCss?: string;              // CSS optimization level
27
    
28
    // Path and dependency configuration
29
    paths?: { [key: string]: string };
30
    packages?: PackageConfig[];
31
    shim?: { [key: string]: ShimConfig };
32
    map?: { [key: string]: { [key: string]: string } };
33
}
34
```
35

36
### Core Build Options
37

38
#### Directory Configuration
39

40
```javascript { .api }
41
/**
42
 * Application directory containing source files
43
 * @type {String}
44
 */
45
config.appDir;
46

47
/**
48
 * Base URL for module resolution (relative to appDir)
49
 * @type {String}
50
 */
51
config.baseUrl;
52

53
/**
54
 * Output directory for optimized files
55
 * @type {String}
56
 */
57
config.dir;
58

59
/**
60
 * Keep previous build directory
61
 * @type {Boolean}
62
 */
63
config.keepBuildDir;
64
```
65

66
**Example:**
67

68
```javascript
69
{
70
    appDir: './src',
71
    baseUrl: 'js',
72
    dir: './dist',
73
    keepBuildDir: false
74
}
75
```
76

77
#### Configuration File Loading
78

79
```javascript { .api }
80
/**
81
 * Main configuration file(s) to read require.config() from
82
 * @type {String|Array}
83
 */
84
config.mainConfigFile;
85
```
86

87
**Example:**
88

89
```javascript
90
{
91
    mainConfigFile: ['js/config.js', 'js/app-config.js']
92
}
93
```
94

95
### Module Configuration
96

97
Define specific modules to build with their dependencies and optimization settings.
98

99
```javascript { .api }
100
/**
101
 * Array of module build configurations
102
 * @type {Array}
103
 */
104
config.modules;
105

106
interface ModuleConfig {
107
    name: string;                      // Module name/path
108
    include?: string[];               // Additional modules to include
109
    exclude?: string[];               // Modules to exclude
110
    excludeShallow?: string[];        // Exclude only direct dependencies
111
    create?: boolean;                 // Create module if it doesn't exist
112
    out?: string;                     // Specific output file
113
    override?: Partial<BuildConfig>;  // Override options for this module
114
}
115
```
116

117
**Example:**
118

119
```javascript
120
{
121
    modules: [
122
        {
123
            name: 'app/main',
124
            include: ['app/utils', 'app/helpers'],
125
            exclude: ['jquery']
126
        },
127
        {
128
            name: 'app/admin',
129
            include: ['app/admin/*'],
130
            excludeShallow: ['app/common']
131
        },
132
        {
133
            name: 'vendor',
134
            create: true,
135
            include: ['jquery', 'underscore', 'backbone']
136
        }
137
    ]
138
}
139
```
140

141
### Optimization Configuration
142

143
#### JavaScript Optimization
144

145
```javascript { .api }
146
/**
147
 * JavaScript optimization method
148
 * @type {String}
149
 */
150
config.optimize; // 'uglify' | 'uglify2' | 'closure' | 'closure.keepLines' | 'none'
151

152
/**
153
 * UglifyJS configuration options
154
 * @type {Object}
155
 */
156
config.uglify;
157

158
/**
159
 * UglifyJS2 configuration options
160
 * @type {Object}
161
 */
162
config.uglify2;
163

164
/**
165
 * Closure Compiler configuration
166
 * @type {Object}
167
 */
168
config.closure;
169

170
/**
171
 * Generate source maps for minified files
172
 * @type {Boolean}
173
 */
174
config.generateSourceMaps;
175

176
/**
177
 * Preserve license comments in output
178
 * @type {Boolean}
179
 */
180
config.preserveLicenseComments;
181
```
182

183
**Example:**
184

185
```javascript
186
{
187
    optimize: 'uglify2',
188
    generateSourceMaps: true,
189
    preserveLicenseComments: false,
190
    uglify2: {
191
        output: {
192
            beautify: false
193
        },
194
        compress: {
195
            drop_console: true,
196
            sequences: false
197
        },
198
        warnings: false,
199
        mangle: true
200
    }
201
}
202
```
203

204
#### CSS Optimization
205

206
```javascript { .api }
207
/**
208
 * CSS optimization method
209
 * @type {String}
210
 */
211
config.optimizeCss; // 'standard' | 'standard.keepLines' | 'standard.keepComments' | 'none'
212

213
/**
214
 * CSS input file for CSS-only optimization
215
 * @type {String}
216
 */
217
config.cssIn;
218

219
/**
220
 * CSS output file
221
 * @type {String}
222
 */
223
config.cssOut;
224

225
/**
226
 * URL prefix for relative CSS URLs
227
 * @type {String}
228
 */
229
config.cssPrefix;
230

231
/**
232
 * CSS files to ignore for @import inlining
233
 * @type {String}
234
 */
235
config.cssImportIgnore;
236
```
237

238
**Example:**
239

240
```javascript
241
{
242
    optimizeCss: 'standard',
243
    cssPrefix: '/assets/',
244
    cssImportIgnore: 'reset.css'
245
}
246
```
247

248
### Content Processing Options
249

250
#### Text and Resource Handling
251

252
```javascript { .api }
253
/**
254
 * Inline text! plugin dependencies
255
 * @type {Boolean}
256
 */
257
config.inlineText;
258

259
/**
260
 * Include "use strict" in built files
261
 * @type {Boolean}
262
 */
263
config.useStrict;
264

265
/**
266
 * Replace modules with stubs in output
267
 * @type {Array}
268
 */
269
config.stubModules;
270

271
/**
272
 * Remove combined files from output directory
273
 * @type {Boolean}
274
 */
275
config.removeCombined;
276
```
277

278
**Example:**
279

280
```javascript
281
{
282
    inlineText: true,
283
    useStrict: true,
284
    stubModules: ['text', 'json'],
285
    removeCombined: true
286
}
287
```
288

289
#### Module Processing
290

291
```javascript { .api }
292
/**
293
 * Skip inserting define() wrappers around modules
294
 * @type {Boolean}
295
 */
296
config.skipModuleInsertion;
297

298
/**
299
 * Normalize define() calls: 'skip' | 'all'
300
 * @type {String}
301
 */
302
config.normalizeDirDefines;
303

304
/**
305
 * Skip optimization of files in dir that are not built
306
 * @type {Boolean}
307
 */
308
config.skipDirOptimize;
309
```
310

311
### Advanced Build Features
312

313
#### Conditional Compilation
314

315
```javascript { .api }
316
/**
317
 * Build pragma flags for conditional compilation
318
 * @type {Object}
319
 */
320
config.pragmas;
321

322
/**
323
 * Pragmas applied only during file save phase
324
 * @type {Object}
325
 */
326
config.pragmasOnSave;
327

328
/**
329
 * has.js feature flags for code branch trimming
330
 * @type {Object}
331
 */
332
config.has;
333

334
/**
335
 * has.js flags applied only during save phase
336
 * @type {Object}
337
 */
338
config.hasOnSave;
339
```
340

341
**Example:**
342

343
```javascript
344
{
345
    pragmas: {
346
        debugExclude: true,
347
        consoleLogExclude: true
348
    },
349
    has: {
350
        'host-browser': true,
351
        'host-node': false
352
    }
353
}
354
```
355

356
#### Namespace and Wrapping
357

358
```javascript { .api }
359
/**
360
 * Namespace for require/define calls
361
 * @type {String}
362
 */
363
config.namespace;
364

365
/**
366
 * Wrap build output with start/end files
367
 * @type {Object}
368
 */
369
config.wrap;
370
```
371

372
**Example:**
373

374
```javascript
375
{
376
    namespace: 'MyApp',
377
    wrap: {
378
        start: 'js/start.frag',
379
        end: 'js/end.frag'
380
    }
381
}
382
```
383

384
#### Dependency Analysis
385

386
```javascript { .api }
387
/**
388
 * Find nested require() calls inside define/require
389
 * @type {Boolean}
390
 */
391
config.findNestedDependencies;
392

393
/**
394
 * Optimize all plugin resources as separate files
395
 * @type {Boolean}
396
 */
397
config.optimizeAllPluginResources;
398

399
/**
400
 * Write build summary text file
401
 * @type {Boolean}
402
 */
403
config.writeBuildTxt;
404
```
405

406
### Build Execution
407

408
#### Command Line Usage
409

410
```bash { .api }
411
# Build with configuration file
412
r.js -o build.js
413

414
# Inline build options
415
r.js -o name=main out=main-built.js baseUrl=.
416

417
# Multiple configuration files
418
r.js -o build.js -o build-mobile.js
419
```
420

421
#### Programmatic API
422

423
```javascript { .api }
424
/**
425
 * Programmatic build function
426
 * @param {Object} config - Build configuration
427
 * @param {Function} callback - Completion callback
428
 */
429
function requirejs.optimize(config, callback);
430
```
431

432
**Example:**
433

434
```javascript
435
const requirejs = require('requirejs');
436

437
requirejs.optimize({
438
    name: 'app/main',
439
    baseUrl: 'js',
440
    out: 'js/main-built.js'
441
}, function(buildResponse) {
442
    console.log('Build completed');
443
    console.log(buildResponse);
444
}, function(err) {
445
    console.error('Build failed:', err);
446
});
447
```
448

449
### Build Output and Logging
450

451
#### Output Options
452

453
```javascript { .api }
454
/**
455
 * Single file output path (alternative to dir)
456
 * @type {String}
457
 */
458
config.out;
459

460
/**
461
 * Log level for build process
462
 * @type {Number}
463
 */
464
config.logLevel; // 0=trace, 1=info, 2=warn, 3=error, 4=silent
465
```
466

467
#### Build Information
468

469
```javascript { .api }
470
/**
471
 * Create build.txt with build information
472
 * @type {Boolean}
473
 */
474
config.writeBuildTxt;
475

476
/**
477
 * Include file information in build output
478
 * @type {Boolean}
479
 */
480
config.fileExclusionRegExp;
481
```
482

483
### Environment-Specific Builds
484

485
#### Multi-Environment Configuration
486

487
```javascript
488
// Base configuration
489
const baseConfig = {
490
    appDir: './src',
491
    baseUrl: 'js',
492
    paths: {
493
        'jquery': 'vendor/jquery'
494
    }
495
};
496

497
// Development build
498
const devConfig = {
499
    ...baseConfig,
500
    dir: './dev-build',
501
    optimize: 'none',
502
    generateSourceMaps: false
503
};
504

505
// Production build
506
const prodConfig = {
507
    ...baseConfig,
508
    dir: './prod-build',
509
    optimize: 'uglify2',
510
    generateSourceMaps: true,
511
    removeCombined: true
512
};
513
```
514

515
#### Plugin Resource Optimization
516

517
```javascript
518
{
519
    // Optimize text! plugin resources
520
    stubModules: ['text'],
521
    
522
    // Optimize all plugin resources
523
    optimizeAllPluginResources: true,
524
    
525
    // Plugin-specific build settings
526
    text: {
527
        useXhr: function() { return true; }
528
    }
529
}
530
```
531

532
### Complete Build Example
533

534
```javascript { .api }
535
/**
536
 * Complete build configuration example
537
 */
538
const buildConfig = {
539
    // Basic settings
540
    appDir: './src',
541
    baseUrl: 'js',
542
    dir: './dist',
543
    
544
    // Main configuration
545
    mainConfigFile: 'js/config.js',
546
    
547
    // Modules to build
548
    modules: [
549
        {
550
            name: 'app/main',
551
            exclude: ['vendor/jquery']
552
        },
553
        {
554
            name: 'vendor/libs',
555
            create: true,
556
            include: ['vendor/jquery', 'vendor/underscore']
557
        }
558
    ],
559
    
560
    // Optimization
561
    optimize: 'uglify2',
562
    optimizeCss: 'standard',
563
    generateSourceMaps: true,
564
    preserveLicenseComments: false,
565
    
566
    // Content processing
567
    inlineText: true,
568
    useStrict: true,
569
    removeCombined: true,
570
    
571
    // Advanced features
572
    findNestedDependencies: true,
573
    writeBuildTxt: true,
574
    
575
    // File exclusions
576
    fileExclusionRegExp: /^(\.|build\.js$)/
577
};
578
```
579

580
## Types
581

582
```javascript { .api }
583
interface BuildConfig {
584
    appDir?: string;
585
    baseUrl?: string;
586
    dir?: string;
587
    mainConfigFile?: string | string[];
588
    modules?: ModuleConfig[];
589
    optimize?: 'uglify' | 'uglify2' | 'closure' | 'closure.keepLines' | 'none';
590
    optimizeCss?: 'standard' | 'standard.keepLines' | 'standard.keepComments' | 'none';
591
    generateSourceMaps?: boolean;
592
    preserveLicenseComments?: boolean;
593
    inlineText?: boolean;
594
    useStrict?: boolean;
595
    namespace?: string;
596
    skipModuleInsertion?: boolean;
597
    stubModules?: string[];
598
    removeCombined?: boolean;
599
    findNestedDependencies?: boolean;
600
    optimizeAllPluginResources?: boolean;
601
    writeBuildTxt?: boolean;
602
    pragmas?: { [key: string]: any };
603
    has?: { [key: string]: any };
604
    wrap?: { start?: string; end?: string };
605
    out?: string;
606
    logLevel?: number;
607
}
608

609
interface ModuleConfig {
610
    name: string;
611
    include?: string[];
612
    exclude?: string[];
613
    excludeShallow?: string[];
614
    create?: boolean;
615
    out?: string;
616
    override?: Partial<BuildConfig>;
617
}
618
```