0
# Configuration
1

2
Comprehensive configuration system supporting file-based configuration, environment variables, and runtime options with intelligent defaults and full type safety.
3

4
## Configuration Methods
5

6
### File-based Configuration
7

8
Taze automatically discovers and loads configuration from several file formats:
9

10
```typescript { .api }
11
// taze.config.js or taze.config.ts
12
export default {
13
  mode: "minor",
14
  recursive: true,
15
  include: ["react*"],
16
  exclude: ["legacy-*"]
17
};
18

19
// .tazerc.json
20
{
21
  "mode": "patch",
22
  "write": false,
23
  "interactive": true
24
}
25

26
// .tazerc (JSON format)
27
{
28
  "recursive": true,
29
  "sort": "diff-desc"
30
}
31
```
32

33
### Programmatic Configuration
34

35
```typescript { .api }
36
import { defineConfig, CheckPackages } from "taze";
37

38
const config = defineConfig({
39
  mode: "minor",
40
  include: ["@types/*"],
41
  depFields: {
42
    dependencies: true,
43
    devDependencies: true,
44
    peerDependencies: false
45
  }
46
});
47

48
await CheckPackages(config);
49
```
50

51
## Configuration Options
52

53
### Core Check Options
54

55
```typescript { .api }
56
interface CheckOptions extends CommonOptions {
57
  /** Update mode determining version range changes */
58
  mode?: RangeMode;
59
  /** Write changes to package.json files */
60
  write?: boolean;
61
  /** Show all packages including up-to-date ones */
62
  all?: boolean;
63
  /** Sort results by specified criteria */
64
  sort?: SortOption;
65
  /** Enable interactive mode for selective updates */
66
  interactive?: boolean;
67
  /** Run package manager install after updating */
68
  install?: boolean;
69
  /** Run package manager update after updating */
70
  update?: boolean;
71
  /** Update global packages instead of local ones */
72
  global?: boolean;
73
  /** Number of concurrent requests to package registries */
74
  concurrency?: number;
75
  /** Group dependencies by source type in display */
76
  group?: boolean;
77
  /** Include locked dependencies and devDependencies */
78
  includeLocked?: boolean;
79
  /** Show time difference between current and updated versions */
80
  timediff?: boolean;
81
  /** Show package compatibility with current Node.js version */
82
  nodecompat?: boolean;
83
}
84
```
85

86
### Common Options
87

88
```typescript { .api }
89
interface CommonOptions {
90
  /** Current working directory */
91
  cwd?: string;
92
  /** Recursively search for package.json files */
93
  recursive?: boolean;
94
  /** Paths to ignore during recursive search */
95
  ignorePaths?: string | string[];
96
  /** Ignore package.json files in other workspaces */
97
  ignoreOtherWorkspaces?: boolean;
98
  /** Only check specified dependencies */
99
  include?: string | string[];
100
  /** Exclude specified dependencies from checks */
101
  exclude?: string | string[];
102
  /** Logging level */
103
  loglevel?: LogLevel;
104
  /** Exit with code 1 if outdated dependencies found */
105
  failOnOutdated?: boolean;
106
  /** Complete silent mode */
107
  silent?: boolean;
108
  /** Package.json fields to check for dependencies */
109
  depFields?: DepFieldOptions;
110
  /** Force fetching from server, bypass cache */
111
  force?: boolean;
112
  /** Include peerDependencies in update process */
113
  peer?: boolean;
114
  /** Override update mode for specific packages */
115
  packageMode?: { [name: string]: PackageMode };
116
  /** Custom addons for extending functionality */
117
  addons?: Addon[];
118
}
119
```
120

121
## Configuration Types
122

123
### Range Modes
124

125
```typescript { .api }
126
type RangeMode = "default" | "major" | "minor" | "patch" | "latest" | "newest" | "next";
127
```
128

129
- `default`: Respect existing version ranges (safe)
130
- `major`: Allow major version updates (breaking changes)
131
- `minor`: Allow minor version updates (new features)
132
- `patch`: Allow patch version updates (bug fixes only)
133
- `latest`: Update to latest stable version
134
- `newest`: Update to newest version (including pre-release)
135
- `next`: Update to next version tag
136

137
### Package Modes
138

139
```typescript { .api }
140
type PackageMode = Exclude<RangeMode, "default"> | "ignore";
141
```
142

143
Used in `packageMode` configuration to override the global mode for specific packages:
144

145
```typescript
146
const config = defineConfig({
147
  mode: "minor",
148
  packageMode: {
149
    "react": "patch",      // Only patch updates for React
150
    "legacy-lib": "ignore", // Never update this package
151
    "typescript": "major"   // Allow major updates for TypeScript
152
  }
153
});
154
```
155

156
### Dependency Field Options
157

158
```typescript { .api }
159
type DepFieldOptions = Partial<Record<DepType, boolean>>;
160

161
type DepType =
162
  | "dependencies"
163
  | "devDependencies"
164
  | "peerDependencies"
165
  | "optionalDependencies"
166
  | "packageManager"
167
  | "pnpm.overrides"
168
  | "resolutions"
169
  | "overrides"
170
  | "pnpm-workspace";
171
```
172

173
Control which dependency fields are processed:
174

175
```typescript
176
const config = defineConfig({
177
  depFields: {
178
    dependencies: true,        // Check production dependencies
179
    devDependencies: true,     // Check development dependencies
180
    peerDependencies: false,   // Skip peer dependencies
181
    optionalDependencies: true, // Check optional dependencies
182
    "pnpm.overrides": true     // Check pnpm overrides
183
  }
184
});
185
```
186

