0
# Programmatic API
1

2
The XO programmatic API provides comprehensive linting functionality for JavaScript and TypeScript files through the main `Xo` class and convenient static methods.
3

4
## Capabilities
5

6
### Xo Class Constructor
7

8
Creates a new XO linting instance with specified options.
9

10
```typescript { .api }
11
/**
12
 * Creates a new XO linting instance
13
 * @param linterOptions - Required linter configuration
14
 * @param baseXoConfig - Optional XO-specific configuration
15
 */
16
constructor(linterOptions: LinterOptions, baseXoConfig?: XoConfigOptions);
17

18
interface LinterOptions {
19
  /** Current working directory for relative paths */
20
  cwd: string;
21
  /** Write fixes to files automatically */
22
  fix?: boolean;
23
  /** Path to file being linted (for lintText) */
24
  filePath?: string;
25
  /** Show only errors, not warnings */
26
  quiet?: boolean;
27
  /** Auto-configure type-aware linting for TypeScript */
28
  ts?: boolean;
29
  /** Custom path to config file */
30
  configPath?: string;
31
}
32

33
interface XoConfigOptions {
34
  /** Use spaces for indentation (boolean, number, or string) */
35
  space?: boolean | number | string;
36
  /** Use semicolons at end of statements */
37
  semicolon?: boolean;
38
  /** Use Prettier formatting ('compat' for compatibility mode) */
39
  prettier?: boolean | 'compat';
40
  /** Enable React-specific linting rules */
41
  react?: boolean;
42
  /** Files to ignore (glob patterns) */
43
  ignores?: string | string[];
44
}
45
```
46

47
**Usage Example:**
48

49
```typescript
50
import Xo from "xo";
51

52
const xo = new Xo(
53
  {
54
    cwd: process.cwd(),
55
    fix: true,
56
    quiet: false
57
  },
58
  {
59
    space: 2,
60
    semicolon: true,
61
    react: true
62
  }
63
);
64
```
65

66
### Lint Files
67

68
Lints files matching the provided glob patterns.
69

70
```typescript { .api }
71
/**
72
 * Lints files matching glob patterns
73
 * @param globs - Glob patterns for files to lint (defaults to all supported files)
74
 * @returns Promise resolving to lint results
75
 */
76
async lintFiles(globs?: string | string[]): Promise<XoLintResult>;
77
```
78

79
**Usage Example:**
80

81
```typescript
82
// Lint all supported files
83
const result = await xo.lintFiles();
84

85
// Lint specific patterns
86
const jsResult = await xo.lintFiles(["src/**/*.js", "test/**/*.ts"]);
87

88
// Check results
89
if (result.errorCount > 0) {
90
  console.error(`Found ${result.errorCount} errors`);
91
  // Access detailed results
92
  result.results.forEach(fileResult => {
93
    console.log(`${fileResult.filePath}: ${fileResult.messages.length} issues`);
94
  });
95
}
96
```
97

98
### Lint Text
99

100
Lints provided text content with specified file path context.
101

102
```typescript { .api }
103
/**
104
 * Lints provided text content
105
 * @param code - Source code text to lint
106
 * @param options - Linting options including file path
107
 * @returns Promise resolving to lint results
108
 */
109
async lintText(code: string, options: LintTextOptions): Promise<XoLintResult>;
110

111
interface LintTextOptions {
112
  /** Path to file being linted (used for rule context) */
113
  filePath: string;
114
  /** Warn if the file would be ignored */
115
  warnIgnored?: boolean;
116
}
117
```
118

119
**Usage Example:**
120

121
```typescript
122
const code = `
123
function hello() {
124
    console.log("Hello world")
125
}
126
`;
127

128
const result = await xo.lintText(code, { 
129
  filePath: "example.js",
130
  warnIgnored: false 
131
});
132

133
console.log(`Errors: ${result.errorCount}, Warnings: ${result.warningCount}`);
134
```
135

136
### Calculate Config for File
137

138
Gets the effective ESLint configuration for a specific file.
139

140
```typescript { .api }
141
/**
142
 * Calculates the effective ESLint configuration for a file
143
 * @param filePath - Path to the file to get config for
144
 * @returns Promise resolving to ESLint configuration
145
 */
146
async calculateConfigForFile(filePath: string): Promise<Linter.Config>;
147
```
148

149
**Usage Example:**
150

151
```typescript
152
const config = await xo.calculateConfigForFile("src/index.ts");
153
console.log("Active rules:", Object.keys(config.rules || {}));
154
```
155

156
### Get Formatter
157

158
Loads an ESLint formatter by name for custom output formatting.
159

160
```typescript { .api }
161
/**
162
 * Loads an ESLint formatter for custom output
163
 * @param name - Name of the formatter to load
164
 * @returns Promise resolving to formatter instance
165
 */
166
async getFormatter(name: string): Promise<ESLint.Formatter>;
167
```
168

169
**Usage Example:**
170

171
```typescript
172
const formatter = await xo.getFormatter("json");
173
const result = await xo.lintFiles();
174
const formattedOutput = formatter.format(result.results);
175
console.log(formattedOutput);
176
```
177

178
### Initialize ESLint
179

180
Initializes the internal ESLint instance with current configuration.
181

