0
# Configuration
1

2
Flexible configuration system supporting project-level and workspace-level settings with extensive customization options. Knip supports multiple configuration file formats and locations.
3

4
## Capabilities
5

6
### Configuration Types
7

8
Core configuration interface for customizing Knip behavior.
9

10
```typescript { .api }
11
/**
12
 * Main configuration type for Knip
13
 */
14
type KnipConfig = {
15
  /** Entry files patterns */
16
  entry?: string | string[];
17
  /** Project files patterns */
18
  project?: string | string[];
19
  /** Files to ignore during analysis */
20
  ignore?: string | string[];
21
  /** Binary executables to ignore */
22
  ignoreBinaries?: (string | RegExp)[];
23
  /** Dependencies to ignore */
24
  ignoreDependencies?: (string | RegExp)[];
25
  /** Unresolved imports to ignore */
26
  ignoreUnresolved?: (string | RegExp)[];
27
  /** Class/interface members to ignore */
28
  ignoreMembers?: (string | RegExp)[];
29
  /** Workspaces to ignore */
30
  ignoreWorkspaces?: string[];
31
  /** Export usage rules per file */
32
  ignoreExportsUsedInFile?: boolean | Partial<Record<SymbolType, boolean>>;
33
  /** Include entry exports in unused exports report */
34
  isIncludeEntryExports?: boolean;
35
  /** Workspace-specific configurations */
36
  workspaces?: Record<string, WorkspaceConfiguration>;
37
  /** Plugin configurations */
38
  [pluginName: string]: PluginConfiguration | any;
39
};
40

41
interface WorkspaceConfiguration {
42
  /** Entry files for this workspace */
43
  entry?: string | string[];
44
  /** Project files for this workspace */
45
  project?: string | string[];
46
  /** Files to ignore in this workspace */
47
  ignore?: string | string[];
48
  /** TypeScript path mappings */
49
  paths?: Record<string, string[]>;
50
  /** Include entry exports for this workspace */
51
  isIncludeEntryExports?: boolean;
52
  /** Plugin configurations for this workspace */
53
  [pluginName: string]: PluginConfiguration | any;
54
}
55

56
type PluginConfiguration = boolean | {
57
  /** Configuration files for the plugin */
58
  config?: string | string[];
59
  /** Entry files for the plugin */
60
  entry?: string | string[];
61
  /** Project files for the plugin */
62
  project?: string | string[];
63
};
64
```
65

66
**Usage Examples:**
67

68
### Basic Configuration
69

70
```json
71
{
72
  "entry": ["src/index.ts", "src/cli.ts"],
73
  "project": ["src/**/*.ts", "scripts/**/*.js"],
74
  "ignore": ["src/**/*.test.ts", "src/**/*.spec.ts"],
75
  "ignoreDependencies": ["@types/*"],
76
  "ignoreBinaries": ["git", "npm"]
77
}
78
```
79

80
### Workspace Configuration
81

82
```json
83
{
84
  "workspaces": {
85
    "packages/frontend": {
86
      "entry": ["src/main.tsx"],
87
      "project": ["src/**/*.{ts,tsx}"],
88
      "ignore": ["src/**/*.test.{ts,tsx}"]
89
    },
90
    "packages/backend": {
91
      "entry": ["src/server.ts"],
92
      "project": ["src/**/*.ts"],
93
      "ignore": ["src/**/*.test.ts"]
94
    }
95
  }
96
}
97
```
98

99
### Plugin-Specific Configuration
100

101
```json
102
{
103
  "jest": {
104
    "config": ["jest.config.js"],
105
    "entry": ["src/**/*.test.ts", "src/**/*.spec.ts"]
106
  },
107
  "webpack": {
108
    "config": ["webpack.config.js", "webpack.*.js"],
109
    "entry": ["src/webpack.config.js"]
110
  },
111
  "eslint": true,
112
  "prettier": false
113
}
114
```
115

116
### Configuration File Locations
117

118
Knip searches for configuration in multiple locations and formats.
119

120
```typescript { .api }
121
/** Supported configuration file locations */
122
const KNIP_CONFIG_LOCATIONS = [
123
  'knip.json',
124
  'knip.jsonc',
125
  '.knip.json',
126
  '.knip.jsonc',
127
  'knip.ts',
128
  'knip.js',
129
  'knip.config.ts',
130
  'knip.config.js'
131
];
132
```
133

134
**Configuration Priority:**
135

136
1. CLI `--config` option
137
2. Configuration files in order listed above
138
3. `package.json` `knip` field
139
4. Default configuration
140

141
### Configuration Loading
142

143
Functions for loading and validating configuration files.
144

145
```typescript { .api }
146
/**
147
 * Create analysis options from CLI arguments and configuration
148
 * @param options - Partial options including parsed CLI args
149
 * @returns Complete options for analysis
150
 */
151
function createOptions(options: CreateOptions): Promise<MainOptions>;
152

153
interface CreateOptions {
154
  /** Parsed CLI arguments */
155
  parsedCLIArgs?: ParsedArgs;
156
  /** Working directory */
157
  cwd?: string;
158
  /** Additional option overrides */
159
  [key: string]: any;
160
}
161

162
/**
163
 * Load configuration file from specified path
164
 * @param configPath - Path to configuration file
165
 * @returns Parsed configuration object
166
 */
167
function loadConfig(configPath: string): Promise<KnipConfig>;
168
```
169

