0
# XO
1

2
XO is a zero-configuration JavaScript and TypeScript linter built as an opinionated ESLint wrapper that enforces strict and readable code standards. It provides beautiful output, automatic file discovery, TypeScript support by default, and includes many useful ESLint plugins like unicorn, import, ava, and n. XO is designed for maximum developer productivity by eliminating configuration decisions while maintaining flexibility through flat config customization when needed.
3

4
## Package Information
5

6
- **Package Name**: xo
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install xo`
10
- **Node.js Version**: >=20.17
11

12
## Core Imports
13

14
```typescript
15
import Xo, { 
16
  allFilesGlob, 
17
  jsFilesGlob, 
18
  tsFilesGlob, 
19
  type FlatXoConfig, 
20
  type XoConfigItem 
21
} from "xo";
22
```
23

24
For CommonJS:
25

26
```javascript
27
const Xo = require("xo").default;
28
const { allFilesGlob, jsFilesGlob, tsFilesGlob } = require("xo");
29
```
30

31
## Basic Usage
32

33
### CLI Usage
34

35
```bash
36
# Lint all supported files in current directory
37
xo
38

39
# Lint specific files
40
xo index.js src/*.ts
41

42
# Auto-fix issues
43
xo --fix
44

45
# Use spaces instead of tabs
46
xo --space
47

48
# Enable React support
49
xo --react
50
```
51

52
### Programmatic Usage
53

54
```typescript
55
import Xo from "xo";
56

57
// Create XO instance
58
const xo = new Xo(
59
  { cwd: process.cwd(), fix: false },
60
  { space: true, semicolon: true }
61
);
62

63
// Lint files
64
const result = await xo.lintFiles("src/**/*.{js,ts}");
65
console.log(`Found ${result.errorCount} errors, ${result.warningCount} warnings`);
66

67
// Lint text
68
const textResult = await xo.lintText("console.log('hello')", { filePath: "test.js" });
69
```
70

71
## Architecture
72

73
XO is built around several key components:
74

75
- **Xo Class**: Main linting engine that wraps ESLint with opinionated defaults
76
- **Configuration System**: Flat config support with XO-specific options layered on top
77
- **CLI Interface**: Command-line tool with comprehensive options for development workflows
78
- **Type System**: Full TypeScript integration with comprehensive type definitions
79
- **Plugin Integration**: Pre-configured ESLint plugins for comprehensive code quality rules
80
- **Cache Management**: Built-in caching system for improved performance on large codebases
81

82
## Capabilities
83

84
### Programmatic Linting
85

86
The core XO class provides comprehensive linting functionality for JavaScript and TypeScript files, with support for both file-based and text-based linting operations.
87

88
```typescript { .api }
89
class Xo {
90
  constructor(linterOptions: LinterOptions, baseXoConfig?: XoConfigOptions);
91
  lintFiles(globs?: string | string[]): Promise<XoLintResult>;
92
  lintText(code: string, options: LintTextOptions): Promise<XoLintResult>;
93
  calculateConfigForFile(filePath: string): Promise<Linter.Config>;
94
  getFormatter(name: string): Promise<ESLint.Formatter>;
95
  initEslint(files?: string[]): Promise<void>;
96
}
97

98
// Static methods for convenience
99
static lintText(code: string, options: LintTextOptions & LinterOptions & XoConfigOptions): Promise<XoLintResult>;
100
static lintFiles(globs: string | undefined, options: LinterOptions & XoConfigOptions): Promise<XoLintResult>;
101
static outputFixes(results: XoLintResult): Promise<void>;
102
static xoToEslintConfig(flatXoConfig: XoConfigItem[], options?: CreateConfigOptions): Linter.Config[];
103
```
104

105
[Programmatic API](./programmatic-api.md)
106

107
### CLI Tool
108

109
Command-line interface providing comprehensive linting capabilities with auto-fixing, reporter options, configuration overrides, and editor integration.
110

111
```typescript { .api }
112
// CLI flags and their types
113
interface CliFlags {
114
  fix: boolean;          // Auto-fix issues
115
  reporter?: string;     // Custom reporter
116
  space?: string;        // Space indentation config
117
  semicolon: boolean;    // Semicolon enforcement
118
  prettier: boolean;     // Prettier integration
119
  react: boolean;        // React-specific rules
120
  quiet: boolean;        // Show only errors
121
  stdin: boolean;        // Read from stdin
122
  open: boolean;         // Open files in editor
123
  ignores: string[];     // Ignore patterns
124
  cwd: string;          // Working directory
125
}
126
```
127

128
[CLI Interface](./cli-interface.md)
129

130
### Configuration
131

132
XO configuration system supporting flat config files, CLI options, and programmatic configuration with TypeScript support.
133

134
```typescript { .api }
135
interface XoConfigOptions {
136
  space?: boolean | number | string;
137
  semicolon?: boolean;
138
  prettier?: boolean | 'compat';
139
  react?: boolean;
140
  ignores?: string | string[];
141
}
142

143
interface XoConfigItem extends XoConfigOptions {
144
  files?: string | string[];
145
  ignores?: string | string[];
146
  // ... extends Linter.Config
147
}
148

149
type FlatXoConfig = XoConfigItem | XoConfigItem[];
150
```
151

152
[Configuration](./configuration.md)
153

154
## File Pattern Constants
155

156
```typescript { .api }
157
// Exported glob patterns for file matching
158
const jsFilesGlob = "**/*.{js,jsx,mjs,cjs}";
159
const tsFilesGlob = "**/*.{ts,tsx,cts,mts}";
160
const allFilesGlob = "**/*.{js,jsx,mjs,cjs,ts,tsx,cts,mts}";
161
```
162

163
## Lint Result Type
164

165
```typescript { .api }
166
interface XoLintResult {
167
  errorCount: number;
168
  warningCount: number;
169
  fixableErrorCount: number;
170
  fixableWarningCount: number;
171
  results: ESLint.LintResult[];
172
  rulesMeta: Record<string, Rule.RuleMetaData>;
173
}
174

175
interface CreateConfigOptions {
176
  prettierOptions?: Options;
177
}
178

179
// Utility types
180
type Space = boolean | number | string | undefined;
181
```