0
# TypeScript Processing
1

2
TypeScript compilation and declaration file generation with support for custom tsconfig files and path alias resolution.
3

4
## Capabilities
5

6
### Emit TypeScript Declarations
7

8
Generates TypeScript declaration files (.d.ts) for the package.
9

10
```typescript { .api }
11
/**
12
 * Generate TypeScript declaration files
13
 * @param input - Input directory path
14
 * @param output - Output directory path for temp files
15
 * @param final_output - Final output directory path
16
 * @param cwd - Current working directory
17
 * @param alias - Path alias mapping
18
 * @param files - Array of files to process
19
 * @param tsconfig - Optional path to tsconfig file
20
 */
21
function emit_dts(
22
  input: string,
23
  output: string,
24
  final_output: string,
25
  cwd: string,
26
  alias: Record<string, string>,
27
  files: File[],
28
  tsconfig?: string
29
): Promise<void>;
30
```
31

32
**Usage Examples:**
33

34
```typescript
35
import { emit_dts } from "@sveltejs/package/src/typescript.js";
36

37
// Generate declaration files
38
await emit_dts(
39
  "src/lib",           // input directory
40
  ".svelte-kit/temp",  // temp output
41
  "dist",              // final output
42
  process.cwd(),       // working directory
43
  { '$lib': 'src/lib' }, // aliases
44
  files,               // file list
45
  "tsconfig.json"      // tsconfig path
46
);
47

48
// Generate without custom tsconfig
49
await emit_dts(
50
  "src/lib",
51
  ".svelte-kit/temp", 
52
  "dist",
53
  process.cwd(),
54
  { '$lib': 'src/lib' },
55
  files
56
);
57
```
58

59
### Transpile TypeScript
60

61
Transpiles TypeScript source code to JavaScript.
62

63
```typescript { .api }
64
/**
65
 * Transpile TypeScript to JavaScript
66
 * @param tsconfig - Path to tsconfig file (optional)
67
 * @param filename - Source file path
68
 * @param source - TypeScript source code
69
 * @returns Promise resolving to transpiled JavaScript
70
 */
71
function transpile_ts(
72
  tsconfig: string | undefined,
73
  filename: string,
74
  source: string
75
): Promise<string>;
76
```
77

78
**Usage Examples:**
79

80
```typescript
81
import { transpile_ts } from "@sveltejs/package/src/typescript.js";
82

83
// Transpile with custom tsconfig
84
const jsCode = await transpile_ts(
85
  "tsconfig.json",
86
  "src/lib/utils.ts",
87
  `
88
  export function add(a: number, b: number): number {
89
    return a + b;
90
  }
91
  `
92
);
93

94
// Transpile with default settings
95
const jsCode = await transpile_ts(
96
  undefined,
97
  "src/lib/helpers.ts",
98
  `
99
  interface User {
100
    name: string;
101
    age: number;
102
  }
103
  
104
  export const createUser = (name: string, age: number): User => ({ name, age });
105
  `
106
);
107
```
108

109
## TypeScript Processing Pipeline
110

111
### Declaration File Generation
112

113
The `emit_dts` function:
114

115
1. **Configuration**: Loads TypeScript configuration from tsconfig
116
2. **Program Creation**: Creates TypeScript compiler program
117
3. **Analysis**: Analyzes source files and their dependencies
118
4. **Generation**: Generates .d.ts files with proper type information
119
5. **Alias Resolution**: Resolves path aliases in generated declarations
120
6. **Output**: Writes declaration files to final output directory
121

122
### Transpilation Process
123

124
The `transpile_ts` function:
125

126
1. **Configuration Loading**: Loads compiler options from tsconfig
127
2. **Source Processing**: Parses TypeScript source code
128
3. **Type Checking**: Performs type checking (optional, based on config)
129
4. **Code Generation**: Generates JavaScript code
130
5. **Source Maps**: Generates source maps if configured
131

132
### Path Alias Resolution
133

134
Both functions support path alias resolution:
135

136
- `$lib` aliases are resolved to the configured library directory
137
- Custom aliases from `kit.alias` configuration are supported
138
- Relative path resolution maintains proper import relationships
139

140
## Configuration Integration
141

142
### TSConfig Support
143

144
The TypeScript processing integrates with tsconfig.json:
145

146
```json
147
{
148
  "compilerOptions": {
149
    "target": "ES2020",
150
    "module": "ESNext",
151
    "moduleResolution": "node",
152
    "declaration": true,
153
    "declarationMap": true,
154
    "sourceMap": true,
155
    "strict": true,
156
    "paths": {
157
      "$lib": ["src/lib"],
158
      "$lib/*": ["src/lib/*"]
159
    }
160
  },
161
  "include": ["src/**/*"],
162
  "exclude": ["**/*.test.ts"]
163
}
164
```
165

166
### Compiler Options
167

168
Key compiler options supported:
169

170
- **Target**: ES version for output JavaScript
171
- **Module**: Module system (ESNext, CommonJS, etc.)
172
- **Declaration**: Generate .d.ts files
173
- **Source Maps**: Generate source map files
174
- **Strict Mode**: TypeScript strict type checking
175
- **Path Mapping**: Path alias resolution
176

177
## Error Handling
178

179
### Compilation Errors
180

181
TypeScript compilation errors are handled gracefully:
182

183
- Syntax errors stop the build process
184
- Type errors can be configured to warn or fail
185
- Missing dependency errors provide helpful messages
186

187
### Configuration Errors
188

189
- Invalid tsconfig files produce clear error messages
190
- Missing tsconfig falls back to default configuration
191
- Path alias errors show resolution attempts
192

193
## Integration with Build Process
194

195
The TypeScript processing integrates with the main build system:
196

197
1. **File Analysis**: Files are analyzed to determine TypeScript processing needs
198
2. **Declaration Generation**: .d.ts files are generated if `types` option is enabled
199
3. **Transpilation**: .ts files are transpiled to .js during file processing
200
4. **Alias Resolution**: Path aliases are resolved in both source and declaration files
201

202
## Types
203

204
```typescript { .api }
205
interface File {
206
  name: string;
207
  dest: string;
208
  base: string;
209
  is_svelte: boolean;
210
}
211
```