0
# Parcel TypeScript TSC Transformer
1

2
A Parcel transformer plugin that uses the TypeScript compiler API (tsc) to transpile TypeScript code to JavaScript. It integrates with Parcel's plugin architecture to handle TypeScript files (.ts, .tsx) during the build process, offering TypeScript compilation with source map support, configurable compiler options through tsconfig.json, and seamless integration with Parcel's asset pipeline.
3

4
## Package Information
5

6
- **Package Name**: @parcel/transformer-typescript-tsc
7
- **Package Type**: npm
8
- **Language**: JavaScript with Flow types (handles TypeScript files)
9
- **Installation**: This is a Parcel plugin, install via: `npm install @parcel/transformer-typescript-tsc`
10
- **Node Version**: >= 16.0.0
11
- **Parcel Version**: ^2.15.4
12

13
## Core Imports
14

15
This package is used as a Parcel plugin and is not typically imported directly in user code. It's configured through Parcel's `.parcelrc` configuration file:
16

17
```json
18
{
19
  "extends": "@parcel/config-default",
20
  "transformers": {
21
    "*.{ts,tsx}": ["@parcel/transformer-typescript-tsc"]
22
  }
23
}
24
```
25

26
For plugin development or advanced usage:
27

28
```javascript
29
import TSCTransformer from "@parcel/transformer-typescript-tsc";
30
```
31

32
## Basic Usage
33

34
Configure the transformer in your `.parcelrc` file to handle TypeScript files:
35

36
```json
37
{
38
  "extends": "@parcel/config-default",
39
  "transformers": {
40
    "*.{ts,tsx}": ["@parcel/transformer-typescript-tsc"]
41
  }
42
}
43
```
44

45
TypeScript configuration via `tsconfig.json`:
46

47
```json
48
{
49
  "compilerOptions": {
50
    "target": "es2020",
51
    "module": "esnext",
52
    "jsx": "react",
53
    "strict": true,
54
    "esModuleInterop": true,
55
    "skipLibCheck": true,
56
    "forceConsistentCasingInFileNames": true
57
  },
58
  "include": ["src/**/*"],
59
  "exclude": ["node_modules"]
60
}
61
```
62

63
The transformer will automatically:
64
- Transpile `.ts` and `.tsx` files to JavaScript
65
- Generate source maps when enabled
66
- Respect TypeScript configuration from `tsconfig.json`
67
- Handle JSX compilation (React by default)
68
- Preserve ES modules for Parcel's scope hoisting
69

70
## Architecture
71

72
The transformer is built as a Parcel plugin using Parcel's transformer architecture:
73

74
- **Plugin Interface**: Creates new Transformer instance with object literal containing loadConfig and transform functions
75
- **Configuration Loading**: Uses `@parcel/ts-utils.loadTSConfig` for TypeScript configuration
76
- **Compilation Engine**: TypeScript compiler API (`typescript.transpileModule`)
77
- **Source Map Integration**: `@parcel/source-map` for source map handling and VLQ map processing
78
- **Asset Pipeline**: Integrates with Parcel's asset transformation pipeline
79
- **Flow Types**: Source code uses Flow type annotations (`// @flow strict-local`)
80

81
## Capabilities
82

83
### TypeScript Compilation
84

85
Transpiles TypeScript source code to JavaScript using the official TypeScript compiler API.
86

87
```javascript { .api }
88
/**
89
 * Default export: Pre-configured Transformer instance created with new Transformer()
90
 * Contains loadConfig and transform function implementations
91
 */
92
export default Transformer;
93

94
/**
95
 * Transformer instance created with object literal containing:
96
 */
97
interface TransformerInstance {
98
  loadConfig({config, options}): Promise<TSConfig>;
99
  transform({asset, config, options}): Promise<Asset[]>;
100
}
101

102
interface LoadConfigParams {
103
  config: ConfigFile;
104
  options: ParcelOptions;
105
}
106

107
interface TransformParams {
108
  asset: Asset;
109
  config: TSConfig;
110
  options: ParcelOptions;
111
}
112
```
113

114
### Configuration Loading
115

116
Loads and processes TypeScript configuration from `tsconfig.json` files.
117

118
```javascript { .api }
119
/**
120
 * Loads TypeScript configuration using @parcel/ts-utils.loadTSConfig
121
 * @param config - Parcel config object  
122
 * @param options - Parcel options object
123
 * @returns Processed TypeScript compiler options
124
 */
125
loadConfig({config, options}): Promise<TSConfig>;
126
```
127

128
### Code Transformation
129

130
Transforms TypeScript code to JavaScript with source map support.
131

132
```javascript { .api }
133
/**
134
 * Transforms TypeScript asset to JavaScript using typescript.transpileModule
135
 * The implementation:
136
 * 1. Gets code and source map from asset
137
 * 2. Calls typescript.transpileModule with merged compiler options
138
 * 3. Processes source maps and extends with original map if present
139
 * 4. Sets asset type to 'js' and returns the modified asset
140
 * @param asset - Input TypeScript asset
141
 * @param config - TypeScript compiler configuration from loadConfig
142
 * @param options - Parcel build options
143
 * @returns Array containing single transformed JavaScript asset
144
 */
145
transform({asset, config, options}): Promise<Asset[]>;
146
```
147

