0
# Parcel TypeScript Types Transformer
1
2
A Parcel transformer plugin that processes TypeScript files to generate optimized TypeScript declaration files (.d.ts). The transformer uses the TypeScript compiler API to build module dependency graphs, perform tree-shaking on type definitions, and generate minimal declaration files with only necessary type information.
3
4
## Package Information
5
6
- **Package Name**: @parcel/transformer-typescript-types
7
- **Package Type**: npm
8
- **Language**: JavaScript with Flow type annotations
9
- **Installation**: `npm install @parcel/transformer-typescript-types`
10
- **Node.js**: >= 16.0.0
11
- **Peer Dependencies**: TypeScript >= 3.0.0
12
13
## Core Imports
14
15
```javascript
16
// This is a Parcel plugin - import and usage is handled by Parcel's plugin system
17
// Direct usage typically occurs through Parcel configuration or programmatic API
18
const TSTypesTransformer = require("@parcel/transformer-typescript-types");
19
```
20
21
For TypeScript:
22
23
```typescript
24
import TSTypesTransformer from "@parcel/transformer-typescript-types";
25
```
26
27
## Basic Usage
28
29
This transformer is designed to be used within the Parcel build system as a plugin. It cannot be used standalone and requires integration with Parcel's plugin architecture.
30
31
```javascript
32
// Parcel automatically loads and uses this transformer for TypeScript files
33
// when configured in .parcelrc or package.json
34
35
// Example .parcelrc configuration for declaration generation
36
{
37
"extends": "@parcel/config-default",
38
"transformers": {
39
"*.ts": ["@parcel/transformer-typescript-types"],
40
"*.tsx": ["@parcel/transformer-typescript-types"]
41
}
42
}
43
44
// Alternative package.json configuration
45
{
46
"name": "my-package",
47
"@parcel/transformer-typescript-types": {
48
"validateTS": true,
49
"isolatedModules": false
50
},
51
"targets": {
52
"types": {
53
"source": "src/index.ts",
54
"distDir": "dist",
55
"includeNodeModules": false
56
}
57
}
58
}
59
60
// Programmatic usage with Parcel API
61
import { Parcel } from '@parcel/core';
62
63
const bundler = new Parcel({
64
entries: 'src/index.ts',
65
defaultConfig: '@parcel/config-default',
66
targets: {
67
types: {
68
distDir: 'types',
69
includeNodeModules: false
70
}
71
}
72
});
73
74
const { bundleGraph } = await bundler.run();
75
```
76
77
## Architecture
78
79
The transformer operates through a two-phase TypeScript compiler transformation process:
80
81
- **Collection Phase**: Builds a complete module dependency graph from TypeScript source files, tracking imports, exports, and local bindings
82
- **Tree-shaking Phase**: Removes unused type definitions and renames symbols to avoid conflicts while preserving necessary type information
83
- **Module Graph System**: Manages dependencies between TypeScript modules for optimal type resolution
84
- **TypeScript Integration**: Uses TypeScript compiler API with custom transforms for advanced AST manipulation
85
- **Source Map Support**: Generates source maps for debugging declaration files
86
87
## Capabilities
88
89
### TypeScript Transformer
90
91
Main transformer that processes TypeScript source files to generate optimized declaration files with tree-shaking and module graph optimization.
92
93
```javascript { .api }
94
/**
95
* Main Parcel transformer instance for processing TypeScript files
96
*/
97
const TSTypesTransformer: {
98
loadConfig(config: any, options: any): Promise<any>;
99
transform(asset: any, config: any, options: any, logger: any): Promise<any[]>;
100
};
101
```
102
103
[TypeScript Transformer](./transformer.md)
104
105
### Module Graph Management
106
107
System for tracking and managing dependencies between TypeScript modules, enabling efficient tree-shaking and symbol resolution.
108
109
```javascript { .api }
110
/**
111
* Manages dependency graph between TypeScript modules
112
*/
113
class TSModuleGraph {
114
constructor(mainModuleName: string);
115
addModule(name: string, module: TSModule): void;
116
getModule(name: string): TSModule | null;
117
markUsed(module: TSModule, name: string, context: any): void;
118
propagate(context: any): Map<string, TSModule>;
119
}
120
121
/**
122
* Represents a single TypeScript module with imports, exports, and bindings
123
*/
124
class TSModule {
125
constructor();
126
addImport(local: string, specifier: string, imported: string): void;
127
addExport(name: string, imported: string, specifier?: string): void;
128
addLocal(name: string, node: any): void;
129
getName(name: string): string;
130
hasBinding(name: string): boolean;
131
}
132
```
133
134
[Module Graph](./module-graph.md)
135
136
### AST Processing
137
138
TypeScript compiler transforms for collecting module information and performing tree-shaking operations.
139
140
```javascript { .api }
141
/**
142
* Collects module graph information from TypeScript AST
143
*/
144
function collect(
145
moduleGraph: TSModuleGraph,
146
context: any,
147
sourceFile: any
148
): any;
149
150
/**
151
* Performs tree-shaking and symbol renaming on TypeScript AST
152
*/
153
function shake(
154
moduleGraph: TSModuleGraph,
155
context: any,
156
sourceFile: any
157
): any;
158
```
159
160
[AST Processing](./ast-processing.md)
161
162
### TypeScript Version Compatibility
163
164
Cross-version compatibility wrappers for TypeScript compiler API functions, ensuring consistent behavior across different TypeScript versions.
165
166
```javascript { .api }
167
/**
168
* Cross-version wrapper for creating import clauses
169
*/
170
function createImportClause(
171
factory: any,
172
isTypeOnly: boolean,
173
name: any,
174
namedBindings: any
175
): any;
176
177
/**
178
* Cross-version wrapper for creating import declarations
179
*/
180
function createImportDeclaration(
181
factory: any,
182
modifiers: any,
183
importClause: any,
184
moduleSpecifier: any,
185
assertClause: any
186
): any;
187
```
188
189
[TypeScript Compatibility](./ts-compatibility.md)
190
191
## Types
192
193
```javascript { .api }
194
/**
195
* Represents an import statement in a TypeScript module
196
*/
197
type Import = {
198
specifier: string; // Module path (e.g., './components', 'react')
199
imported: string; // Imported symbol name ('default', '*', or named export)
200
};
201
202
/**
203
* Represents an export statement in a TypeScript module
204
* Either a named export (possibly re-exported) or a wildcard export
205
*/
206
type Export =
207
| {
208
name: string; // Export name in current module
209
imported: string; // Symbol name being exported
210
specifier?: string; // Re-export source module (optional)
211
}
212
| {
213
specifier: string; // Wildcard export source (export * from 'module')
214
};
215
216
/**
217
* TypeScript transform context provided by the compiler
218
* Contains factory methods and compilation state
219
*/
220
interface TransformContext {
221
factory?: any; // TypeScript node factory (TS 4.0+)
222
suspendLexicalEnvironment?(): void; // Suspend lexical tracking
223
resumeLexicalEnvironment?(): void; // Resume lexical tracking
224
getCompilerOptions(): any; // Get compiler configuration
225
[key: string]: any; // Additional context properties
226
}
227
228
/**
229
* TypeScript AST node types commonly used by the transformer
230
*/
231
interface TypeScriptASTNodes {
232
SourceFile: any; // Root AST node for a TypeScript file
233
ImportDeclaration: any; // import statement
234
ExportDeclaration: any; // export statement
235
ImportClause: any; // import clause with bindings
236
ImportSpecifier: any; // named import specifier
237
ModuleDeclaration: any; // module or namespace declaration
238
FunctionDeclaration: any; // function declaration
239
ClassDeclaration: any; // class declaration
240
InterfaceDeclaration: any; // interface declaration
241
TypeAliasDeclaration: any; // type alias declaration
242
EnumDeclaration: any; // enum declaration
243
VariableStatement: any; // variable statement (const, let, var)
244
ImportTypeNode: any; // import() type node
245
QualifiedName: any; // qualified name (namespace.Type)
246
Identifier: any; // identifier node
247
}
248
249
/**
250
* Diagnostic information for TypeScript compilation errors
251
*/
252
interface TypeScriptDiagnostic {
253
messageText: string | any; // Error message or message chain
254
file?: any; // Source file with error
255
start?: number; // Error start position
256
length?: number; // Error length
257
source?: string; // Source code text
258
}
259
```