170
**Usage Examples:**
171

172
```typescript
173
import { createOptions, loadConfig } from "knip";
174

175
// Load configuration manually
176
const config = await loadConfig('./knip.config.js');
177

178
// Create complete options from CLI args
179
const options = await createOptions({
180
  parsedCLIArgs: { production: true, config: './knip.json' },
181
  cwd: process.cwd()
182
});
183
```
184

185
### Ignore Patterns
186

187
Various ignore pattern configurations for fine-tuning analysis.
188

189
```typescript { .api }
190
/** Pattern types for ignoring items */
191
type IgnorePatterns = (string | RegExp)[];
192

193
/** Export ignore configuration per symbol type */
194
type IgnoreExportsUsedInFile = boolean | Partial<Record<SymbolType, boolean>>;
195

196
enum SymbolType {
197
  VARIABLE = 'variable',
198
  TYPE = 'type',
199
  INTERFACE = 'interface',
200
  ENUM = 'enum',
201
  FUNCTION = 'function',
202
  CLASS = 'class',
203
  MEMBER = 'member',
204
  UNKNOWN = 'unknown'
205
}
206
```
207

208
**Advanced Ignore Examples:**
209

210
```json
211
{
212
  "ignoreDependencies": [
213
    "@types/*",
214
    /^@babel\/.*/,
215
    "webpack"
216
  ],
217
  "ignoreBinaries": [
218
    "git",
219
    "docker",
220
    /^npm.*/
221
  ],
222
  "ignoreUnresolved": [
223
    "virtual:*",
224
    "*.css",
225
    "*.png"
226
  ],
227
  "ignoreExportsUsedInFile": {
228
    "interface": true,
229
    "type": true,
230
    "enum": false
231
  }
232
}
233
```
234

235
### Plugin Configuration
236

237
Configuration system for enabling and configuring plugins.
238

239
```typescript { .api }
240
interface Plugin {
241
  /** Plugin display name */
242
  title: string;
243
  /** Files/packages that enable this plugin */
244
  enablers?: IgnorePatterns | string;
245
  /** Custom enablement logic */
246
  isEnabled?: IsPluginEnabled;
247
  /** Only run in root workspace */
248
  isRootOnly?: boolean;
249
  /** Configuration file patterns */
250
  config?: string[];
251
  /** Entry file patterns */
252
  entry?: string[];
253
  /** Production file patterns */
254
  production?: string[];
255
  /** Project file patterns */
256
  project?: string[];
257
}
258

259
type IsPluginEnabled = (options: PluginOptions) => boolean | Promise<boolean>;
260

261
interface PluginOptions {
262
  /** Root working directory */
263
  rootCwd: string;
264
  /** Current working directory */
265
  cwd: string;
266
  /** Package.json manifest */
267
  manifest: PackageJson;
268
  /** Plugin configuration */
269
  config: EnsuredPluginConfiguration;
270
  /** Configuration file directory */
271
  configFileDir: string;
272
  /** Configuration file name */
273
  configFileName: string;
274
  /** Configuration file path */
275
  configFilePath: string;
276
  /** Production mode flag */
277
  isProduction: boolean;
278
  /** List of enabled plugins */
279
  enabledPlugins: string[];
280
}
281
```
282

283
**Plugin Configuration Examples:**
284

285
```json
286
{
287
  "jest": {
288
    "config": ["jest.config.{js,ts,json}"],
289
    "entry": ["**/*.{test,spec}.{js,ts,tsx}"]
290
  },
291
  "webpack": {
292
    "config": ["webpack.config.js"],
293
    "entry": ["webpack.config.js"]
294
  },
295
  "typescript": {
296
    "config": ["tsconfig.json", "tsconfig.*.json"],
297
    "project": ["**/*.ts", "**/*.tsx"]
298
  }
299
}
300
```
301

302
### Configuration Validation
303

304
Knip validates configuration and provides helpful hints.
305

306
```typescript { .api }
307
interface ConfigurationHint {
308
  /** Type of configuration hint */
309
  type: ConfigurationHintType;
310
  /** Pattern or identifier causing the hint */
311
  identifier: string | RegExp;
312
  /** Associated file path */
313
  filePath?: string;
314
  /** Workspace name */
315
  workspaceName?: string;
316
  /** Size metric for the hint */
317
  size?: number;
318
}
319

320
type ConfigurationHintType = 
321
  | 'ignoreBinaries'
322
  | 'ignoreDependencies' 
323
  | 'ignoreUnresolved'
324
  | 'ignoreWorkspaces'
325
  | 'entry-redundant'
326
  | 'project-redundant'
327
  | 'entry-top-level'
328
  | 'project-top-level'
329
  | 'entry-empty'
330
  | 'project-empty'
331
  | 'package-entry'
332
  | 'workspace-unconfigured';
333
```
334

335
**Common Configuration Hints:**
336

337
- `entry-redundant`: Entry patterns that don't match any files
338
- `project-redundant`: Project patterns that don't match any files  
339
- `workspace-unconfigured`: Workspaces without specific configuration
340
- `ignoreDependencies`: Suggest adding frequently unused dependencies to ignore list