182
```typescript { .api }
183
/**
184
 * Initializes the ESLint instance (called automatically by lint methods)
185
 * @param files - Optional list of files for TypeScript configuration
186
 */
187
async initEslint(files?: string[]): Promise<void>;
188
```
189

190
### XO to ESLint Config Conversion
191

192
Converts XO configuration to ESLint flat config format for direct ESLint usage.
193

194
```typescript { .api }
195
/**
196
 * Static helper to convert XO config to ESLint config for use in eslint.config.js
197
 * @param flatXoConfig - Array of XO configuration items
198
 * @param options - Additional options including Prettier configuration
199
 * @returns ESLint flat configuration array
200
 */
201
static xoToEslintConfig(
202
  flatXoConfig: XoConfigItem[], 
203
  options?: CreateConfigOptions
204
): Linter.Config[];
205

206
interface CreateConfigOptions {
207
  /** Prettier options to merge with XO's defaults */
208
  prettierOptions?: Options;
209
}
210
```
211

212
**Usage Example:**
213

214
```typescript
215
import { xoToEslintConfig } from "xo";
216

217
// Convert XO config to ESLint config
218
const eslintConfig = xoToEslintConfig([
219
  { space: 2, semicolon: true, react: true }
220
], {
221
  prettierOptions: { semi: true, tabWidth: 2 }
222
});
223

224
// Use in eslint.config.js
225
export default eslintConfig;
226
```
227

228
## Static Methods
229

230
### Static Lint Text
231

232
Convenience method for linting text without creating an XO instance.
233

234
```typescript { .api }
235
/**
236
 * Static convenience method for linting text
237
 * @param code - Source code to lint
238
 * @param options - Combined linter, XO config, and text options
239
 * @returns Promise resolving to lint results
240
 */
241
static async lintText(
242
  code: string, 
243
  options: LintTextOptions & LinterOptions & XoConfigOptions
244
): Promise<XoLintResult>;
245
```
246

247
**Usage Example:**
248

249
```typescript
250
const result = await Xo.lintText(`console.log("test")`, {
251
  filePath: "test.js",
252
  cwd: process.cwd(),
253
  space: true,
254
  semicolon: false
255
});
256
```
257

258
### Static Lint Files
259

260
Convenience method for linting files without creating an XO instance.
261

262
```typescript { .api }
263
/**
264
 * Static convenience method for linting files
265
 * @param globs - Glob patterns for files to lint
266
 * @param options - Combined linter and XO config options
267
 * @returns Promise resolving to lint results
268
 */
269
static async lintFiles(
270
  globs: string | undefined, 
271
  options: LinterOptions & XoConfigOptions
272
): Promise<XoLintResult>;
273
```
274

275
**Usage Example:**
276

277
```typescript
278
const result = await Xo.lintFiles("src/**/*.js", {
279
  cwd: process.cwd(),
280
  fix: true,
281
  space: 2,
282
  react: true
283
});
284
```
285

286
### Static Output Fixes
287

288
Writes auto-fixes from lint results to disk.
289

290
```typescript { .api }
291
/**
292
 * Writes auto-fixes to disk
293
 * @param results - Lint results containing fixes
294
 */
295
static async outputFixes(results: XoLintResult): Promise<void>;
296
```
297

298
**Usage Example:**
299

300
```typescript
301
const result = await xo.lintFiles();
302
if (result.fixableErrorCount > 0 || result.fixableWarningCount > 0) {
303
  await Xo.outputFixes(result);
304
  console.log("Auto-fixes applied");
305
}
306
```
307

308
## Result Types
309

310
```typescript { .api }
311
interface XoLintResult {
312
  /** Total number of errors found */
313
  errorCount: number;
314
  /** Total number of warnings found */
315
  warningCount: number;
316
  /** Number of fixable errors */
317
  fixableErrorCount: number;
318
  /** Number of fixable warnings */
319
  fixableWarningCount: number;
320
  /** Array of ESLint results for each file */
321
  results: ESLint.LintResult[];
322
  /** Metadata about the rules that were executed */
323
  rulesMeta: Record<string, Rule.RuleMetaData>;
324
}
325
```
326

327
## Instance Properties
328

329
The XO class exposes several properties for advanced usage:
330

331
```typescript { .api }
332
interface XoInstance {
333
  /** Configuration options passed to constructor */
334
  linterOptions: LinterOptions;
335
  baseXoConfig: XoConfigOptions;
336
  
337
  /** Path to ESLint cache directory */
338
  cacheLocation: string;
339
  
340
  /** Internal ESLint instance (available after initEslint) */
341
  eslint?: ESLint;
342
  
343
  /** Resolved XO configuration */
344
  xoConfig?: XoConfigItem[];
345
  
346
  /** Generated ESLint configuration */
347
  eslintConfig?: Linter.Config[];
348
  
349
  /** Path to flat config file if found */
350
  flatConfigPath?: string;
351
  
352
  /** Whether Prettier integration is enabled */
353
  prettier?: boolean;
354
  
355
  /** Resolved Prettier configuration */
356
  prettierConfig?: prettier.Options;
357
  
358
  /** Glob patterns for TypeScript files */
359
  tsFilesGlob: string[];
360
  
361
  /** Negative glob patterns for TypeScript overrides */
362
  tsFilesIgnoresGlob: string[];
363
}
364
```