0
# Configuration
1

2
Type-safe configuration system with defineConfig helper and extensive options for customizing the build process. Supports multiple configuration patterns including arrays, functions, and workspace configurations.
3

4
## Capabilities
5

6
### Define Configuration
7

8
Type-safe configuration helper that provides IntelliSense and validation for build options.
9

10
```typescript { .api }
11
/**
12
 * Defines the configuration for tsdown with type safety
13
 * @param options - Static configuration object
14
 */
15
function defineConfig(options: UserConfig): UserConfig;
16

17
/**
18
 * Defines the configuration for tsdown with dynamic configuration
19
 * @param options - Function that returns configuration based on CLI options
20
 */
21
function defineConfig(options: UserConfigFn): UserConfigFn;
22
```
23

24
**Usage Examples:**
25

26
```typescript
27
import { defineConfig } from "tsdown";
28

29
// Simple static configuration
30
export default defineConfig({
31
  entry: "src/index.ts",
32
  format: ["esm", "cjs"],
33
  dts: true
34
});
35

36
// Multiple configurations
37
export default defineConfig([
38
  {
39
    entry: "src/index.ts",
40
    format: "esm",
41
    outDir: "dist/esm"
42
  },
43
  {
44
    entry: "src/index.ts", 
45
    format: "cjs",
46
    outDir: "dist/cjs"
47
  }
48
]);
49

50
// Dynamic configuration based on CLI options
51
export default defineConfig((options) => {
52
  return {
53
    entry: "src/index.ts",
54
    format: options.watch ? ["esm"] : ["esm", "cjs"],
55
    minify: !options.watch,
56
    sourcemap: options.watch
57
  };
58
});
59

60
// Conditional configuration
61
export default defineConfig((options) => {
62
  const config = {
63
    entry: "src/index.ts",
64
    format: ["esm", "cjs"] as const,
65
    dts: true
66
  };
67

68
  if (process.env.NODE_ENV === "production") {
69
    config.minify = true;
70
    config.sourcemap = false;
71
  }
72

73
  return config;
74
});
75
```
76

77
### Configuration Types
78

79
Type definitions for configuration objects and functions.
80

81
```typescript { .api }
82
/**
83
 * User configuration type supporting single config or array of configs
84
 */
85
type UserConfig = Arrayable<Omit<Options, 'config' | 'filter'>>;
86

87
/**
88
 * User configuration function type for dynamic configuration
89
 * @param cliOptions - Options passed from CLI
90
 * @returns Configuration object or array
91
 */
92
type UserConfigFn = (cliOptions: Options) => Awaitable<UserConfig>;
93

94
/**
95
 * Normalized user configuration (array flattened)
96
 */
97
type NormalizedUserConfig = Exclude<UserConfig, any[]>;
98
```
99

100
### Options Resolution
101

102
Main function for resolving and processing configuration options.
103

104
```typescript { .api }
105
/**
106
 * Resolve user options into build configurations
107
 * @param options - Raw options from CLI or API
108
 * @returns Resolved configurations and config file paths
109
 */
110
function resolveOptions(options: Options): Promise<{
111
  configs: ResolvedOptions[];
112
  files: string[];
113
}>;
114
```
115

116
### Configuration File Loading
117

118
Configuration files are automatically detected in the following order:
119

120
1. `tsdown.config.ts`
121
2. `tsdown.config.cts` 
122
3. `tsdown.config.mts`
123
4. `tsdown.config.js`
124
5. `tsdown.config.cjs`
125
6. `tsdown.config.mjs`
126
7. `tsdown.config.json`
127

128
**TypeScript Configuration Example:**
129

130
```typescript
131
// tsdown.config.ts
132
import { defineConfig } from "tsdown";
133

134
export default defineConfig({
135
  entry: "src/index.ts",
136
  format: ["esm", "cjs"],
137
  dts: true,
138
  sourcemap: true,
139
  external: ["react", "react-dom"],
140
  target: "es2020"
141
});
142
```
143

144
**JavaScript Configuration Example:**
145

146
```javascript
147
// tsdown.config.js
148
import { defineConfig } from "tsdown";
149

150
export default defineConfig({
151
  entry: "src/index.js",
152
  format: ["esm", "cjs"],
153
  minify: true,
154
  outDir: "lib"
155
});
156
```
157

158
**JSON Configuration Example:**
159

160
```json
161
{
162
  "entry": "src/index.ts",
163
  "format": ["esm", "cjs"],
164
  "dts": true,
165
  "outDir": "dist"
166
}
167
```
168

169
### Multi-Configuration Setup
170

171
Support for building multiple configurations in a single run.
172

173
```typescript { .api }
174
// Multiple entry points
175
export default defineConfig([
176
  {
177
    entry: "src/index.ts",
178
    format: "esm",
179
    outDir: "dist/esm"
180
  },
181
  {
182
    entry: "src/cli.ts",
183
    format: "esm", 
184
    outDir: "dist/cli",
185
    external: ["commander"]
186
  }
187
]);
188

189
// Different formats for same entry
190
export default defineConfig([
191
  {
192
    entry: "src/index.ts",
193
    format: "esm",
194
    platform: "neutral"
195
  },
196
  {
197
    entry: "src/index.ts",
198
    format: "cjs", 
199
    platform: "node"
200
  }
201
]);
202
```
203

204
### Vite Integration
205

206
Integration with existing Vite configurations for plugin reuse.
207

208
```typescript { .api }
209
interface Options {
210
  /**
211
   * Reuse config from Vite or Vitest (experimental)
212
   * @default false
213
   */
214
  fromVite?: boolean | 'vitest';
215
}
216
```
217

218
**Usage Example:**
219

220
```typescript
221
export default defineConfig({
222
  entry: "src/index.ts",
223
  format: ["esm", "cjs"],
224
  fromVite: true, // Reuse vite.config.ts plugins and aliases
225
  dts: true
226
});
227
```
228

229
### Configuration Validation
230

231
The configuration system validates options and provides helpful error messages:
232

233
- **Type Safety**: TypeScript integration catches type mismatches
234
- **Option Validation**: Invalid combinations are detected and reported
235
- **Path Resolution**: Entry points and output directories are validated
236
- **Plugin Compatibility**: Plugin compatibility warnings are shown
237
- **Format Validation**: Unsupported format combinations are flagged
238

239
### Environment-Based Configuration
240

241
Configuration can be adapted based on environment variables and runtime conditions.
242

243
```typescript
244
export default defineConfig((options) => {
245
  const isDev = process.env.NODE_ENV === "development";
246
  const isProd = process.env.NODE_ENV === "production";
247
  
248
  return {
249
    entry: "src/index.ts",
250
    format: ["esm", "cjs"],
251
    minify: isProd,
252
    sourcemap: isDev ? "inline" : false,
253
    watch: isDev,
254
    dts: isProd,
255
    clean: isProd
256
  };
257
});
258
```
259

260
### Merging User Options
261

262
Utility function for merging configuration objects with proper async handling.
263

264
```typescript { .api }
265
/**
266
 * Merge user options with defaults
267
 * @param defaults - Default configuration
268
 * @param user - User configuration (object, function, or null)
269
 * @param args - Additional arguments for function configurations
270
 * @returns Merged configuration
271
 */
272
function mergeUserOptions<T extends object, A extends unknown[]>(
273
  defaults: T,
274
  user: T | undefined | null | ((options: T, ...args: A) => Awaitable<T | void | null>),
275
  args: A
276
): Promise<T>;
277
```
278

279
This utility is used internally for merging `inputOptions` and `outputOptions` with their respective defaults while supporting both static objects and dynamic functions.