0
# Plugin Configuration
1

2
Comprehensive configuration options for the vite-plugin-dts plugin, controlling declaration file generation, TypeScript compilation, and build integration.
3

4
## Capabilities
5

6
### Core Plugin Function
7

8
Main plugin factory function that creates a Vite plugin instance with TypeScript declaration generation capabilities.
9

10
```typescript { .api }
11
/**
12
 * Creates a Vite plugin that generates declaration files from TypeScript and Vue source files
13
 * @param options - Configuration options for the plugin
14
 * @returns Configured Vite plugin instance
15
 */
16
function dts(options?: PluginOptions): import('vite').Plugin;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { defineConfig } from "vite";
23
import dts from "vite-plugin-dts";
24

25
// Basic usage with default settings
26
export default defineConfig({
27
  plugins: [dts()]
28
});
29

30
// Advanced configuration
31
export default defineConfig({
32
  plugins: [
33
    dts({
34
      outDir: ["dist", "types"],
35
      include: ["src/**/*.ts", "src/**/*.vue"],
36
      exclude: ["src/**/*.test.ts"],
37
      rollupTypes: true,
38
      insertTypesEntry: true
39
    })
40
  ]
41
});
42
```
43

44
### Plugin Options Interface
45

46
Complete configuration interface defining all available plugin options.
47

48
```typescript { .api }
49
interface PluginOptions {
50
  /** Specify root directory (defaults to Vite config root or process.cwd()) */
51
  root?: string;
52
  
53
  /** Output directory for declaration files (can be array for multiple outputs) */
54
  outDir?: string | string[];
55
  
56
  /** Override root path of entry files (useful in monorepos) */
57
  entryRoot?: string;
58
  
59
  /** Restrict declaration files output to outDir (default: true) */
60
  strictOutput?: boolean;
61
  
62
  /** Override TypeScript compiler options */
63
  compilerOptions?: ts.CompilerOptions | null;
64
  
65
  /** Specify tsconfig.json path for resolving include/exclude globs */
66
  tsconfigPath?: string;
67
  
68
  /** Custom resolvers for non-standard file types (default: []) */
69
  resolvers?: Resolver[];
70
  
71
  /** Parse tsconfig.json paths to aliases for declaration files (default: true) */
72
  pathsToAliases?: boolean;
73
  
74
  /** Exclude paths when transforming aliases (default: []) */
75
  aliasesExclude?: (string | RegExp)[];
76
  
77
  /** Transform '.vue.d.ts' filenames to '.d.ts' (default: false) */
78
  cleanVueFileName?: boolean;
79
  
80
  /** Transform dynamic imports to static imports (default: false, forced true when rollupTypes is true) */
81
  staticImport?: boolean;
82
  
83
  /** Override include glob patterns (relative to root) */
84
  include?: string | string[];
85
  
86
  /** Override exclude glob patterns (default: 'node_modules/**') */
87
  exclude?: string | string[];
88
  
89
  /** Remove pure import statements like 'import "xxx"' (default: true) */
90
  clearPureImport?: boolean;
91
  
92
  /** Generate types entry file(s) based on package.json types property (default: false, forced true when rollupTypes is true) */
93
  insertTypesEntry?: boolean;
94
  
95
  /** Bundle declaration files using @microsoft/api-extractor (default: false) */
96
  rollupTypes?: boolean;
97
  
98
  /** Bundled packages configuration for @microsoft/api-extractor (default: []) */
99
  bundledPackages?: string[];
100
  
101
  /** Override @microsoft/api-extractor configuration */
102
  rollupConfig?: RollupConfig;
103
  
104
  /** Override @microsoft/api-extractor invoke options */
105
  rollupOptions?: IExtractorInvokeOptions;
106
  
107
  /** Copy existing .d.ts source files to outDir (default: false) */
108
  copyDtsFiles?: boolean;
109
  
110
  /** Emit only declaration files, removing all other Vite outputs (default: false) */
111
  declarationOnly?: boolean;
112
  
113
  /** Logging level for this plugin (defaults to Vite config logLevel) */
114
  logLevel?: LogLevel;
115
  
116
  /** Hook called after TypeScript diagnostics are emitted */
117
  afterDiagnostic?: (diagnostics: readonly ts.Diagnostic[]) => MaybePromise<void>;
118
  
119
  /** Hook called before writing each declaration file (return false to skip file) */
120
  beforeWriteFile?: (
121
    filePath: string,
122
    content: string
123
  ) => MaybePromise<void | false | { filePath?: string; content?: string }>;
124
  
125
  /** Hook called after declaration files are bundled with rollupTypes */
126
  afterRollup?: (result: ExtractorResult) => MaybePromise<void>;
127
  
128
  /** Hook called after all declaration files are written */
129
  afterBuild?: (emittedFiles: Map<string, string>) => MaybePromise<void>;
130
}
131
```
132

133
### Directory and Path Configuration
134

135
Options controlling file paths and directory structure for generated declaration files.
136

