0
# Formatting
1

2
Rome's formatter provides automatic code formatting that replaces Prettier, with support for JavaScript, TypeScript, JSON, and CSS files. It focuses on opinionated defaults while allowing key customizations.
3

4
## Capabilities
5

6
### Format Command
7

8
The primary formatting command that processes files and directories.
9

10
```bash { .api }
11
/**
12
 * Format files according to Rome's style rules
13
 * 
14
 * Usage: rome format [OPTIONS] <INPUTS...>
15
 *
16
 * INPUTS can be one or more filesystem paths, each pointing to a single file 
17
 * or an entire directory to be searched recursively for supported files
18
 */
19
rome format <INPUTS...>
20
```
21

22
**Core Options:**
23

24
```bash { .api }
25
--write                    # Edit files in place instead of printing diff to console
26
--skip-errors             # Skip files with syntax errors instead of emitting error diagnostic  
27
--max-diagnostics <number> # Cap the amount of diagnostics displayed (default: 50)
28
--verbose                 # Print additional verbose advice on diagnostics
29
--stdin-file-path <string> # File name with extension for reading from stdin
30
--json                    # Output results in JSON format
31
```
32

33
**Usage Examples:**
34

35
```bash
36
# Format and display diff
37
rome format src/
38

39
# Format files in place
40
rome format src/ --write
41

42
# Format single file
43
rome format src/index.js --write
44

45
# Format from stdin with file extension
46
echo 'const x=1;' | rome format --stdin-file-path=file.js
47

48
# Format with verbose output
49
rome format src/ --verbose
50

51
# Skip files with syntax errors
52
rome format src/ --skip-errors --write
53
```
54

55
### Indentation Options
56

57
Control how code is indented.
58

59
```bash { .api }
60
--indent-style <tabs|space>  # Change indentation character (default: tabs)
61
--indent-size <number>       # Spaces for indentation when using space style (default: 2)
62
```
63

64
**Usage Examples:**
65

66
```bash
67
# Use spaces instead of tabs
68
rome format src/ --indent-style=space --write
69

70
# Use 4 spaces for indentation
71
rome format src/ --indent-style=space --indent-size=4 --write
72

73
# Use tabs (default)
74
rome format src/ --indent-style=tabs --write
75
```
76

77
### Line Length Options
78

79
Control line wrapping behavior.
80

81
```bash { .api }
82
--line-width <number>  # Maximum characters the formatter is allowed per line (default: 80)
83
```
84

85
**Usage Examples:**
86

87
```bash
88
# Allow longer lines
89
rome format src/ --line-width=120 --write
90

91
# Shorter lines for readability
92
rome format src/ --line-width=60 --write
93
```
94

95
### Quote Style Options
96

97
Control quotation marks in strings and object properties.
98

99
```bash { .api }
100
--quote-style <single|double>                # Quotation character for strings (default: double)
101
--quote-properties <as-needed|preserve>      # When properties in objects should be quoted (default: as-needed)
102
```
103

104
**Usage Examples:**
105

106
```bash
107
# Use single quotes for strings
108
rome format src/ --quote-style=single --write
109

110
# Always preserve existing property quotes
111
rome format src/ --quote-properties=preserve --write
112

113
# Minimal property quoting (default)
114
rome format src/ --quote-properties=as-needed --write
115
```
116

117
### Trailing Comma Options
118

119
Control trailing comma behavior in multi-line structures.
120

121
```bash { .api }
122
--trailing-comma <all|es5|none>  # Changes trailing commas in multi-line comma-separated syntactic structures (default: all)
123
```
124

125
**Values:**
126
- `all` - Trailing commas wherever possible (including function parameters)
127
- `es5` - Trailing commas where valid in ES5 (objects, arrays)  
128
- `none` - No trailing commas
129

130
**Usage Examples:**
131

132
```bash
133
# Trailing commas everywhere
134
rome format src/ --trailing-comma=all --write
135

136
# ES5-compatible trailing commas
137
rome format src/ --trailing-comma=es5 --write
138

139
# No trailing commas
140
rome format src/ --trailing-comma=none --write
141
```
142

143
### Semicolon Options
144

145
Control semicolon usage in statements.
146

147
```bash { .api }
148
--semicolons <always|as-needed>  # When to print semicolons for statements (default: always)
149
```
150

151
**Usage Examples:**
152

153
```bash
154
# Always use semicolons (default)
155
rome format src/ --semicolons=always --write
156

157
# Only use semicolons when required
158
rome format src/ --semicolons=as-needed --write
159
```
160

161
## Configuration File Usage
162

163
All formatting options can be specified in `rome.json`:
164

165
```json
166
{
167
  "formatter": {
168
    "enabled": true,
169
    "formatWithErrors": false,
170
    "indentStyle": "space",
171
    "indentSize": 2,
172
    "lineWidth": 100,
173
    "ignore": ["dist/**"]
174
  },
175
  "javascript": {
176
    "formatter": {
177
      "quoteStyle": "single",
178
      "quoteProperties": "asNeeded",
179
      "trailingComma": "all",
180
      "semicolons": "always"
181
    }
182
  }
183
}
184
```
185

186
## Language-Specific Behavior
187

188
### JavaScript/TypeScript
189

190
Rome formats JavaScript and TypeScript files with full syntax support including:
191

192
- **Modern syntax**: ES2022+ features, TypeScript types
193
- **JSX support**: React JSX and TSX files
194
- **Module formats**: ESM imports/exports, CommonJS require/module.exports
195
- **Decorators**: Experimental and legacy decorator syntax
196
- **Async/await**: Proper formatting for async functions and expressions
197

198
### JSON
199

200
Rome formats JSON files with:
201

202
- **Trailing commas**: Configurable support for trailing commas in JSON
203
- **Comments**: Support for JSONC (JSON with Comments) files
204
- **Consistent indentation**: Proper alignment and spacing
205
- **Array/object formatting**: Intelligent multi-line formatting
206

207
### CSS
208

209
Rome provides basic CSS formatting support including:
210

211
- **Property alignment**: Consistent spacing around colons and semicolons
212
- **Selector formatting**: Proper indentation and line breaks
213
- **Declaration blocks**: Organized property ordering
214

215
## Error Handling
216

217
The formatter handles various error conditions:
218

219
### Syntax Errors
220

221
```bash
222
# Skip files with syntax errors
223
rome format src/ --skip-errors --write
224

225
# Default behavior: report syntax errors
226
rome format src/
227
```
228

229
### File Access Errors
230

231
- **Permission errors**: Reports files that cannot be read/written
232
- **Large files**: Respects `--files-max-size` limit
233
- **Binary files**: Automatically skips non-text files
234

235
### Output Formats
236

237
```bash
238
# Human-readable output (default)
239
rome format src/
240

241
# JSON output for tooling integration
242
rome format src/ --json
243
```