0
# Configuration Options
1

2
Comprehensive configuration system for JS Beautify with base options shared across all beautifiers and language-specific extensions. Supports EditorConfig integration, hierarchical option inheritance, and multiple configuration sources.
3

4
## Capabilities
5

6
### Base Options Interface
7

8
Core configuration options shared by all beautifiers (JavaScript, CSS, HTML).
9

10
```javascript { .api }
11
/**
12
 * Base configuration options shared by all beautifiers
13
 * @typedef {Object} BaseOptions
14
 * @property {boolean} [disabled=false] - Disable beautification entirely - returns source unchanged
15
 * @property {string} [eol='auto'] - Character(s) to use as line terminators (auto-detect or '\n')
16
 * @property {boolean} [end_with_newline=false] - End output with newline
17
 * @property {number} [indent_size=4] - Indentation size in spaces
18
 * @property {string} [indent_char=' '] - Character used for indentation
19
 * @property {number} [indent_level=0] - Initial indentation level
20
 * @property {boolean} [preserve_newlines=true] - Preserve existing line-breaks
21
 * @property {number} [max_preserve_newlines=32786] - Maximum number of line-breaks to preserve in one chunk
22
 * @property {boolean} [indent_with_tabs=false] - Use tabs for indentation, overrides indent_size and indent_char
23
 * @property {number} [wrap_line_length=0] - Wrap lines that exceed N characters (0 disables)
24
 * @property {boolean} [indent_empty_lines=false] - Keep indentation on empty lines
25
 * @property {string[]} [templating=['auto']] - List of templating languages to support: 'auto', 'none', 'angular', 'django', 'erb', 'handlebars', 'php', 'smarty'
26
 */
27
```
28

29
### Default Options Function
30

31
Returns default configuration for any beautifier.
32

33
```javascript { .api }
34
/**
35
 * Get default options for a beautifier
36
 * @returns {Object} BaseOptions with default values
37
 */
38
function defaultOptions();
39
```
40

41
**Usage Example:**
42

43
```javascript
44
const beautify = require('js-beautify');
45

46
// Get default options for JavaScript
47
const jsDefaults = beautify.js.defaultOptions();
48

49
// Get default options for CSS  
50
const cssDefaults = beautify.css.defaultOptions();
51

52
// Get default options for HTML
53
const htmlDefaults = beautify.html.defaultOptions();
54

55
// All return objects with BaseOptions plus language-specific options
56
console.log(jsDefaults.indent_size); // 4
57
console.log(jsDefaults.preserve_newlines); // true
58
```
59

60
## Configuration Sources
61

62
### Direct Options Object
63
Pass options directly to beautifier functions:
64

65
```javascript
66
const beautified = beautify.js(code, {
67
  indent_size: 2,
68
  brace_style: 'expand',
69
  preserve_newlines: false
70
});
71
```
72

73
### Environment Variables (JavaScript Only)
74
Any environment variable prefixed with `jsbeautify_` is used as configuration:
75

76
```bash
77
export jsbeautify_indent_size=2
78
export jsbeautify_brace_style=expand
79
node my-script.js
80
```
81

82
### Configuration Files (JavaScript Only)
83
JSON-formatted configuration can be loaded from:
84

85
#### Command Line Config
86
```bash
87
js-beautify --config /path/to/config.json file.js
88
```
89

90
#### .jsbeautifyrc Files
91
Automatically loaded from current directory or parent directories:
92

93
```json
94
{
95
  "indent_size": 2,
96
  "brace_style": "expand",
97
  "html": {
98
    "indent_size": 4,
99
    "wrap_attributes": "force"
100
  }
101
}
102
```
103

104
### EditorConfig Support
105
When `editorconfig: true` is set, reads formatting settings from `.editorconfig` files:
106

107
```ini
108
# .editorconfig
109
[*.js]
110
indent_style = space
111
indent_size = 2
112
end_of_line = lf
113
insert_final_newline = true
114

115
[*.html]  
116
indent_size = 4
117
```
118

119
**Usage:**
120
```javascript
121
const beautified = beautify.js(code, { 
122
  editorconfig: true 
123
});
124
```
125

126
## Hierarchical Configuration
127

128
### Language-Specific Overrides
129
Base options can be overridden for specific languages:
130