187
### Sort Options
188

189
```typescript { .api }
190
type SortOption = "diff-asc" | "diff-desc" | "name-asc" | "name-desc";
191
```
192

193
- `diff-asc`: Sort by update significance (patch → minor → major)
194
- `diff-desc`: Sort by update significance (major → minor → patch)
195
- `name-asc`: Sort alphabetically by package name (A-Z)
196
- `name-desc`: Sort alphabetically by package name (Z-A)
197

198
### Log Levels
199

200
```typescript { .api }
201
type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
202
```
203

204
## Default Configuration
205

206
```typescript { .api }
207
const DEFAULT_CHECK_OPTIONS: CheckOptions = {
208
  cwd: "",
209
  loglevel: "info",
210
  failOnOutdated: false,
211
  silent: false,
212
  recursive: false,
213
  force: false,
214
  ignorePaths: "",
215
  ignoreOtherWorkspaces: true,
216
  include: "",
217
  exclude: "",
218
  depFields: {},
219
  mode: "default",
220
  write: false,
221
  global: false,
222
  interactive: false,
223
  install: false,
224
  update: false,
225
  all: false,
226
  sort: "diff-asc",
227
  group: true,
228
  includeLocked: false,
229
  nodecompat: true,
230
  concurrency: 10
231
};
232
```
233

234
## Advanced Configuration
235

236
### Custom Addons
237

238
```typescript { .api }
239
interface Addon {
240
  /** Called after package resolution but before display */
241
  postprocess?: (pkg: PackageMeta, options: CheckOptions) => void | Promise<void>;
242
  /** Called before writing changes to package files */
243
  beforeWrite?: (pkg: PackageMeta, options: CheckOptions) => void | Promise<void>;
244
}
245
```
246

247
Example addon:
248

249
```typescript
250
const customAddon: Addon = {
251
  postprocess: (pkg, options) => {
252
    // Custom processing after dependency resolution
253
    console.log(`Processed ${pkg.name} with ${pkg.resolved.length} changes`);
254
  },
255
  beforeWrite: (pkg, options) => {
256
    // Custom validation before writing
257
    if (pkg.resolved.some(dep => dep.diff === "major")) {
258
      console.warn(`Major updates detected in ${pkg.name}`);
259
    }
260
  }
261
};
262

263
const config = defineConfig({
264
  addons: [customAddon]
265
});
266
```
267

268
### Workspace-specific Configuration
269

270
```typescript
271
// In workspace root
272
const config = defineConfig({
273
  recursive: true,
274
  packageMode: {
275
    // Different update strategies per package
276
    "@my-org/core": "patch",
277
    "@my-org/utils": "minor",
278
    "@my-org/experimental": "major"
279
  },
280
  depFields: {
281
    dependencies: true,
282
    devDependencies: false  // Don't update devDeps in workspaces
283
  }
284
});
285
```
286

287
### Environment-based Configuration
288

289
```typescript
290
const config = defineConfig({
291
  mode: process.env.NODE_ENV === "production" ? "patch" : "minor",
292
  write: process.env.CI !== "true", // Don't write in CI
293
  interactive: process.stdout.isTTY, // Interactive only in terminal
294
  force: process.env.TAZE_FORCE_REFRESH === "true"
295
});
296
```
297

298
## Configuration Resolution
299

300
Configuration is resolved in the following order (later sources override earlier ones):
301

302
1. Default configuration values
303
2. Configuration file (taze.config.js/ts, .tazerc.json, .tazerc)
304
3. Command-line arguments
305
4. Programmatic options passed to CheckPackages
306

307
### Example Resolution
308

309
```typescript
310
// .tazerc.json
311
{
312
  "mode": "minor",
313
  "write": false
314
}
315

316
// Command line: taze major --write
317
// Final configuration: { mode: "major", write: true }
318
```
319

320
## Configuration Validation
321

322
Taze performs automatic validation of configuration options:
323

324
```typescript
325
// Invalid configurations will throw helpful errors
326
const config = defineConfig({
327
  mode: "invalid-mode",    // Error: Invalid mode
328
  concurrency: -1,         // Error: Concurrency must be positive
329
  sort: "unknown-sort"     // Error: Invalid sort option
330
});
331
```
332

333
## Best Practices
334

335
### Project-specific Configuration
336

337
```typescript
338
// taze.config.ts - Committed to repository
339
export default defineConfig({
340
  mode: "minor",
341
  recursive: true,
342
  include: ["@types/*", "eslint*", "prettier"],
343
  exclude: ["react"], // Pin React version
344
  depFields: {
345
    dependencies: true,
346
    devDependencies: true,
347
    peerDependencies: false
348
  }
349
});
350
```
351

352
### CI/CD Configuration
353

354
```typescript
355
// Separate config for automated environments
356
export default defineConfig({
357
  mode: "patch",           // Conservative updates in CI
358
  write: false,            // Never write in CI
359
  failOnOutdated: true,    // Fail build if outdated
360
  silent: true,            // Minimal output
361
  force: true              // Always fetch latest data
362
});
363
```
364

365
### Development Workflow
366

367
```typescript
368
// Development-friendly configuration
369
export default defineConfig({
370
  mode: "minor",
371
  interactive: true,       // Allow selective updates
372
  write: true,            // Save changes immediately
373
  install: true,          // Auto-install after updates
374
  group: true,            // Organized display
375
  timediff: true,         // Show age of updates
376
  nodecompat: true        // Show compatibility info
377
});
378
```