0
# Configuration
1

2
RequireJS provides a comprehensive configuration system that allows you to customize module loading behavior, path resolution, dependency management, and many other aspects of the AMD loader.
3

4
## Capabilities
5

6
### Main Configuration Function
7

8
Configure the RequireJS loader with various options for customizing module loading behavior.
9

10
```javascript { .api }
11
/**
12
 * Configure RequireJS loader settings
13
 * @param {Object} config - Configuration object with various options
14
 */
15
function requirejs.config(config);
16
function require.config(config);
17
```
18

19
### Core Configuration Options
20

21
#### Base URL Configuration
22

23
Set the base path for module resolution.
24

25
```javascript { .api }
26
/**
27
 * Base URL for loading modules
28
 * @type {String}
29
 */
30
config.baseUrl;
31
```
32

33
**Usage:**
34

35
```javascript
36
requirejs.config({
37
    baseUrl: '/js/app'
38
});
39
```
40

41
#### Path Mappings
42

43
Map module names to specific file paths.
44

45
```javascript { .api }
46
/**
47
 * Path mappings for module names
48
 * @type {Object}
49
 */
50
config.paths;
51
```
52

53
**Usage:**
54

55
```javascript
56
requirejs.config({
57
    paths: {
58
        'jquery': 'vendor/jquery-3.6.0',
59
        'underscore': 'vendor/underscore-1.13.1',
60
        'backbone': 'vendor/backbone-1.4.0',
61
        'templates': '../templates',
62
        'app': 'application'
63
    }
64
});
65
```
66

67
#### Shim Configuration
68

69
Configure non-AMD scripts to work with RequireJS.
70

71
```javascript { .api }
72
/**
73
 * Shim configuration for non-AMD scripts
74
 * @type {Object}
75
 */
76
config.shim;
77

78
interface ShimConfig {
79
    deps?: string[];           // Dependencies for the shimmed script
80
    exports?: string;          // Global variable name to export
81
    init?: Function;          // Initialization function
82
}
83
```
84

85
**Usage:**
86

87
```javascript
88
requirejs.config({
89
    shim: {
90
        'backbone': {
91
            deps: ['underscore', 'jquery'],
92
            exports: 'Backbone'
93
        },
94
        'underscore': {
95
            exports: '_'
96
        },
97
        'jquery.plugin': {
98
            deps: ['jquery'],
99
            init: function() {
100
                return jQuery.noConflict();
101
            }
102
        }
103
    }
104
});
105
```
106

107
#### Module ID Mapping
108

109
Map one module ID to another for versioning and legacy support.
110

111
```javascript { .api }
112
/**
113
 * Module ID mappings for versioning and compatibility
114
 * @type {Object}
115
 */
116
config.map;
117
```
118

119
**Usage:**
120

121
```javascript
122
requirejs.config({
123
    map: {
124
        '*': {
125
            'oldModule': 'newModule',
126
            'legacy': 'modern-replacement'
127
        },
128
        'some/newmodule': {
129
            'foo': 'foo1.2'
130
        }
131
    }
132
});
133
```
134

135
### Package Configuration
136

137
Configure package-style modules with main files and locations.
138

139
```javascript { .api }
140
/**
141
 * Package configurations for multi-file modules
142
 * @type {Array}
143
 */
144
config.packages;
145

146
interface PackageConfig {
147
    name: string;              // Package name
148
    location?: string;         // Package location (relative to baseUrl)
149
    main?: string;            // Main module file (default: 'main')
150
}
151
```
152

153
**Usage:**
154

155
```javascript
156
requirejs.config({
157
    packages: [
158
        {
159
            name: 'myPackage',
160
            location: 'vendor/myPackage',
161
            main: 'index'
162
        },
163
        {
164
            name: 'dojo',
165
            location: 'vendor/dojo',
166
            main: 'main'
167
        }
168
    ]
169
});
170
```
171

172
### Module-Specific Configuration
173

174
Pass configuration data to specific modules.
175

176
```javascript { .api }
177
/**
178
 * Module-specific configuration data
179
 * @type {Object}
180
 */
181
config.config;
182
```
183

184
**Usage:**
185

186
```javascript
187
requirejs.config({
188
    config: {
189
        'app/module': {
190
            apiKey: 'abc123',
191
            debug: true,
192
            endpoint: 'https://api.example.com'
193
        }
194
    }
195
});
196

197
// In app/module.js
198
define(['module'], function(module) {
199
    var config = module.config();
200
    console.log(config.apiKey); // 'abc123'
201
});
202
```
203

204
### Dependency and Callback Configuration
205

206
Configure initial dependencies and startup callback.
207

208
```javascript { .api }
209
/**
210
 * Dependencies to load immediately
211
 * @type {Array}
212
 */
213
config.deps;
214

215
/**
216
 * Callback function executed after deps are loaded
217
 * @type {Function}
218
 */
219
config.callback;
220
```
221

222
**Usage:**
223

224
```javascript
225
requirejs.config({
226
    deps: ['app/main', 'app/init'],
227
    callback: function() {
228
        console.log('Application initialized');
229
    }
230
});
231
```
232

233
### Advanced Configuration Options
234

235
#### Enforcement and Validation
236

237
```javascript { .api }
238
/**
239
 * Enforce that all scripts call define()
240
 * @type {Boolean}
241
 */
242
config.enforceDefine;
243

244
/**
245
 * Wait for all define() calls before executing
246
 * @type {Boolean}
247
 */
248
config.waitSeconds;
249
```
250

251
**Usage:**
252

253
```javascript
254
requirejs.config({
255
    enforceDefine: true,
256
    waitSeconds: 30  // 30 second timeout
257
});
258
```
259

