0
# @putout/eslint-flat
1

2
@putout/eslint-flat provides utilities for working with ESLint Flat Config format, offering a more convenient object-based syntax for ESLint configuration management. It simplifies ESLint configuration in monorepos and complex project structures by providing intuitive APIs that reduce boilerplate code and improve maintainability.
3

4
## Package Information
5

6
- **Package Name**: @putout/eslint-flat
7
- **Package Type**: npm
8
- **Language**: JavaScript (CommonJS)
9
- **Installation**: `npm install @putout/eslint-flat`
10

11
## Core Imports
12

13
```javascript
14
const { matchToFlat, matchToFlatDir, mergeESLintConfigs, createESLintConfig } = require('@putout/eslint-flat');
15
```
16

17
Individual imports:
18
```javascript
19
const { matchToFlat } = require('@putout/eslint-flat');
20
const { matchToFlatDir } = require('@putout/eslint-flat');
21
const { mergeESLintConfigs } = require('@putout/eslint-flat');
22
const { createESLintConfig } = require('@putout/eslint-flat');
23
```
24

25
## Basic Usage
26

27
```javascript
28
const { matchToFlat, matchToFlatDir } = require('@putout/eslint-flat');
29

30
// Convert object-based rules to flat config
31
const match = {
32
  'bin/cli.js': {
33
    'n/hashbang': 'off',
34
  },
35
  '**/*.spec.js': {
36
    'n/no-unsupported-features/node-builtins': 'off',
37
  },
38
};
39

40
const flatConfig = matchToFlat(match);
41
// Result: [
42
//   { files: ['bin/cli.js'], rules: { 'n/hashbang': 'off' } },
43
//   { files: ['**/*.spec.js'], rules: { 'n/no-unsupported-features/node-builtins': 'off' } }
44
// ]
45

46
// Use in monorepo structure
47
const packageConfig = await matchToFlatDir(__dirname, './packages/my-package');
48
```
49

50
## Architecture
51

52
@putout/eslint-flat is built around several key components:
53

54
- **Config Transformation**: Core utilities (`matchToFlat`, `matchToFlatDir`) that convert object-based configurations to ESLint flat config format
55
- **Monorepo Support**: Multi-directory configuration merging (`mergeESLintConfigs`) for complex project structures
56
- **Path Handling**: Smart file and directory path resolution supporting both regular paths and file:// URLs
57
- **Legacy Compatibility**: Automatic detection and conversion of .eslintrc.json files using ESLint's FlatCompat
58
- **Utility Functions**: Helper function (`createESLintConfig`) providing convenient access to ESLint's defineConfig
59

60
## Capabilities
61

62
### Configuration Transformation
63

64
Core functionality for converting object-based ESLint rules to flat config format. Transforms simple key-value rule objects into proper ESLint flat config arrays.
65

66
```javascript { .api }
67
function matchToFlat(config: Object): Array<Object>;
68
```
69

70
[Configuration Transformation](./transformation.md)
71

72
### Directory-based Configuration
73

74
Advanced configuration building for specific directories, supporting both file paths and file:// URLs. Handles config reading, path resolution, and pattern building for monorepo structures.
75

76
```javascript { .api }
77
async function matchToFlatDir(
78
  cwd: string | URL,
79
  path: string,
80
  config?: Object,
81
  overrides?: OverrideOptions
82
): Promise<Array<Object>>;
83
```
84

85
[Directory Configuration](./directory-config.md)
86

87
### Monorepo Configuration Management
88

89
Utilities for merging ESLint configurations across multiple directories in monorepos. Provides bulk configuration processing and flattening.
90

91
```javascript { .api }
92
async function mergeESLintConfigs(
93
  cwd: string | URL,
94
  directories: string | Array<string>,
95
  options?: OverrideOptions
96
): Promise<Array<Object>>;
97

98
function createESLintConfig(configs: Array<Object>): Array<Object>;
99
```
100

101
[Monorepo Management](./monorepo-config.md)
102

103
## Types
104

105
```javascript { .api }
106
// Configuration object for simple rule transformation
107
interface ConfigObject {
108
  [filePattern: string]: {
109
    [ruleName: string]: any;
110
  };
111
}
112

113
// ESLint flat config object structure
114
interface FlatConfigObject {
115
  files: Array<string>;
116
  rules: {
117
    [ruleName: string]: any;
118
  };
119
  ignores?: Array<string>;
120
}
121

122
// Override options for dependency injection
123
interface OverrideOptions {
124
  readdir?: (path: string) => Promise<Array<string>>;
125
}
126
```