0
# Monorepo Configuration Management
1

2
Utilities for merging ESLint configurations across multiple directories in monorepos, providing bulk configuration processing and convenient helper functions.
3

4
## Capabilities
5

6
### mergeESLintConfigs Function
7

8
Merges ESLint configurations from multiple directories in a monorepo structure. Reads all subdirectories within specified directories and combines their configurations into a single flat config array.
9

10
```javascript { .api }
11
/**
12
 * Merges ESLint configurations from multiple directories
13
 * @param {string|URL} cwd - Current working directory or file URL
14
 * @param {string|Array<string>} directories - Directory name(s) to read configs from
15
 * @param {Object} [options] - Optional override functions { readdir, readESLintConfig }
16
 * @returns {Promise<Array<Object>>} Promise resolving to flattened array of merged ESLint config objects
17
 */
18
async function mergeESLintConfigs(cwd, directories, options);
19
```
20

21
**Parameters:**
22
- `cwd` (string|URL): Current working directory or file:// URL
23
- `directories` (string|Array): Single directory name or array of directory names to process
24
- `options` (Object, optional): Override functions for dependency injection
25
  - `readdir` (function): Custom directory reading function
26

27
**Returns:**
28
Promise resolving to a flattened array of all merged ESLint configuration objects.
29

30
**Usage Examples:**
31

32
**Single Directory Processing:**
33
```javascript
34
const { mergeESLintConfigs } = require('@putout/eslint-flat');
35

36
// Process all packages in ./packages directory
37
const config = await mergeESLintConfigs(__dirname, 'packages');
38

39
// This will:
40
// 1. Read all subdirectories in ./packages
41
// 2. Read ESLint config from each subdirectory
42
// 3. Use matchToFlatDir for each subdirectory
43
// 4. Flatten all configs into single array
44
```
45

46
**Multiple Directory Processing:**
47
```javascript
48
const { mergeESLintConfigs } = require('@putout/eslint-flat');
49

50
// Process multiple directory types
51
const config = await mergeESLintConfigs(__dirname, ['packages', 'tools', 'scripts']);
52
```
53

54
**With File URL (ESM):**
55
```javascript
56
import { mergeESLintConfigs } from '@putout/eslint-flat';
57

58
const config = await mergeESLintConfigs(import.meta.url, ['packages']);
59
```
60

61
**Complete Monorepo ESLint Configuration:**
62
```javascript
63
import { safeAlign } from 'eslint-plugin-putout/config';
64
import { mergeESLintConfigs } from '@putout/eslint-flat';
65

66
const packageConfigs = await mergeESLintConfigs(import.meta.url, ['packages']);
67

68
export default [
69
  ...safeAlign,
70
  ...packageConfigs,
71
];
72
```
73

74
**With Custom Options:**
75
```javascript
76
const { mergeESLintConfigs } = require('@putout/eslint-flat');
77
const fs = require('fs/promises');
78

79
// Custom directory reading for filtered processing
80
const customReaddir = async (path) => {
81
  const items = await fs.readdir(path);
82
  // Only process directories starting with 'pkg-'
83
  return items.filter(item => item.startsWith('pkg-'));
84
};
85

86
const config = await mergeESLintConfigs(__dirname, 'packages', {
87
  readdir: customReaddir,
88
});
89
```
90

91
### createESLintConfig Function
92

93
Convenience function that serves as an alias to ESLint's defineConfig function, providing a cleaner API for creating ESLint configurations.
94

95
```javascript { .api }
96
/**
97
 * Alias to ESLint's defineConfig function for creating configurations
98
 * @param {Array<Object>} configs - Array of ESLint configuration objects
99
 * @returns {Array<Object>} Processed configuration array from ESLint's defineConfig
100
 */
101
function createESLintConfig(configs);
102
```
103

104
**Parameters:**
105
- `configs` (Array<Object>): Array of ESLint configuration objects to be processed
106

107
**Returns:**
108
Array of ESLint configuration objects processed by ESLint's defineConfig function.
109

110
**Usage Examples:**
111

112
**Simple Configuration Creation:**
113
```javascript
114
const { createESLintConfig } = require('@putout/eslint-flat');
115
const { safeAlign } = require('eslint-plugin-putout/config');
116

117
// Instead of spreading arrays manually
118
export default createESLintConfig([
119
  ...safeAlign,
120
  {
121
    files: ['**/*.js'],
122
    rules: {
123
      'no-console': 'warn',
124
    },
125
  },
126
]);
127
```
128

129
**Compared to Manual Spreading:**
130
```javascript
131
// Without createESLintConfig (more verbose)
132
export default [
133
  ...safeAlign,
134
  ...otherConfigs,
135
  customConfig,
136
];
137

138
// With createESLintConfig (cleaner)
139
export default createESLintConfig([safeAlign, otherConfigs, customConfig]);
140
```
141

142
## Monorepo Processing Flow
143

144
The `mergeESLintConfigs` function follows this processing flow:
145

146
1. **Directory Resolution**: Converts cwd to proper directory path (handles file:// URLs)
147
2. **Directory Reading**: Reads all items in each specified directory
148
3. **Subdirectory Processing**: For each subdirectory found:
149
   - Reads ESLint configuration using internal `readESLintConfig`
150
   - Applies `matchToFlatDir` to process and prefix file patterns
151
4. **Flattening**: Combines all configuration arrays into single flat array
152

153
## Directory Structure Example
154

155
```
156
my-monorepo/
157
├── packages/
158
│   ├── package-a/
159
│   │   └── eslint.config.js
160
│   ├── package-b/
161
│   │   └── eslint.config.js
162
│   └── package-c/
163
│       └── .eslintrc.json
164
└── tools/
165
    ├── build-tool/
166
    │   └── eslint.config.js
167
    └── dev-tool/
168
        └── eslint.config.js
169
```
170

171
**Configuration:**
172
```javascript
173
const config = await mergeESLintConfigs(__dirname, ['packages', 'tools']);
174
// Processes: package-a, package-b, package-c, build-tool, dev-tool
175
// Returns: Single flattened array with all configurations
176
```
177

178
## Error Handling
179

180
- Gracefully handles missing directories (skips them)
181
- Uses try-catch internally for file operations
182
- Empty configurations return empty arrays rather than errors
183
- Supports dependency injection for testing and custom behavior
184

185
## Performance Considerations
186

187
- Processes directories in parallel using `Promise.all`
188
- Reads configurations asynchronously
189
- Flattens results efficiently using `Array.flat()`
190
- Suitable for large monorepos with many packages