0
# TypeScript Processing
1

2
TypeScript compiler integration providing full TypeScript support in Svelte components with configurable compiler options, tsconfig support, and diagnostic reporting.
3

4
## Capabilities
5

6
### TypeScript Preprocessor
7

8
Standalone TypeScript preprocessor that can be used independently or as part of the auto preprocessor.
9

10
```typescript { .api }
11
/**
12
 * Creates a TypeScript preprocessor for script blocks
13
 * @param options - TypeScript compiler configuration
14
 * @returns PreprocessorGroup with script preprocessing
15
 */
16
function typescript(options?: Options.Typescript): PreprocessorGroup;
17

18
namespace Options {
19
  interface Typescript {
20
    /** TypeScript compiler options (overrides tsconfig) */
21
    compilerOptions?: any;
22
    
23
    /** Path to tsconfig.json file or boolean to enable/disable tsconfig loading */
24
    tsconfigFile?: string | boolean;
25
    
26
    /** Directory to search for tsconfig.json (when tsconfigFile is true) */
27
    tsconfigDirectory?: string | boolean;
28
    
29
    /** Enable TypeScript diagnostic reporting */
30
    reportDiagnostics?: boolean;
31
    
32
    /** Content to prepend to TypeScript source */
33
    prependData?: string;
34
    
35
    /** Remove common leading whitespace from source */
36
    stripIndent?: boolean;
37
  }
38
}
39
```
40

41
**Usage Examples:**
42

43
```typescript
44
import { typescript } from "svelte-preprocess";
45

46
// Basic TypeScript support
47
const preprocess = {
48
  script: typescript()
49
};
50

51
// With custom compiler options
52
const preprocess = {
53
  script: typescript({
54
    compilerOptions: {
55
      target: 'es2020', 
56
      module: 'esnext',
57
      strict: true,
58
      skipLibCheck: true
59
    }
60
  })
61
};
62

63
// Using existing tsconfig.json
64
const preprocess = {
65
  script: typescript({
66
    tsconfigFile: './tsconfig.json',
67
    reportDiagnostics: true
68
  })
69
};
70

71
// With prepended data for global types
72
const preprocess = {
73
  script: typescript({
74
    prependData: `
75
      import type { ComponentEvents } from './types/events';
76
      declare global {
77
        namespace App {
78
          interface Locals {
79
            user?: User;
80
          }
81
        }
82
      }
83
    `
84
  })
85
};
86
```
87

88
### Compiler Options
89

90
TypeScript compiler options can be specified directly or loaded from tsconfig.json:
91

92
```typescript
93
// Direct compiler options
94
const preprocess = {
95
  script: typescript({
96
    compilerOptions: {
97
      target: 'es2022',
98
      module: 'esnext',
99
      moduleResolution: 'node',
100
      allowSyntheticDefaultImports: true,
101
      esModuleInterop: true,
102
      skipLibCheck: true,
103
      strict: true,
104
      
105
      // Svelte-specific settings
106
      importsNotUsedAsValues: 'preserve',
107
      preserveValueImports: true
108
    }
109
  })
110
};
111

112
// Load from tsconfig.json
113
const preprocess = {
114
  script: typescript({
115
    tsconfigFile: true, // Search for tsconfig.json in current or parent directories
116
    // or
117
    tsconfigFile: './src/tsconfig.json', // Specific path
118
    
119
    // Optional: override specific options
120
    compilerOptions: {
121
      sourceMap: true
122
    }
123
  })
124
};
125
```
126

127
### Diagnostic Reporting
128

129
Enable TypeScript diagnostic reporting to get compile-time errors:
130

131
```typescript
132
const preprocess = {
133
  script: typescript({
134
    reportDiagnostics: true,
135
    compilerOptions: {
136
      strict: true,
137
      noUnusedLocals: true,
138
      noUnusedParameters: true
139
    }
140
  })
141
};
142
```
143

144
When enabled, TypeScript diagnostics are included in the `Processed` result and can be handled by build tools:
145