137
```typescript { .api }
138
// Root directory configuration
139
root?: string;
140

141
// Output directory (single or multiple)
142
outDir?: string | string[];
143

144
// Entry root for monorepo scenarios
145
entryRoot?: string;
146

147
// Restrict output to specified directories
148
strictOutput?: boolean;
149
```
150

151
**Usage Examples:**
152

153
```typescript
154
// Multiple output directories
155
dts({
156
  outDir: ["dist/types", "lib/types"]
157
});
158

159
// Monorepo configuration
160
dts({
161
  root: "./packages/core",
162
  entryRoot: "./packages/core/src",
163
  outDir: "./packages/core/dist"
164
});
165
```
166

167
### TypeScript Compiler Configuration
168

169
Options for customizing TypeScript compilation behavior and tsconfig.json integration.
170

171
```typescript { .api }
172
// TypeScript compiler options override
173
compilerOptions?: ts.CompilerOptions | null;
174

175
// Path to specific tsconfig.json file
176
tsconfigPath?: string;
177

178
// File inclusion/exclusion patterns
179
include?: string | string[];
180
exclude?: string | string[];
181
```
182

183
**Usage Examples:**
184

185
```typescript
186
// Override compiler options
187
dts({
188
  compilerOptions: {
189
    target: "ES2020",
190
    module: "ESNext",
191
    strict: true
192
  }
193
});
194

195
// Use specific tsconfig
196
dts({
197
  tsconfigPath: "./tsconfig.build.json"
198
});
199

200
// Custom file patterns
201
dts({
202
  include: ["src/**/*.ts", "types/**/*.d.ts"],
203
  exclude: ["**/*.test.ts", "**/*.spec.ts"]
204
});
205
```
206

207
### Import and Alias Configuration
208

209
Settings for handling module aliases and import transformations in generated declaration files.
210

211
```typescript { .api }
212
// Convert tsconfig paths to Vite aliases
213
pathsToAliases?: boolean;
214

215
// Exclude specific aliases from transformation
216
aliasesExclude?: (string | RegExp)[];
217

218
// Convert dynamic to static imports
219
staticImport?: boolean;
220

221
// Remove pure import statements
222
clearPureImport?: boolean;
223
```
224

225
**Usage Examples:**
226

227
```typescript
228
// Disable alias transformation for specific patterns
229
dts({
230
  pathsToAliases: true,
231
  aliasesExclude: [/^@types\//, "virtual:*"]
232
});
233

234
// Force static imports for better bundling
235
dts({
236
  staticImport: true,
237
  clearPureImport: false
238
});
239
```
240

241
### Declaration File Generation Options
242

243
Configuration for the structure and format of generated declaration files.
244

245
```typescript { .api }
246
// Generate main entry declaration files
247
insertTypesEntry?: boolean;
248

249
// Bundle all declarations into single files
250
rollupTypes?: boolean;
251

252
// Copy existing .d.ts files
253
copyDtsFiles?: boolean;
254

255
// Remove non-declaration outputs
256
declarationOnly?: boolean;
257

258
// Clean Vue file naming
259
cleanVueFileName?: boolean;
260
```
261

262
**Usage Examples:**
263

264
```typescript
265
// Bundle declarations with entry generation
266
dts({
267
  insertTypesEntry: true,
268
  rollupTypes: true,
269
  declarationOnly: true
270
});
271

272
// Vue project configuration
273
dts({
274
  cleanVueFileName: true,
275
  include: ["src/**/*.ts", "src/**/*.vue"]
276
});
277
```
278

279
### Build Lifecycle Hooks
280

281
Callback functions for customizing plugin behavior at different stages of the build process.
282

283
```typescript { .api }
284
/**
285
 * Called after TypeScript diagnostics are emitted
286
 * Use diagnostics.length to check for type errors
287
 */
288
afterDiagnostic?: (diagnostics: readonly ts.Diagnostic[]) => MaybePromise<void>;
289

290
/**
291
 * Called before writing each declaration file
292
 * Return false to skip the file, or modify path/content
293
 */
294
beforeWriteFile?: (
295
  filePath: string,
296
  content: string
297
) => MaybePromise<void | false | { filePath?: string; content?: string }>;
298

299
/**
300
 * Called after declaration bundling with api-extractor
301
 */
302
afterRollup?: (result: ExtractorResult) => MaybePromise<void>;
303

304
/**
305
 * Called after all declaration files are written
306
 * Receives map of file paths to their content
307
 */
308
afterBuild?: (emittedFiles: Map<string, string>) => MaybePromise<void>;
309
```
310

311
**Usage Examples:**
312

313
```typescript
314
dts({
315
  afterDiagnostic: async (diagnostics) => {
316
    if (diagnostics.length > 0) {
317
      console.warn(`Found ${diagnostics.length} type issues`);
318
    }
319
  },
320
  
321
  beforeWriteFile: async (filePath, content) => {
322
    // Add custom header to all declaration files
323
    if (filePath.endsWith('.d.ts')) {
324
      return {
325
        content: `// Generated by vite-plugin-dts\n${content}`
326
      };
327
    }
328
  },
329
  
330
  afterBuild: async (emittedFiles) => {
331
    console.log(`Generated ${emittedFiles.size} declaration files`);
332
  }
333
});
334
```