0
# Biome Checker
1

2
Biome integration for fast JavaScript, TypeScript, and JSON linting, formatting, and type checking with support for multiple command modes and development/build configurations.
3

4
## Capabilities
5

6
### Biome Configuration
7

8
Enable and configure Biome for comprehensive code quality checking with flexible command options.
9

10
```typescript { .api }
11
/**
12
 * Biome checker configuration
13
 * - Set to `true` to enable Biome with default lint command
14
 * - Set to `false` to disable Biome checking
15
 * - Provide configuration object for custom setup
16
 */
17
type BiomeConfig = boolean | BiomeConfigObject;
18

19
interface BiomeConfigObject {
20
  /**
21
   * Command type used in both dev and build mode
22
   * Will be overridden by dev.command or build.command if specified
23
   */
24
  command?: BiomeCommand;
25
  
26
  /**
27
   * Command flags used in both dev and build mode
28
   * Will be overridden by dev.flags or build.flags if specified
29
   */
30
  flags?: string;
31
  
32
  /** Development-specific configuration */
33
  dev?: Partial<BiomeDevConfig>;
34
  
35
  /** Build-specific configuration */
36
  build?: Partial<BiomeBuildConfig>;
37
}
38

39
type BiomeCommand = 'lint' | 'check' | 'format' | 'ci';
40

41
interface BiomeDevConfig {
42
  /** Command to use in development mode */
43
  command: BiomeCommand;
44
  
45
  /** Command flags for development mode */
46
  flags?: string;
47
  
48
  /** Which diagnostic levels to emit from the plugin */
49
  logLevel: ('error' | 'warning' | 'info')[];
50
}
51

52
interface BiomeBuildConfig {
53
  /** Command to use in build mode */
54
  command: BiomeCommand;
55
  
56
  /** Command flags for build mode */
57
  flags?: string;
58
}
59
```
60

61
**Usage Examples:**
62

63
```typescript
64
// Simple enable with default lint command
65
checker({
66
  biome: true,
67
});
68

69
// Custom command configuration
70
checker({
71
  biome: {
72
    command: 'check', // Use 'check' for both lint and format
73
    flags: '--apply',
74
  },
75
});
76

77
// Separate dev and build configurations
78
checker({
79
  biome: {
80
    dev: {
81
      command: 'lint',
82
      flags: '--apply-unsafe',
83
      logLevel: ['error', 'warning'],
84
    },
85
    build: {
86
      command: 'ci',
87
      flags: '--max-diagnostics=50',
88
    },
89
  },
90
});
91
```
92

93
### Biome Commands
94

95
Biome supports different command modes for various use cases:
96

97
```typescript { .api }
98
type BiomeCommand = 'lint' | 'check' | 'format' | 'ci';
99
```
100

101
**Command Descriptions:**
102

103
- **`lint`**: Run linting rules only, checking for code quality issues
104
- **`check`**: Run both linting and formatting checks (comprehensive analysis)
105
- **`format`**: Format code according to Biome's formatting rules
106
- **`ci`**: Optimized command for CI/CD environments with performance optimizations
107

108
### Default Configuration
109

110
When `biome: true` is used, the following default configuration is applied:
111

112
```typescript
113
{
114
  command: 'lint',      // Run linting by default
115
  flags: '',           // No additional flags
116
  dev: {
117
    command: 'lint',
118
    logLevel: ['error', 'warning', 'info'],
119
  },
120
  build: {
121
    command: 'lint',
122
  },
123
}
124
```
125

126
### Development Mode Configuration
127

128
Override Biome behavior specifically for development mode with custom commands and log levels.
129

130
```typescript { .api }
131
interface BiomeDevConfig {
132
  /**
133
   * Command to use in development mode
134
   * Overrides global command setting
135
   */
136
  command: BiomeCommand;
137
  
138
  /**
139
   * Command flags for development mode
140
   * Overrides global flags setting
141
   */
142
  flags?: string;
143
  
144
  /**
145
   * Control which diagnostic levels are emitted from the plugin
146
   * @default ['error', 'warning', 'info']
147
   */
148
  logLevel: ('error' | 'warning' | 'info')[];
149
}
150
```
151

152
**Development Configuration Examples:**
153

154
```typescript
155
// Auto-fix issues in development
156
biome: {
157
  dev: {
158
    command: 'check',
159
    flags: '--apply',
160
    logLevel: ['error', 'warning'],
161
  },
162
}
163

164
// Lint only with unsafe fixes in development
165
biome: {
166
  dev: {
167
    command: 'lint',
168
    flags: '--apply-unsafe',
169
    logLevel: ['error'],
170
  },
171
}
172

173
// Format and lint in development
174
biome: {
175
  dev: {
176
    command: 'check',
177
    flags: '--apply --verbose',
178
    logLevel: ['error', 'warning', 'info'],
179
  },
180
}
181
```
182

183
### Build Mode Configuration
184

185
Configure Biome behavior specifically for build/production mode.
186

187
```typescript { .api }
188
interface BiomeBuildConfig {
189
  /**
190
   * Command to use in build mode
191
   * Overrides global command setting
192
   */
193
  command: BiomeCommand;
194
  
195
  /**
196
   * Command flags for build mode
197
   * Overrides global flags setting
198
   */
199
  flags?: string;
200
}
201
```
202

203
**Build Configuration Examples:**
204

205
```typescript
206
// Strict checking in build mode
207
biome: {
208
  build: {
209
    command: 'ci',
210
    flags: '--max-diagnostics=100',
211
  },
212
}
213

214
// Comprehensive checking in build
215
biome: {
216
  build: {
217
    command: 'check',
218
    flags: '--verbose --no-errors-on-unmatched',
219
  },
220
}
221

222
// Format checking only in build
223
biome: {
224
  build: {
225
    command: 'format',
226
    flags: '--check',
227
  },
228
}
229
```
230

