0
# Configuration
1

2
Bunli's configuration system provides type-safe project settings through configuration files and programmatic APIs. Configuration files are automatically discovered and loaded from the project root.
3

4
## Capabilities
5

6
### Configuration Definition
7

8
Helper function for creating type-safe configuration files with full IntelliSense support.
9

10
```typescript { .api }
11
/**
12
 * Type-safe helper for defining bunli configuration files
13
 * @param config - Configuration object following BunliConfig schema
14
 * @returns The same configuration object with type validation
15
 */
16
function defineConfig(config: BunliConfig): BunliConfig;
17
```
18

19
**Usage Example:**
20

21
```typescript
22
// bunli.config.ts
23
import { defineConfig } from 'bunli';
24

25
export default defineConfig({
26
  name: 'my-awesome-cli',
27
  version: '1.0.0',
28
  description: 'An awesome CLI built with Bunli',
29

30
  build: {
31
    entry: 'src/cli.ts',
32
    outdir: 'dist',
33
    targets: ['darwin-arm64', 'linux-x64', 'windows-x64'],
34
    minify: true,
35
    sourcemap: false,
36
    compress: true
37
  },
38

39
  dev: {
40
    watch: true,
41
    inspect: false,
42
    port: 9229
43
  },
44

45
  test: {
46
    pattern: ['**/*.test.ts', '**/*.spec.ts'],
47
    coverage: true,
48
    watch: false
49
  },
50

51
  release: {
52
    npm: true,
53
    github: true,
54
    tagFormat: 'v${version}',
55
    conventionalCommits: true
56
  }
57
});
58
```
59

60
### Configuration Loading
61

62
Loads configuration from multiple file formats with automatic discovery.
63

64
```typescript { .api }
65
/**
66
 * Loads bunli configuration from config files
67
 * @param cwd - Current working directory to search for config files (defaults to process.cwd())
68
 * @returns Promise resolving to the loaded configuration or empty object if no config found
69
 */
70
function loadConfig(cwd?: string): Promise<BunliConfig>;
71
```
72

73
**Configuration File Discovery:**
74

75
Bunli searches for configuration files in the following order:
76
1. `bunli.config.ts`
77
2. `bunli.config.js`
78
3. `bunli.config.mjs`
79

80
**Usage Example:**
81

82
```typescript
83
import { loadConfig } from 'bunli';
84

85
// Load from current directory
86
const config = await loadConfig();
87

88
// Load from specific directory
89
const projectConfig = await loadConfig('/path/to/project');
90

91
// Access configuration values
92
console.log(`Building ${config.name || 'CLI'} v${config.version || '1.0.0'}`);
93
```
94

95
### Configuration Schema
96

97
Complete configuration type definition with all available options.
98

99
```typescript { .api }
100
interface BunliConfig {
101
  /** Project name */
102
  name?: string;
103
  /** Project version */
104
  version?: string;
105
  /** Project description */
106
  description?: string;
107

108
  /** Commands configuration */
109
  commands?: {
110
    /** Path to commands manifest file */
111
    manifest?: string;
112
    /** Directory containing command files */
113
    directory?: string;
114
  };
115

116
  /** Build configuration */
117
  build?: BuildConfig;
118
  /** Development configuration */
119
  dev?: DevConfig;
120
  /** Testing configuration */
121
  test?: TestConfig;
122
  /** Release configuration */
123
  release?: ReleaseConfig;
124
  /** Workspace configuration for monorepos */
125
  workspace?: WorkspaceConfig;
126
}
127

128
interface BuildConfig {
129
  /** Entry point file(s) for compilation */
130
  entry?: string | string[];
131
  /** Output directory for built files */
132
  outdir?: string;
133
  /** Target platforms for compilation */
134
  targets?: string[];
135
  /** Enable compression for multi-target builds */
136
  compress?: boolean;
137
  /** External dependencies to exclude from bundle */
138
  external?: string[];
139
  /** Enable minification */
140
  minify?: boolean;
141
  /** Generate source maps */
142
  sourcemap?: boolean;
143
}
144

145
interface DevConfig {
146
  /** Enable file watching and hot reload */
147
  watch?: boolean;
148
  /** Enable debugger */
149
  inspect?: boolean;
150
  /** Debugger port number */
151
  port?: number;
152
}
153

154
interface TestConfig {
155
  /** Test file patterns to match */
156
  pattern?: string | string[];
157
  /** Generate coverage reports */
158
  coverage?: boolean;
159
  /** Enable watch mode for tests */
160
  watch?: boolean;
161
}
162

163
interface ReleaseConfig {
164
  /** Publish to npm registry */
165
  npm?: boolean;
166
  /** Create GitHub release */
167
  github?: boolean;
168
  /** Git tag format string (use ${version} placeholder) */
169
  tagFormat?: string;
170
  /** Use conventional commits for changelog */
171
  conventionalCommits?: boolean;
172
}
173

174
interface WorkspaceConfig {
175
  /** Package patterns for workspace detection */
176
  packages?: string[];
177
  /** Shared workspace configuration */
178
  shared?: any;
179
  /** Version strategy for workspace packages */
180
  versionStrategy?: 'fixed' | 'independent';
181
}
182
```
183

184
### Build Targets
185

186
Supported compilation targets for standalone executable generation:
187

188
- `native` - Current platform architecture
189
- `all` - All supported platforms
190
- `darwin-arm64` - macOS Apple Silicon
191
- `darwin-x64` - macOS Intel
192
- `linux-arm64` - Linux ARM64
193
- `linux-x64` - Linux x86_64
194
- `windows-x64` - Windows x86_64
195

196
### Configuration Validation
197

198
Configuration is automatically validated using Zod schemas, providing runtime type checking and helpful error messages for invalid configurations.