0
# Flat Config Utilities
1

2
Utilities for working with ESLint flat configurations and type-safe configuration composition.
3

4
## Capabilities
5

6
### Define Flat Configs
7

8
Provides type definitions for constructing ESLint flat config items with promise resolution and type safety.
9

10
```typescript { .api }
11
/**
12
 * Provide type definitions for constructing ESLint flat config items.
13
 * This function takes flat config item, or an array of them as rest arguments.
14
 * It also automatically resolves the promise if the config item is a promise.
15
 * 
16
 * @param configs - Flat config items or promises of config items
17
 * @returns FlatConfigComposer for chaining and composition
18
 */
19
function defineFlatConfigs(...configs: ResolvableFlatConfig[]): FlatConfigComposer;
20

21
type ResolvableFlatConfig = Linter.Config | Promise<Linter.Config>;
22
```
23

24
**Usage Examples:**
25

26
```typescript
27
import { defineFlatConfigs } from "@nuxt/eslint-config";
28
import js from "@eslint/js";
29

30
// Define multiple flat configs
31
export default defineFlatConfigs(
32
  // Basic recommended rules
33
  js.configs.recommended,
34
  
35
  // Custom rules
36
  {
37
    rules: {
38
      "no-unused-vars": "warn",
39
      "prefer-const": "error"
40
    }
41
  },
42
  
43
  // Async config (will be resolved automatically)
44
  import("./custom-config.js"),
45
  
46
  // Conditional config
47
  process.env.NODE_ENV === "development" ? {
48
    rules: {
49
      "no-console": "off"
50
    }
51
  } : undefined
52
);
53

54
// Chaining with other configs
55
export default defineFlatConfigs(
56
  js.configs.recommended
57
).append({
58
  files: ["**/*.ts"],
59
  rules: {
60
    "@typescript-eslint/no-explicit-any": "warn"
61
  }
62
});
63
```
64

65
### Flat Config Composer
66

67
The `FlatConfigComposer` provides a fluent interface for building and composing ESLint configurations.
68

69
```typescript { .api }
70
interface FlatConfigComposer {
71
  /**
72
   * Append additional configurations to the composer
73
   */
74
  append(...configs: ResolvableFlatConfig[]): FlatConfigComposer;
75
  
76
  /**
77
   * Set plugin conflicts error handling
78
   */
79
  setPluginConflictsError(pluginName?: string, message?: string): FlatConfigComposer;
80
}
81
```
82

83
**Usage Examples:**
84

85
```typescript
86
import { defineFlatConfigs } from "@nuxt/eslint-config";
87

88
// Building configurations step by step
89
const config = defineFlatConfigs()
90
  .append({
91
    name: "base-rules",
92
    rules: {
93
      "no-unused-vars": "warn"
94
    }
95
  })
96
  .append({
97
    name: "typescript-rules",
98
    files: ["**/*.ts", "**/*.tsx"],
99
    rules: {
100
      "@typescript-eslint/explicit-function-return-type": "error"
101
    }
102
  })
103
  .setPluginConflictsError("import", "Different import plugin instances detected");
104

105
export default config;
106
```
107

108
### Resolvable Flat Config Type
109

110
Type definition for configurations that can be synchronous or asynchronous.
111

112
```typescript { .api }
113
/**
114
 * A flat config that can be a direct config object or a promise that resolves to one
115
 */
116
type ResolvableFlatConfig = Linter.Config | Promise<Linter.Config>;
117

118
/**
119
 * ESLint Linter.Config for reference
120
 */
121
interface Linter.Config {
122
  name?: string;
123
  files?: string | string[];
124
  ignores?: string[];
125
  languageOptions?: LanguageOptions;
126
  linterOptions?: LinterOptions;
127
  processor?: string | Processor;
128
  plugins?: Record<string, Plugin>;
129
  rules?: Record<string, RuleLevel | RuleLevelAndOptions>;
130
  settings?: Record<string, any>;
131
}
132
```
133

134
**Usage Examples:**
135

136
```typescript
137
import { defineFlatConfigs } from "@nuxt/eslint-config";
138

139
// Mix of sync and async configs
140
export default defineFlatConfigs(
141
  // Synchronous config
142
  {
143
    name: "sync-config",
144
    rules: {
145
      "no-console": "warn"
146
    }
147
  },
148
  
149
  // Asynchronous config - will be resolved automatically
150
  import("./async-config.js").then(module => ({
151
    name: "async-config",
152
    ...module.default
153
  })),
154
  
155
  // Conditional async config
156
  process.env.ENABLE_TYPESCRIPT ? 
157
    import("@typescript-eslint/eslint-plugin").then(plugin => ({
158
      name: "typescript",
159
      plugins: {
160
        "@typescript-eslint": plugin
161
      }
162
    })) : 
163
    undefined
164
);
165
```
166

167
### Integration with External Tools
168

169
Working with other ESLint configuration tools and plugins.
170

171
```typescript
172
import { defineFlatConfigs } from "@nuxt/eslint-config";
173
import { composer } from "eslint-flat-config-utils";
174
import gitignore from "eslint-config-flat-gitignore";
175

176
// Integration with eslint-flat-config-utils
177
export default defineFlatConfigs(
178
  gitignore({ strict: false }),
179
  
180
  // Use the composer directly if needed
181
  ...composer(
182
    {
183
      name: "base",
184
      rules: { "no-console": "warn" }
185
    },
186
    {
187
      name: "typescript",
188
      files: ["**/*.ts"],
189
      rules: { "@typescript-eslint/no-explicit-any": "error" }
190
    }
191
  )
192
);
193
```