231
### Command Flags
232

233
Common Biome command flags that can be used with different commands:
234

235
**General Flags:**
236
- `--apply`: Apply safe fixes automatically
237
- `--apply-unsafe`: Apply safe and unsafe fixes automatically
238
- `--verbose`: Enable verbose output
239
- `--no-errors-on-unmatched`: Don't error when no files match the pattern
240
- `--max-diagnostics=N`: Limit the number of diagnostics shown
241

242
**Lint-specific Flags:**
243
- `--fix`: Same as `--apply` for backwards compatibility
244
- `--unsafe`: Same as `--apply-unsafe` for backwards compatibility
245

246
**Format-specific Flags:**
247
- `--check`: Check if files are formatted correctly without applying changes
248
- `--write`: Write formatted files (default behavior)
249

250
**CI-specific Flags:**
251
- `--formatter=FORMAT`: Set output formatter (json, github, junit)
252
- `--changed`: Only check changed files (requires git)
253

254
### Configuration File Integration
255

256
Biome respects configuration in `biome.json` or `biome.jsonc`:
257

258
```json
259
{
260
  "linter": {
261
    "enabled": true,
262
    "rules": {
263
      "recommended": true,
264
      "suspicious": {
265
        "noExplicitAny": "error"
266
      }
267
    }
268
  },
269
  "formatter": {
270
    "enabled": true,
271
    "indentStyle": "space",
272
    "indentWidth": 2
273
  },
274
  "files": {
275
    "include": ["src/**/*.ts", "src/**/*.tsx"],
276
    "ignore": ["**/*.d.ts"]
277
  }
278
}
279
```
280

281
The checker will use these configuration settings when running Biome commands.
282

283
### Language Support
284

285
Biome supports multiple file types:
286

287
**JavaScript/TypeScript:**
288
```typescript
289
biome: {
290
  command: 'check',
291
  flags: '--apply',
292
}
293
```
294

295
**JSON Files:**
296
```typescript
297
biome: {
298
  command: 'format',
299
  flags: '--write',
300
}
301
```
302

303
**JSX/TSX:**
304
```typescript  
305
biome: {
306
  dev: {
307
    command: 'check',
308
    flags: '--apply',
309
    logLevel: ['error', 'warning'],
310
  },
311
}
312
```
313

314
### Error Reporting
315

316
Biome errors and warnings are reported with comprehensive information:
317

318
- **Rule name**: The specific Biome rule that was violated
319
- **Severity**: Error, warning, or info level
320
- **File location**: Exact file path and line/column numbers
321
- **Message**: Detailed description of the issue
322
- **Code frame**: Highlighted code snippet showing the problematic code
323
- **Fix suggestion**: Automatic fix information when available
324
- **Performance metrics**: Timing information for CI/CD optimization
325

326
### Integration Examples
327

328
**React TypeScript Project:**
329
```typescript
330
checker({
331
  biome: {
332
    command: 'check',
333
    dev: {
334
      command: 'check',
335
      flags: '--apply',
336
      logLevel: ['error', 'warning'],
337
    },
338
    build: {
339
      command: 'ci',
340
      flags: '--formatter=github',
341
    },
342
  },
343
});
344
```
345

346
**Node.js Backend:**
347
```typescript
348
checker({
349
  biome: {
350
    dev: {
351
      command: 'lint',
352
      flags: '--apply-unsafe',
353
      logLevel: ['error'],
354
    },
355
    build: {
356
      command: 'check',
357
      flags: '--max-diagnostics=50',
358
    },
359
  },
360
});
361
```
362

363
**Monorepo Setup:**
364
```typescript
365
checker({
366
  biome: {
367
    command: 'check',
368
    flags: '--no-errors-on-unmatched',
369
    dev: {
370
      command: 'lint',
371
      flags: '--apply --verbose',
372
      logLevel: ['error', 'warning'],
373
    },
374
    build: {
375
      command: 'ci',
376
      flags: '--formatter=json --changed',
377
    },
378
  },
379
});
380
```
381

382
### Performance Benefits
383

384
Biome offers significant performance advantages:
385

386
- **Fast startup**: Near-instantaneous startup time compared to ESLint
387
- **Parallel processing**: Multi-threaded processing for large codebases
388
- **Incremental checking**: Only checks changed files when possible
389
- **Memory efficiency**: Lower memory usage than traditional Node.js tools
390
- **Native performance**: Built with Rust for optimal performance
391

392
### Migration from ESLint/Prettier
393

394
When migrating from ESLint and Prettier:
395

396
```typescript
397
// Before: ESLint + Prettier
398
checker({
399
  eslint: {
400
    lintCommand: 'eslint "src/**/*.{ts,tsx}"',
401
  },
402
  // + separate prettier configuration
403
});
404

405
// After: Biome (replaces both)
406
checker({
407
  biome: {
408
    command: 'check',
409
    flags: '--apply',
410
  },
411
});
412
```
413

414
### Troubleshooting
415

416
**Biome not found:**
417
```bash
418
npm install --save-dev @biomejs/biome
419
```
420

421
**Configuration not found:**
422
Create a `biome.json` file in your project root:
423
```json
424
{
425
  "linter": { "enabled": true },
426
  "formatter": { "enabled": true }
427
}
428
```
429

430
**Performance issues:**
431
Use the `ci` command for build environments:
432
```typescript
433
biome: {
434
  build: {
435
    command: 'ci',
436
    flags: '--max-diagnostics=25',
437
  },
438
}
439
```