146
```typescript
147
// Diagnostics are available in the result
148
interface Processed {
149
  code: string;
150
  map?: string | object;
151
  dependencies?: string[];
152
  diagnostics?: Array<{
153
    category: number;
154
    code: number;
155
    messageText: string;
156
    file?: {
157
      fileName: string;
158
    };
159
    start?: number;
160
    length?: number;
161
  }>;
162
}
163
```
164

165
### Content Preparation
166

167
Control how TypeScript source is prepared before compilation:
168

169
```typescript
170
const preprocess = {
171
  script: typescript({
172
    // Add global declarations
173
    prependData: `
174
      import type { SvelteComponentTyped } from 'svelte';
175
      
176
      declare global {
177
        const __VERSION__: string;
178
        const __DEV__: boolean;
179
      }
180
    `,
181
    
182
    // Normalize indentation
183
    stripIndent: true
184
  })
185
};
186
```
187

188
### Integration with Auto Preprocessor
189

190
TypeScript processing is automatically enabled when using the auto preprocessor:
191

192
```typescript
193
import { sveltePreprocess } from "svelte-preprocess";
194

195
const preprocess = sveltePreprocess({
196
  // Enable with defaults
197
  typescript: true,
198
  
199
  // Or with custom options
200
  typescript: {
201
    tsconfigFile: './tsconfig.json',
202
    compilerOptions: {
203
      target: 'es2020'
204
    }
205
  }
206
});
207
```
208

209
The auto preprocessor automatically detects TypeScript in:
210
- `<script lang="ts">` 
211
- `<script lang="typescript">`
212
- External `.ts` files
213

214
### Advanced Configuration
215

216
```typescript
217
// Complete configuration example
218
const preprocess = {
219
  script: typescript({
220
    // TypeScript configuration
221
    tsconfigFile: './tsconfig.json',
222
    reportDiagnostics: true,
223
    
224
    // Source preparation
225
    prependData: `
226
      // Global type declarations
227
      import type { UserSession } from '$lib/types';
228
      
229
      declare global {
230
        const $session: UserSession;
231
      }
232
    `,
233
    stripIndent: true,
234
    
235
    // Compiler overrides
236
    compilerOptions: {
237
      // Enable source maps for development
238
      sourceMap: process.env.NODE_ENV === 'development',
239
      
240
      // Svelte-optimized settings
241
      importsNotUsedAsValues: 'preserve',
242
      isolatedModules: true
243
    }
244
  })
245
};
246
```
247

248
## Configuration Patterns
249

250
### Development vs Production
251

252
```typescript
253
const isDev = process.env.NODE_ENV === 'development';
254

255
const preprocess = {
256
  script: typescript({
257
    compilerOptions: {
258
      // Enable source maps in development
259
      sourceMap: isDev,
260
      
261
      // More aggressive optimization in production
262
      target: isDev ? 'es2020' : 'es2018',
263
      
264
      // Strict checking in development
265
      strict: isDev,
266
      noUnusedLocals: isDev,
267
      noUnusedParameters: isDev
268
    },
269
    
270
    // Report diagnostics in development
271
    reportDiagnostics: isDev
272
  })
273
};
274
```
275

276
### Monorepo Setup
277

278
```typescript
279
// For packages in a monorepo
280
const preprocess = {
281
  script: typescript({
282
    tsconfigFile: './packages/ui/tsconfig.json',
283
    tsconfigDirectory: './packages/ui',
284
    
285
    compilerOptions: {
286
      // Reference other packages
287
      baseUrl: '../../',
288
      paths: {
289
        '@packages/*': ['packages/*/src']
290
      }
291
    }
292
  })
293
};
294
```
295

296
## Types
297

298
```typescript { .api }
299
interface TypescriptOptions {
300
  /** TypeScript compiler options */
301
  compilerOptions?: import('typescript').CompilerOptions;
302
  
303
  /** Path to tsconfig.json or boolean to enable auto-discovery */
304
  tsconfigFile?: string | boolean;
305
  
306
  /** Directory to search for tsconfig.json */
307
  tsconfigDirectory?: string | boolean;
308
  
309
  /** Enable diagnostic reporting */
310
  reportDiagnostics?: boolean;
311
  
312
  /** Content to prepend to source */
313
  prependData?: string;
314
  
315
  /** Remove leading whitespace */
316
  stripIndent?: boolean;
317
}
318
```