0
# Vite Plugin DTS
1

2
Vite Plugin DTS is a comprehensive Vite plugin that automatically generates TypeScript declaration files (*.d.ts) from TypeScript (.ts, .tsx) and Vue (.vue) source files when building libraries with Vite. It provides flexible configuration options including declaration file bundling, custom resolvers, and advanced TypeScript compilation features.
3

4
## Package Information
5

6
- **Package Name**: vite-plugin-dts
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install vite-plugin-dts -D` or `pnpm add vite-plugin-dts -D`
10

11
## Core Imports
12

13
```typescript
14
import dts from "vite-plugin-dts";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const dts = require("vite-plugin-dts").default;
21
```
22

23
Named imports:
24

25
```typescript
26
import dts, { editSourceMapDir, type PluginOptions } from "vite-plugin-dts";
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { defineConfig } from "vite";
33
import dts from "vite-plugin-dts";
34

35
export default defineConfig({
36
  build: {
37
    lib: {
38
      entry: "src/index.ts",
39
      name: "MyLib",
40
      formats: ["es"],
41
      fileName: "my-lib"
42
    }
43
  },
44
  plugins: [
45
    dts({
46
      // Generate declaration files to match source structure
47
      outDir: "dist",
48
      // Include all TypeScript files
49
      include: ["src/**/*.ts"],
50
      // Exclude test files
51
      exclude: ["src/**/*.test.ts"]
52
    })
53
  ]
54
});
55
```
56

57
## Architecture
58

59
Vite Plugin DTS is built around several key components:
60

61
- **Core Plugin**: Main `dtsPlugin` function that integrates with Vite's build lifecycle
62
- **TypeScript Compiler Integration**: Uses TypeScript's compiler API for accurate declaration generation
63
- **Built-in Resolvers**: Specialized handlers for Vue, Svelte, and JSON files
64
- **Transform Engine**: Code transformation utilities for alias resolution and import handling
65
- **Rollup Integration**: Optional bundling of declaration files using Microsoft API Extractor
66
- **Source Map Support**: Full source map generation and transformation for debugging
67

68
## Capabilities
69

70
### Plugin Configuration
71

72
Core plugin factory function with comprehensive configuration options for declaration file generation, TypeScript compilation, and build integration.
73

74
```typescript { .api }
75
function dts(options?: PluginOptions): import('vite').Plugin;
76

77
interface PluginOptions {
78
  root?: string;
79
  outDir?: string | string[];
80
  entryRoot?: string;
81
  strictOutput?: boolean;
82
  compilerOptions?: ts.CompilerOptions | null;
83
  tsconfigPath?: string;
84
  resolvers?: Resolver[];
85
  pathsToAliases?: boolean;
86
  aliasesExclude?: (string | RegExp)[];
87
  cleanVueFileName?: boolean;
88
  staticImport?: boolean;
89
  include?: string | string[];
90
  exclude?: string | string[];
91
  clearPureImport?: boolean;
92
  insertTypesEntry?: boolean;
93
  rollupTypes?: boolean;
94
  bundledPackages?: string[];
95
  rollupConfig?: RollupConfig;
96
  rollupOptions?: IExtractorInvokeOptions;
97
  copyDtsFiles?: boolean;
98
  declarationOnly?: boolean;
99
  logLevel?: LogLevel;
100
  afterDiagnostic?: (diagnostics: readonly ts.Diagnostic[]) => MaybePromise<void>;
101
  beforeWriteFile?: (filePath: string, content: string) => MaybePromise<void | false | { filePath?: string; content?: string }>;
102
  afterRollup?: (result: ExtractorResult) => MaybePromise<void>;
103
  afterBuild?: (emittedFiles: Map<string, string>) => MaybePromise<void>;
104
}
105
```
106

107
[Plugin Configuration](./plugin-configuration.md)
108

109
### Utility Functions
110

111
Source map manipulation and path handling utilities for advanced declaration file processing.
112

113
```typescript { .api }
114
function editSourceMapDir(content: string, fromDir: string, toDir: string): string | boolean;
115
```
116

117
[Utility Functions](./utility-functions.md)
118

119
### Custom Resolvers
120

121
Extensible resolver system for handling non-standard file types during declaration generation.
122

123
```typescript { .api }
124
interface Resolver {
125
  name: string;
126
  supports: (id: string) => void | boolean;
127
  transform: (payload: {
128
    id: string;
129
    code: string;
130
    root: string;
131
    outDir: string;
132
    host: ts.CompilerHost;
133
    program: ts.Program;
134
  }) => MaybePromise<
135
    | { outputs: { path: string; content: string }[]; emitSkipped?: boolean; diagnostics?: readonly ts.Diagnostic[] }
136
    | { path: string; content: string }[]
137
  >;
138
}
139
```
140

141
[Custom Resolvers](./custom-resolvers.md)
142

143
### Built-in Resolvers
144

145
Pre-configured resolvers for common file types including JSON, Vue SFC, and Svelte components. These are automatically included in the plugin and do not need to be imported separately.
146

147
```typescript { .api }
148
// Built-in resolvers are automatically included:
149
// - JSON file resolver for .json files
150
// - Vue SFC resolver for .vue files  
151
// - Svelte component resolver for .svelte files
152
```
153

154
[Built-in Resolvers](./built-in-resolvers.md)
155

156
### Declaration Bundling
157

158
Bundle multiple declaration files into single files using Microsoft API Extractor.
159

160
```typescript { .api }
161
function rollupDeclarationFiles(options: BundleOptions): ExtractorResult;
162

163
interface BundleOptions {
164
  root: string;
165
  configPath?: string;
166
  compilerOptions: Record<string, any>;
167
  outDir: string;
168
  entryPath: string;
169
  fileName: string;
170
  libFolder?: string;
171
  rollupConfig?: RollupConfig;
172
  rollupOptions?: IExtractorInvokeOptions;
173
}
174
```
175

176
## Types
177

178
```typescript { .api }
179
type MaybePromise<T> = T | Promise<T>;
180

181
type RollupConfig = Omit<
182
  IExtractorConfigPrepareOptions['configObject'],
183
  'projectFolder' | 'mainEntryPointFilePath' | 'compiler' | 'dtsRollup'
184
>;
185

186
interface BundleOptions {
187
  root: string;
188
  configPath?: string;
189
  compilerOptions: Record<string, any>;
190
  outDir: string;
191
  entryPath: string;
192
  fileName: string;
193
  libFolder?: string;
194
  rollupConfig?: RollupConfig;
195
  rollupOptions?: IExtractorInvokeOptions;
196
}
197

198
function rollupDeclarationFiles(options: BundleOptions): ExtractorResult;
199

200
// External types from dependencies
201
interface ExtractorResult {
202
  succeeded: boolean;
203
  errorCount: number;
204
  warningCount: number;
205
}
206

207
interface IExtractorInvokeOptions {
208
  localBuild?: boolean;
209
  showVerboseMessages?: boolean;
210
  showDiagnostics?: boolean;
211
  typescriptCompilerFolder?: string;
212
}
213

214
interface IExtractorConfigPrepareOptions {
215
  configObject: any;
216
}
217

218
type LogLevel = 'info' | 'warn' | 'error' | 'silent';
219
```