0
# Configuration
1
2
Rome's configuration system provides extensive customization options through the `rome.json` file, with sensible defaults and the ability to override settings via command-line arguments.
3
4
## Capabilities
5
6
### Project Initialization
7
8
Initialize a new Rome project with default configuration.
9
10
```bash { .api }
11
/**
12
* Bootstrap a new rome project
13
*
14
* Usage: rome init
15
*
16
* Creates a rome.json configuration file in the current directory
17
*/
18
rome init
19
```
20
21
**Usage Examples:**
22
23
```bash
24
# Initialize in current directory
25
rome init
26
27
# Creates rome.json with default settings
28
```
29
30
### Configuration File Structure
31
32
Rome uses a `rome.json` file for project configuration with the following structure:
33
34
```json { .api }
35
{
36
"$schema": "./node_modules/rome/configuration_schema.json",
37
"files": {
38
"maxSize": 1048576,
39
"ignore": ["dist/**", "node_modules/**"]
40
},
41
"formatter": {
42
"enabled": true,
43
"formatWithErrors": false,
44
"indentStyle": "tabs",
45
"indentSize": 2,
46
"lineWidth": 80,
47
"ignore": []
48
},
49
"linter": {
50
"enabled": true,
51
"rules": {
52
"recommended": true,
53
"a11y": { "recommended": true },
54
"complexity": { "recommended": true },
55
"correctness": { "recommended": true },
56
"performance": { "recommended": true },
57
"security": { "recommended": true },
58
"style": { "recommended": true },
59
"suspicious": { "recommended": true }
60
},
61
"ignore": []
62
},
63
"javascript": {
64
"formatter": {
65
"quoteStyle": "double",
66
"quoteProperties": "asNeeded",
67
"trailingComma": "all",
68
"semicolons": "always"
69
},
70
"globals": ["console", "process"]
71
}
72
}
73
```
74
75
## Configuration Sections
76
77
### Files Configuration
78
79
Global file handling settings that apply to all Rome tools.
80
81
```json { .api }
82
{
83
"files": {
84
"maxSize": 1048576, // Maximum file size in bytes (default: 1MB)
85
"ignore": [ // Files and patterns to ignore globally
86
"dist/**",
87
"build/**",
88
"node_modules/**",
89
"*.min.js",
90
"coverage/**"
91
]
92
}
93
}
94
```
95
96
**Properties:**
97
98
- `maxSize`: Maximum allowed size for source code files in bytes
99
- `ignore`: Array of Unix shell style patterns (glob patterns) to ignore
100
101
**Usage Examples:**
102
103
```json
104
{
105
"files": {
106
"maxSize": 2097152, // 2MB limit
107
"ignore": [
108
"dist/**", // Ignore dist directory
109
"**/*.min.js", // Ignore minified files
110
"test/fixtures/**" // Ignore test fixtures
111
]
112
}
113
}
114
```
115
116
### Formatter Configuration
117
118
Settings for Rome's code formatter.
119
120
```json { .api }
121
{
122
"formatter": {
123
"enabled": true, // Enable/disable formatter (default: true)
124
"formatWithErrors": false, // Format files with syntax errors (default: false)
125
"indentStyle": "tabs", // "tabs" | "space" (default: "tabs")
126
"indentSize": 2, // Number of spaces when indentStyle is "space" (default: 2)
127
"lineWidth": 80, // Maximum line width (default: 80)
128
"ignore": [] // Files to exclude from formatting
129
}
130
}
131
```
132
133
**Usage Examples:**
134
135
```json
136
{
137
"formatter": {
138
"enabled": true,
139
"indentStyle": "space",
140
"indentSize": 4,
141
"lineWidth": 120,
142
"ignore": ["src/legacy/**"]
143
}
144
}
145
```
146
147
### JavaScript Formatter Configuration
148
149
JavaScript and TypeScript specific formatting options.
150
151
```json { .api }
152
{
153
"javascript": {
154
"formatter": {
155
"quoteStyle": "double", // "single" | "double" (default: "double")
156
"quoteProperties": "asNeeded", // "asNeeded" | "preserve" (default: "asNeeded")
157
"trailingComma": "all", // "all" | "es5" | "none" (default: "all")
158
"semicolons": "always" // "always" | "asNeeded" (default: "always")
159
}
160
}
161
}
162
```
163
164
**Trailing Comma Options:**
165
- `"all"`: Trailing commas wherever possible (including function parameters)
166
- `"es5"`: Trailing commas where valid in ES5 (objects, arrays)
167
- `"none"`: No trailing commas
168
169
**Usage Examples:**
170
171
```json
172
{
173
"javascript": {
174
"formatter": {
175
"quoteStyle": "single",
176
"trailingComma": "es5",
177
"semicolons": "asNeeded"
178
}
179
}
180
}
181
```
182
183
### Linter Configuration
184
185
Settings for Rome's linter and rule configuration.
186
187
```json { .api }
188
{
189
"linter": {
190
"enabled": true, // Enable/disable linter (default: true)
191
"rules": {
192
"recommended": true, // Enable all recommended rules
193
"all": false // Enable all available rules (overrides recommended)
194
},
195
"ignore": [] // Files to exclude from linting
196
}
197
}
198
```
199
200
### Rule Group Configuration
201
202
Configure entire rule groups or individual rules.
203
204
```json { .api }
205
{
206
"linter": {
207
"rules": {
208
"a11y": {
209
"recommended": true, // Enable recommended accessibility rules
210
"noAutofocus": "error", // Individual rule: "error" | "warn" | "off"
211
"noBlankTarget": "warn",
212
"useAltText": "off"
213
},
214
"correctness": {
215
"recommended": true,
216
"noUnusedVariables": "error",
217
"noConstAssign": "error"
218
},
219
"style": {
220
"recommended": false, // Disable entire group
221
"useConst": "error" // But enable specific rules
222
}
223
}
224
}
225
}
226
```
227
228
**Rule Severity Levels:**
229
- `"error"`: Rule violation causes build failure
230
- `"warn"`: Rule violation reported as warning
231
- `"off"`: Rule disabled
232
233
### JavaScript Configuration
234
235
JavaScript and TypeScript specific settings.
236
237
```json { .api }
238
{
239
"javascript": {
240
"formatter": {
241
// Formatter options (see above)
242
},
243
"globals": [ // Global variables available in code
244
"console",
245
"process",
246
"Buffer",
247
"$",
248
"jQuery"
249
]
250
}
251
}
252
```
253
254
## Command Line Overrides
255
256
Configuration file settings can be overridden via command-line arguments:
257
258
```bash { .api }
259
# Override formatter settings
260
rome format src/ --indent-style=space --line-width=120
261
262
# Override linter settings
263
rome check src/ --max-diagnostics=50
264
265
# Override file size limits
266
rome check src/ --files-max-size=2097152
267
```
268
269
## Schema Validation
270
271
Rome provides JSON schema validation for configuration files:
272
273
```json { .api }
274
{
275
"$schema": "./node_modules/rome/configuration_schema.json",
276
// ... rest of configuration
277
}
278
```
279
280
This enables:
281
- **IDE support**: Autocomplete and validation in editors
282
- **Error detection**: Invalid configuration detection
283
- **Documentation**: Inline help for configuration options
284
285
## Configuration Discovery
286
287
Rome searches for configuration in the following order:
288
289
1. `rome.json` in current directory
290
2. `rome.json` in parent directories (walking up)
291
3. Default configuration if no file found
292
293
```bash { .api }
294
# Force specific configuration file
295
rome check src/ --config-path=./custom-rome.json
296
```
297
298
## Example Configurations
299
300
### Minimal Configuration
301
302
```json
303
{
304
"formatter": {
305
"enabled": true
306
},
307
"linter": {
308
"enabled": true,
309
"rules": {
310
"recommended": true
311
}
312
}
313
}
314
```
315
316
### Strict Configuration
317
318
```json
319
{
320
"files": {
321
"maxSize": 524288,
322
"ignore": ["dist/**", "coverage/**"]
323
},
324
"formatter": {
325
"enabled": true,
326
"indentStyle": "space",
327
"indentSize": 2,
328
"lineWidth": 100
329
},
330
"linter": {
331
"enabled": true,
332
"rules": {
333
"recommended": true,
334
"correctness": {
335
"recommended": true,
336
"noUnusedVariables": "error"
337
},
338
"suspicious": {
339
"recommended": true,
340
"noExplicitAny": "error"
341
}
342
}
343
},
344
"javascript": {
345
"formatter": {
346
"quoteStyle": "single",
347
"semicolons": "always"
348
}
349
}
350
}
351
```
352
353
### Team Configuration
354
355
```json
356
{
357
"$schema": "./node_modules/rome/configuration_schema.json",
358
"files": {
359
"ignore": [
360
"dist/**",
361
"build/**",
362
"node_modules/**",
363
"*.min.js",
364
"coverage/**",
365
"docs/**"
366
]
367
},
368
"formatter": {
369
"enabled": true,
370
"indentStyle": "space",
371
"indentSize": 2,
372
"lineWidth": 120
373
},
374
"linter": {
375
"enabled": true,
376
"rules": {
377
"recommended": true,
378
"a11y": {
379
"recommended": true
380
},
381
"correctness": {
382
"recommended": true,
383
"noUnusedVariables": "error"
384
},
385
"style": {
386
"recommended": true,
387
"useConst": "error",
388
"noVar": "error"
389
}
390
}
391
},
392
"javascript": {
393
"formatter": {
394
"quoteStyle": "single",
395
"trailingComma": "es5",
396
"semicolons": "always"
397
},
398
"globals": ["process", "console", "Buffer"]
399
}
400
}
401
```
402
403
### Gradual Adoption Configuration
404
405
```json
406
{
407
"formatter": {
408
"enabled": false // Disable formatter initially
409
},
410
"linter": {
411
"enabled": true,
412
"rules": {
413
"correctness": {
414
"recommended": true,
415
"noUnusedVariables": "warn" // Start with warnings
416
},
417
"suspicious": {
418
"recommended": false,
419
"noDebugger": "error" // Enable critical rules only
420
}
421
},
422
"ignore": [
423
"src/legacy/**" // Ignore legacy code initially
424
]
425
}
426
}
427
```
428
429
## Configuration Validation
430
431
Rome validates configuration files and provides helpful error messages:
432
433
```bash
434
# Check configuration validity
435
rome check src/
436
437
# Example error for invalid configuration:
438
# Configuration error: Unknown property "invalidOption" at root level
439
# Valid properties are: files, formatter, linter, javascript
440
```
441
442
## Environment-Specific Configuration
443
444
Use different configurations for different environments:
445
446
```json
447
{
448
"formatter": {
449
"enabled": true
450
},
451
"linter": {
452
"enabled": true,
453
"rules": {
454
"recommended": true,
455
"suspicious": {
456
"noDebugger": "warn" // Warn in development
457
}
458
}
459
}
460
}
461
```
462
463
Then override for production:
464
465
```bash
466
# Production CI with strict rules
467
rome ci src/ --max-diagnostics=0 # Fail on any issues
468
```