131
```json
132
{
133
  "indent_size": 4,
134
  "preserve_newlines": true,
135
  "js": {
136
    "indent_size": 2,
137
    "brace_style": "expand"
138
  },
139
  "css": {
140
    "indent_size": 2,
141
    "newline_between_rules": false
142
  },
143
  "html": {
144
    "indent_size": 4, 
145
    "wrap_attributes": "force",
146
    "js": {
147
      "indent_size": 2
148
    },
149
    "css": {
150
      "indent_size": 2
151
    }
152
  }
153
}
154
```
155

156
**Inheritance Behavior:**
157
- JavaScript files inherit `indent_size: 2` and `brace_style: 'expand'`
158
- CSS files inherit `indent_size: 2` and `newline_between_rules: false`
159
- HTML files use `indent_size: 4` and `wrap_attributes: 'force'`
160
- JavaScript inside HTML uses `indent_size: 2`
161
- CSS inside HTML uses `indent_size: 2`
162

163
### Configuration Priority
164
Configuration sources are applied in order of precedence (highest to lowest):
165

166
1. Direct options object passed to function
167
2. Environment variables (`jsbeautify_*`)
168
3. Command line `--config` file
169
4. `.jsbeautifyrc` file in current/parent directories
170
5. Default options
171

172
## Common Configuration Patterns
173

174
### Tab Indentation
175
```javascript
176
const options = {
177
  indent_with_tabs: true,
178
  indent_size: 4  // Tab width for display
179
};
180
```
181

182
### Strict Line Length
183
```javascript
184
const options = {
185
  wrap_line_length: 80,
186
  preserve_newlines: false,
187
  max_preserve_newlines: 1
188
};
189
```
190

191
### Minimal Formatting
192
```javascript
193
const options = {
194
  preserve_newlines: false,
195
  max_preserve_newlines: 0,
196
  indent_empty_lines: false,
197
  end_with_newline: false
198
};
199
```
200

201
### Development vs Production
202
```javascript
203
// Development - preserve developer formatting
204
const devOptions = {
205
  preserve_newlines: true,
206
  max_preserve_newlines: 10,
207
  indent_empty_lines: true
208
};
209

210
// Production - compact formatting  
211
const prodOptions = {
212
  preserve_newlines: false,
213
  max_preserve_newlines: 1,
214
  wrap_line_length: 120,
215
  end_with_newline: false
216
};
217
```
218

219
## Option Validation and Normalization
220

221
### Option Name Normalization
222
Dashes in option names are automatically converted to underscores:
223

224
```javascript
225
// These are equivalent:
226
{ 'indent-size': 2, 'brace-style': 'expand' }
227
{ 'indent_size': 2, 'brace_style': 'expand' }
228
```
229

230
### Type Coercion
231
Options are automatically coerced to appropriate types:
232

233
```javascript
234
// String numbers become integers
235
{ indent_size: '2' } // becomes { indent_size: 2 }
236

237
// String booleans become booleans  
238
{ preserve_newlines: 'false' } // becomes { preserve_newlines: false }
239
```
240

241
### Invalid Option Handling
242
Invalid options throw descriptive errors:
243

244
```javascript
245
// This will throw an error
246
beautify.js(code, { 
247
  brace_style: 'invalid-style' 
248
});
249
// Error: Invalid Option Value: The option 'brace_style' can only be one of the following values:
250
// collapse,expand,end-expand,none,preserve-inline
251
// You passed in: 'invalid-style'
252
```
253

254
## Template Language Configuration
255

256
### Auto Detection
257
```javascript
258
{
259
  templating: ['auto']  // Default for HTML, detects all supported templates
260
}
261
```
262

263
### Specific Languages
264
```javascript
265
{
266
  templating: ['handlebars', 'django']  // Only these templates
267
}
268
```
269

270
### Disable Templates
271
```javascript
272
{
273
  templating: ['none']  // No template processing
274
}
275
```
276

277
**Supported Templates:**
278
- `angular` - Angular template syntax `{{ }}`
279
- `django` - Django template syntax `{% %}`, `{{ }}`
280
- `erb` - ERB template syntax `<% %>`, `<%= %>`
281
- `handlebars` - Handlebars syntax `{{ }}`, `{{# }}`
282
- `php` - PHP syntax `<?php ?>`, `<? ?>`
283
- `smarty` - Smarty syntax `{$var}`, `{if}`