0
# Rome
1

2
Rome is a comprehensive web development toolchain that unifies functionality traditionally provided by separate tools like Babel, ESLint, webpack, Prettier, and Jest. Written in Rust for performance, it provides formatting, linting, bundling capabilities for JavaScript, TypeScript, JSON, HTML, Markdown, and CSS with strong conventions and minimal configuration.
3

4
## Package Information
5

6
- **Package Name**: rome
7
- **Package Type**: npm
8
- **Language**: Rust (distributed via npm)
9
- **Installation**: `npm install rome`
10
- **Documentation**: https://docs.rome.tools/
11
- **Repository**: https://github.com/rome/tools
12

13
## Core Imports
14

15
Rome is primarily used as a CLI tool rather than a library. It provides executable commands through npm scripts or direct CLI usage:
16

17
```bash
18
# Via npx
19
npx rome format src/
20

21
# Via npm scripts (in package.json)
22
"scripts": {
23
  "format": "rome format src/",
24
  "lint": "rome check src/",
25
  "ci": "rome ci src/"
26
}
27
```
28

29
## Basic Usage
30

31
```bash
32
# Format files
33
rome format src/
34

35
# Check (lint) files with auto-fix
36
rome check src/ --apply
37

38
# Combined format check and linting for CI
39
rome ci src/
40

41
# Initialize Rome configuration
42
rome init
43

44
# Start daemon for faster subsequent runs
45
rome start
46
rome check src/ --use-server
47
rome stop
48
```
49

50
## Architecture
51

52
Rome is built around several key components:
53

54
- **CLI Interface**: Primary interaction through command-line commands
55
- **Language Support**: Parsers and formatters for JavaScript, TypeScript, JSON, and CSS
56
- **Configuration System**: Flexible configuration via `rome.json` with sensible defaults
57
- **Daemon Mode**: Optional server mode for improved performance across multiple operations
58
- **Language Server**: LSP implementation for editor integration
59

60
## Capabilities
61

62
### Formatting
63

64
Code formatting functionality that replaces Prettier, with support for JavaScript, TypeScript, JSON, and CSS files.
65

66
```bash { .api }
67
rome format [OPTIONS] <INPUTS...>
68

69
# Key options:
70
--write                    # Edit files in place
71
--skip-errors             # Skip files with syntax errors
72
--json                    # Output results in JSON format
73
--stdin-file-path <string> # File name with extension for reading from stdin
74
--max-diagnostics <number> # Cap diagnostics displayed (default: 50)
75
--verbose                 # Print additional verbose advice
76
--indent-style <tabs|space>  # Change indentation character (default: tabs)  
77
--indent-size <number>     # Spaces for indentation when using space style (default: 2)
78
--line-width <number>      # Maximum characters per line (default: 80)
79
--quote-style <single|double>  # Quotation character for strings (default: double)
80
```
81

82
[Formatting](./formatting.md)
83

84
### Linting and Code Analysis
85

86
Static analysis and linting functionality that replaces ESLint, with extensive rules for code quality, accessibility, performance, and security.
87

88
```bash { .api }
89
rome check [OPTIONS] <INPUTS...>
90

91
# Key options:
92
--apply                    # Apply safe fixes
93
--apply-suggested         # Apply safe and suggested fixes
94
--max-diagnostics <number>  # Cap diagnostics displayed (default: 20)
95
--verbose                 # Print additional verbose advice
96
```
97

98
[Linting](./linting.md)
99

100
### Continuous Integration
101

102
Combined formatting and linting checks optimized for CI/CD environments.
103

104
```bash { .api }
105
rome ci [OPTIONS] <INPUTS...>
106

107
# Key options:
108
--formatter-enabled       # Enable/disable formatter check (default: true)
109
--linter-enabled         # Enable/disable linter check (default: true)
110
--max-diagnostics <number>  # Cap diagnostics displayed (default: 50)
111
--verbose                 # Print additional verbose advice
112
```
113

114
[CI Integration](./ci-integration.md)
115

116
### Configuration Management
117

118
Configuration system supporting project initialization and extensive customization options.
119

120
```bash { .api }
121
rome init                 # Bootstrap new rome project
122

123
# Configuration via rome.json:
124
{
125
  "formatter": { "enabled": true, "indentStyle": "space" },
126
  "linter": { "enabled": true, "rules": { "recommended": true } },
127
  "files": { "ignore": ["dist/**", "node_modules/**"] }
128
}
129
```
130

131
[Configuration](./configuration.md)
132

133
### Daemon Mode
134

135
Optional server mode for improved performance across multiple operations.
136

137
```bash { .api }
138
rome start               # Start Rome daemon server process
139
rome stop                # Stop Rome daemon server process
140
rome lsp-proxy           # Language Server Protocol over stdin/stdout
141

142
# Use daemon for commands:
143
rome check src/ --use-server
144
```
145

146
[Daemon Mode](./daemon-mode.md)
147

148
### Utility Commands
149

150
Additional commands for version information and debugging support.
151

152
```bash { .api }
153
rome version              # Show Rome version information
154
rome rage                 # Print debugging information  
155
rome help [command]       # Print help message for commands
156
```
157

158
**Usage Examples:**
159

160
```bash
161
# Show version
162
rome version
163

164
# Get debugging information for issue reports
165
rome rage
166

167
# Get help for specific command
168
rome help format
169
```
170

171
## Global Options
172

173
```bash { .api }
174
# Available for all commands:
175
--colors <off|force>      # Set markup formatting mode
176
--use-server             # Connect to running daemon instance  
177
--version                # Show version information
178
--help                   # Show help information
179
--files-max-size <bytes>  # Maximum file size in bytes (default: 1MB)
180
--show-metrics           # Display performance metrics
181
```
182

183
## Supported File Types
184

185
- **JavaScript**: `.js`, `.jsx`, `.mjs`, `.cjs`
186
- **TypeScript**: `.ts`, `.tsx`, `.mts`, `.cts`, `.d.ts`  
187
- **JSON**: `.json`, `.jsonc`
188
- **CSS**: `.css` (parsing support)
189

190
## Error Handling
191

192
Rome provides detailed diagnostics with:
193

194
- **Precise error locations**: Line and column information
195
- **Contextual messages**: Clear explanations of issues
196
- **Fix suggestions**: Automatic fixes for many problems
197
- **Multiple output formats**: Human-readable and JSON formats
198
- **Graceful degradation**: Continues processing despite individual file errors