148
## TypeScript Compiler Configuration
149

150
The transformer supports all standard TypeScript compiler options through `tsconfig.json`, with specific defaults:
151

152
### Default Compiler Options
153

154
```javascript { .api }
155
/**
156
 * Compiler options merged in transform() method:
157
 * User config is spread first, then these options override/ensure correct behavior
158
 */
159
interface AppliedCompilerOptions {
160
  jsx: typescript.JsxEmit.React;           // React JSX compilation (default, user can override via tsconfig)
161
  noEmit: false;                           // Always emit output (forced)
162
  module: typescript.ModuleKind.ESNext;    // Preserve ES modules for scope hoisting (forced)
163
  sourceMap: boolean;                      // Based on asset.env.sourceMap (forced)
164
  mapRoot: string;                         // Set to options.projectRoot (forced)
165
}
166

167
/**
168
 * TranspileOptions passed to typescript.transpileModule
169
 */
170
interface TranspileOptions {
171
  compilerOptions: AppliedCompilerOptions;
172
  fileName: string;                        // Set to asset.filePath
173
}
174
```
175

176
### Supported File Types
177

178
- **`.ts`**: TypeScript files
179
- **`.tsx`**: TypeScript files with JSX
180

181
### Output
182

183
- **File type**: JavaScript (`.js`)
184
- **Module format**: ES modules (preserved for scope hoisting)
185
- **Source maps**: Generated when enabled in Parcel environment
186
- **JSX**: Compiled to React.createElement calls by default
187

188
## Error Handling
189

190
The transformer integrates with Parcel's error handling system:
191

192
- TypeScript compilation errors are reported through Parcel's diagnostic system
193
- Configuration errors from invalid `tsconfig.json` are properly surfaced
194
- Source map generation errors are handled gracefully
195

196
## Dependencies
197

198
### Required Dependencies
199

200
```javascript { .api }
201
// Flow type import (source uses Flow types)
202
import type {TranspileOptions} from 'typescript';
203

204
// Core Parcel plugin system
205
import {Transformer} from '@parcel/plugin';
206

207
// TypeScript configuration utilities
208
import {loadTSConfig} from '@parcel/ts-utils';  
209

210
// TypeScript compiler API
211
import typescript from 'typescript';
212

213
// Source map handling
214
import SourceMap from '@parcel/source-map';
215
```
216

217
### Peer Dependencies
218

219
- **typescript**: `>=3.0.0` - Must be installed by the user
220

221
## Advanced Usage
222

223
### Custom TypeScript Configuration
224

225
Override default compiler options via `tsconfig.json`:
226

227
```json
228
{
229
  "compilerOptions": {
230
    "jsx": "react-jsx",
231
    "target": "es2022", 
232
    "strict": true,
233
    "experimentalDecorators": true,
234
    "emitDecoratorMetadata": true
235
  }
236
}
237
```
238

239
### Source Map Configuration
240

241
Source maps are automatically generated based on Parcel's environment settings:
242

243
```javascript
244
// Source maps enabled in development
245
process.env.NODE_ENV === 'development'
246

247
// Controlled via Parcel CLI
248
parcel build --no-source-maps
249
```
250

251
## Type Definitions
252

253
```javascript { .api }
254
// Complete type definitions used by the transformer
255

256
// From TypeScript compiler API (imported as Flow type)
257
interface TranspileOptions {
258
  compilerOptions?: CompilerOptions;
259
  fileName?: string;
260
  reportDiagnostics?: boolean;
261
  moduleName?: string;
262
  renamedDependencies?: MapLike<string>;
263
}
264

265
interface TranspileOutput {
266
  outputText: string;
267
  diagnostics?: Diagnostic[];
268
  sourceMapText?: string;
269
}
270

271
interface CompilerOptions {
272
  jsx?: JsxEmit;
273
  noEmit?: boolean;
274
  module?: ModuleKind;
275
  sourceMap?: boolean;
276
  mapRoot?: string;
277
  target?: ScriptTarget;
278
  strict?: boolean;
279
  // ... plus all other TypeScript compiler options
280
}
281

282
// Asset interface from Parcel plugin system
283
interface Asset {
284
  getCode(): Promise<string>;
285
  getMap(): Promise<SourceMap | null>;
286
  setCode(code: string): void;  
287
  setMap(map: SourceMap): void;
288
  type: string;
289
  filePath: string;
290
  env: Environment;
291
}
292

293
interface Environment {
294
  sourceMap: boolean;
295
}
296

297
interface ParcelOptions {
298
  projectRoot: string;
299
}
300

301
interface ConfigFile {
302
  // Parcel config file interface
303
}
304

305
interface TSConfig {
306
  // TypeScript configuration object returned by loadTSConfig
307
}
308

309
// Constants from TypeScript API
310
enum JsxEmit {
311
  React = 'react'
312
}
313

314
enum ModuleKind {
315
  ESNext = 'esnext'
316
}
317
```