260
#### URL and Script Configuration
261

262
```javascript { .api }
263
/**
264
 * Query string arguments to append to URLs
265
 * @type {String}
266
 */
267
config.urlArgs;
268

269
/**
270
 * Script tag type attribute
271
 * @type {String}
272
 */
273
config.scriptType;
274

275
/**
276
 * Create script tags compatible with XHTML
277
 * @type {Boolean}
278
 */
279
config.xhtml;
280

281
/**
282
 * Skip processing data-main attribute
283
 * @type {Boolean}
284
 */
285
config.skipDataMain;
286
```
287

288
**Usage:**
289

290
```javascript
291
requirejs.config({
292
    urlArgs: 'bust=' + (new Date()).getTime(),
293
    scriptType: 'text/javascript',
294
    xhtml: false,
295
    skipDataMain: false
296
});
297
```
298

299
#### Context Configuration
300

301
```javascript { .api }
302
/**
303
 * Context name for this configuration
304
 * @type {String}
305
 */
306
config.context;
307

308
/**
309
 * Node.js specific options
310
 * @type {Object}
311
 */
312
config.nodeIdCompat;
313
```
314

315
**Usage:**
316

317
```javascript
318
// Create isolated context
319
const myContext = requirejs.config({
320
    context: 'myApp',
321
    baseUrl: '/js/myapp',
322
    paths: {
323
        'lib': 'libraries'
324
    }
325
});
326

327
// Use context-specific require
328
myContext(['lib/helper'], function(helper) {
329
    helper.initialize();
330
});
331
```
332

333
## Configuration Examples
334

335
### Basic Web Application
336

337
```javascript
338
requirejs.config({
339
    baseUrl: '/js',
340
    paths: {
341
        'jquery': 'vendor/jquery-3.6.0.min',
342
        'bootstrap': 'vendor/bootstrap.bundle.min',
343
        'app': 'application'
344
    },
345
    shim: {
346
        'bootstrap': {
347
            deps: ['jquery']
348
        }
349
    },
350
    deps: ['app/main']
351
});
352
```
353

354
### Node.js Application
355

356
```javascript
357
const requirejs = require('requirejs');
358

359
requirejs.config({
360
    nodeRequire: require,
361
    baseUrl: __dirname + '/lib',
362
    paths: {
363
        'lodash': '../node_modules/lodash/lodash'
364
    }
365
});
366
```
367

368
### Development vs Production
369

370
```javascript
371
// Development configuration
372
requirejs.config({
373
    baseUrl: '/js',
374
    urlArgs: 'bust=' + Date.now(),  // Cache busting
375
    paths: {
376
        'jquery': 'vendor/jquery-3.6.0',  // Unminified
377
        'app': 'src'
378
    }
379
});
380

381
// Production configuration
382
requirejs.config({
383
    baseUrl: '/js',
384
    paths: {
385
        'jquery': 'vendor/jquery-3.6.0.min',  // Minified
386
        'app': 'dist'
387
    }
388
});
389
```
390

391
### Multi-Version Module Support
392

393
```javascript
394
requirejs.config({
395
    paths: {
396
        'jquery': 'vendor/jquery-3.6.0',
397
        'jquery2': 'vendor/jquery-2.2.4'
398
    },
399
    map: {
400
        'legacy-module': {
401
            'jquery': 'jquery2'
402
        },
403
        '*': {
404
            'jquery': 'jquery'
405
        }
406
    }
407
});
408
```
409

410
## Environment-Specific Configuration
411

412
### Browser Detection
413

414
```javascript
415
if (typeof window !== 'undefined') {
416
    // Browser environment
417
    requirejs.config({
418
        baseUrl: '/js',
419
        paths: {
420
            'dom': 'browser/dom-utils'
421
        }
422
    });
423
} else {
424
    // Node.js environment
425
    requirejs.config({
426
        nodeRequire: require,
427
        baseUrl: __dirname + '/lib',
428
        paths: {
429
            'fs': 'node/file-utils'
430
        }
431
    });
432
}
433
```
434

435
### Conditional Module Loading
436

437
```javascript
438
requirejs.config({
439
    map: {
440
        '*': {
441
            'http': typeof window !== 'undefined' ? 'browser/http' : 'node/http',
442
            'storage': typeof localStorage !== 'undefined' ? 'browser/storage' : 'node/storage'
443
        }
444
    }
445
});
446
```
447

448
## Configuration Validation
449

450
RequireJS validates configuration options and provides helpful error messages:
451

452
```javascript
453
// Invalid configuration will log warnings
454
requirejs.config({
455
    baseUrl: '/js',
456
    paths: {
457
        'invalid-path': function() {} // Error: paths must be strings
458
    }
459
});
460
```
461

462
## Types
463

464
```javascript { .api }
465
interface RequireConfig {
466
    baseUrl?: string;
467
    paths?: { [key: string]: string };
468
    shim?: { [key: string]: ShimConfig };
469
    map?: { [key: string]: { [key: string]: string } };
470
    packages?: PackageConfig[];
471
    config?: { [key: string]: any };
472
    deps?: string[];
473
    callback?: Function;
474
    enforceDefine?: boolean;
475
    xhtml?: boolean;
476
    urlArgs?: string;
477
    scriptType?: string;
478
    skipDataMain?: boolean;
479
    context?: string;
480
    waitSeconds?: number;
481
    nodeIdCompat?: boolean;
482
}
483

484
interface ShimConfig {
485
    deps?: string[];
486
    exports?: string;
487
    init?: Function;
488
}
489

490
interface PackageConfig {
491
    name: string;
492
    location?: string;
493
    main?: string;
494
}
495
```