0
# Rollup Plugin DTS
1

2
Rollup Plugin DTS is a Rollup plugin that bundles TypeScript definition files (.d.ts) into consolidated declaration files. It uses the TypeScript compiler API to intelligently process and merge multiple declaration files while preserving type information and module relationships.
3

4
## Package Information
5

6
- **Package Name**: rollup-plugin-dts
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install --save-dev rollup-plugin-dts`
10

11
## Core Imports
12

13
```typescript
14
import { dts } from "rollup-plugin-dts";
15
```
16

17
For legacy support (default import - both exports are identical):
18

19
```typescript
20
import dts from "rollup-plugin-dts";
21
```
22

23
Type-only imports:
24

25
```typescript
26
import type { Options } from "rollup-plugin-dts";
27
```
28

29
CommonJS:
30

31
```javascript
32
const { dts } = require("rollup-plugin-dts");
33
```
34

35
## Basic Usage
36

37
```typescript
38
import { dts } from "rollup-plugin-dts";
39

40
const config = [
41
  // Your regular build configuration
42
  {
43
    input: "src/index.ts",
44
    output: [{ file: "dist/my-library.js", format: "cjs" }],
45
    plugins: [/* other plugins */],
46
  },
47
  // Declaration file bundling configuration
48
  {
49
    input: "./src/index.d.ts", // or generated .d.ts files
50
    output: [{ file: "dist/my-library.d.ts", format: "es" }],
51
    plugins: [dts()],
52
  },
53
];
54

55
export default config;
56
```
57

58
## Capabilities
59

60
### DTS Plugin
61

62
The main plugin function that creates a Rollup plugin for bundling TypeScript declaration files.
63

64
```typescript { .api }
65
/**
66
 * Creates a Rollup plugin that bundles TypeScript declaration files
67
 * @param options - Plugin configuration options
68
 * @returns Rollup plugin instance
69
 */
70
function dts(options?: Options): Plugin;
71
```
72

73
**Usage Examples:**
74

75
```typescript
76
import { dts } from "rollup-plugin-dts";
77

78
// Basic usage with no options
79
export default {
80
  input: "types/index.d.ts",
81
  output: { file: "dist/bundle.d.ts", format: "es" },
82
  plugins: [dts()],
83
};
84

85
// With configuration options
86
export default {
87
  input: "types/index.d.ts", 
88
  output: { file: "dist/bundle.d.ts", format: "es" },
89
  plugins: [
90
    dts({
91
      respectExternal: true,
92
      includeExternal: ["some-types-package"],
93
      compilerOptions: {
94
        baseUrl: "./",
95
        paths: {
96
          "@/*": ["src/*"]
97
        }
98
      },
99
      tsconfig: "./tsconfig.build.json"
100
    })
101
  ],
102
};
103
```
104

105
### Configuration Options
106

107
Plugin configuration interface for customizing bundling behavior.
108

109
```typescript { .api }
110
interface Options {
111
  /**
112
   * Controls external library classification. When true, uses rollup's external
113
   * configuration instead of automatically marking all node_modules as external.
114
   * @default false
115
   */
116
  respectExternal?: boolean;
117
  
118
  /**
119
   * List of external module names to include types from instead of marking as external.
120
   * Useful for bundling specific @types packages or external library types.
121
   * @default []
122
   */
123
  includeExternal?: Array<string>;
124
  
125
  /**
126
   * TypeScript compiler options for path-mapping and module resolution.
127
   * Commonly used for baseUrl and paths configuration.
128
   * @default {}
129
   */
130
  compilerOptions?: ts.CompilerOptions;
131
  
132
  /**
133
   * Path to custom tsconfig.json file for TypeScript configuration.
134
   * By default, will try to load 'tsconfig.json' from the current directory.
135
   */
136
  tsconfig?: string;
137
}
138
```
139

140
**Configuration Examples:**
141

142
```typescript
143
// Path mapping support
144
const config = dts({
145
  compilerOptions: {
146
    baseUrl: "./",
147
    paths: {
148
      "@utils/*": ["src/utils/*"],
149
      "@types/*": ["types/*"]
150
    }
151
  }
152
});
153

154
// Include external types
155
const config = dts({
156
  includeExternal: ["@types/node", "typescript"],
157
  respectExternal: false
158
});
159

160
// Custom tsconfig
161
const config = dts({
162
  tsconfig: "./tsconfig.declarations.json"
163
});
164
```
165

166
## Advanced Usage Patterns
167

168
### Multiple Entry Points
169

170
```typescript
171
// Handle multiple entry points
172
export default {
173
  input: {
174
    main: "types/index.d.ts",
175
    utils: "types/utils.d.ts", 
176
    helpers: "types/helpers.d.ts"
177
  },
178
  output: {
179
    dir: "dist/types",
180
    format: "es"
181
  },
182
  plugins: [dts()],
183
};
184
```
185

186
### Working with Generated Types
187

188
```typescript
189
// Bundle TypeScript-generated declaration files
190
export default [
191
  // First, build your TypeScript source
192
  {
193
    input: "src/index.ts",
194
    output: { file: "dist/index.js", format: "cjs" },
195
    plugins: [typescript({ declaration: true, outDir: "temp" })],
196
  },
197
  // Then bundle the generated .d.ts files
198
  {
199
    input: "temp/index.d.ts",
200
    output: { file: "dist/index.d.ts", format: "es" },
201
    plugins: [dts()],
202
  },
203
];
204
```
205

206
### JSON Module Support
207

208
```typescript
209
// When using resolveJsonModule in TypeScript
210
export default {
211
  input: "src/index.ts",
212
  output: { file: "dist/bundle.d.ts", format: "es" },
213
  plugins: [
214
    dts({
215
      compilerOptions: {
216
        resolveJsonModule: true
217
      }
218
    })
219
  ],
220
};
221
```
222

223
## Key Features
224

225
### Automatic External Handling
226
The plugin automatically marks all external libraries from `node_modules` as external, preventing them from being bundled. This behavior can be controlled with the `respectExternal` option.
227

228
### TypeScript Integration
229
Uses the TypeScript compiler API for:
230
- Intelligent module resolution
231
- Type-aware bundling
232
- Support for TypeScript language features
233
- Proper handling of declaration files
234

235
### Multi-Program Support
236
Creates separate TypeScript programs for different entry points when they have different compiler configurations or are in different directories.
237

238
### Reference Processing
239
Handles TypeScript triple-slash references:
240
- `/// <reference path="..." />` for file references
241
- `/// <reference types="..." />` for type references
242

243
### Namespace Conversion
244
Converts JavaScript-style namespace exports to proper TypeScript namespace declarations in the final output.
245

246
## Error Handling
247

248
The plugin will emit TypeScript compilation errors and halt the build if:
249
- TypeScript compilation fails with errors
250
- Required source files cannot be found
251
- Invalid TypeScript syntax is encountered
252

253
Common errors include:
254
- Missing type dependencies
255
- Circular dependencies in declaration files
256
- Invalid module resolution paths
257
- Incompatible TypeScript compiler options
258

259
## Compatibility
260

261
- **Node.js**: Requires Node.js 16 or higher
262
- **Rollup**: Compatible with Rollup 3.29.4+ and 4.x
263
- **TypeScript**: Supports TypeScript 4.5+ and 5.x
264
- **Module Formats**: Outputs ES module format declaration files