1
# Compiler
2

3
Complete compilation pipeline for transforming Svelte components into optimized JavaScript with preprocessing support.
4

5
## Capabilities
6

7
### Component Compilation
8

9
Transform Svelte component source code into optimized JavaScript modules.
10

11
```javascript { .api }
12
/**
13
 * Compiles a Svelte component into JavaScript
14
 * @param source - Svelte component source code
15
 * @param options - Compilation options
16
 * @returns Compilation result with generated code and metadata
17
 */
18
function compile(source: string, options?: CompileOptions): CompileResult;
19

20
interface CompileOptions {
21
  /** Component name (inferred from filename if not provided) */
22
  name?: string;
23
  /** Source filename for debugging and sourcemaps */
24
  filename?: string;
25
  /** Generation target: 'dom', 'ssr', or false */
26
  generate?: 'dom' | 'ssr' | false;
27
  /** Error handling mode: 'throw' or 'warn' */
28
  errorMode?: 'throw' | 'warn';
29
  /** Variables report mode: 'strict', 'full', or false */
30
  varsReport?: 'full' | 'strict' | false;
31
  /** Enable sourcemap generation */
32
  enableSourcemap?: boolean | { js: boolean; css: boolean };
33
  /** Development mode with runtime checks */
34
  dev?: boolean;
35
  /** Generate accessors for props */
36
  accessors?: boolean;
37
  /** Treat objects as immutable */
38
  immutable?: boolean;
39
  /** Enable hydration support */
40
  hydratable?: boolean;
41
  /** Generate legacy-compatible code */
42
  legacy?: boolean;
43
  /** Generate custom element constructor */
44
  customElement?: boolean;
45
  /** Custom element tag name */
46
  tag?: string;
47
  /** CSS handling: 'injected', 'external', 'none' */
48
  css?: 'injected' | 'external' | 'none' | boolean;
49
  /** Preserve HTML comments in SSR */
50
  preserveComments?: boolean;
51
  /** Preserve whitespace */
52
  preserveWhitespace?: boolean;
53
}
54

55
interface CompileResult {
56
  /** Generated JavaScript code */
57
  js: {
58
    code: string;
59
    map: any;
60
  };
61
  /** Generated CSS code */
62
  css: {
63
    code: string;
64
    map: SourceMap;
65
  };
66
  /** Abstract syntax tree */
67
  ast: Ast;
68
  /** Compilation warnings */
69
  warnings: Warning[];
70
  /** Variable declarations */
71
  vars: Var[];
72
  /** Performance statistics */
73
  stats: {
74
    timings: { total: number };
75
  };
76
}
77
```
78

79
**Usage Examples:**
80

81
```javascript
82
import { compile } from "svelte/compiler";
83

84
// Basic compilation
85
const source = `
86
<script>
87
  export let name = 'world';
88
</script>
89

90
<h1>Hello {name}!</h1>
91
`;
92

93
const result = compile(source, {
94
  filename: 'Hello.svelte',
95
  dev: true
96
});
97

98
console.log(result.js.code); // Generated JavaScript
99
console.log(result.css.code); // Generated CSS
100
console.log(result.warnings); // Any warnings
101

102
// SSR compilation
103
const ssrResult = compile(source, {
104
  generate: 'ssr',
105
  hydratable: true
106
});
107

108
// Custom element compilation
109
const customElementResult = compile(source, {
110
  customElement: true,
111
  tag: 'hello-component'
112
});
113
```
114

115
### AST Parsing
116

117
Parse Svelte component templates into abstract syntax trees for analysis and transformation.
118

119
```javascript { .api }
120
/**
121
 * Parses a Svelte component into an AST without compilation
122
 * @param template - Svelte component source
123
 * @param options - Parser options
124
 * @returns Abstract syntax tree
125
 */
126
function parse(template: string, options?: ParserOptions): Ast;
127

128
interface ParserOptions {
129
  /** Source filename */
130
  filename?: string;
131
  /** Parse as custom element */
132
  customElement?: boolean;
133
  /** CSS mode for parsing */
134
  css?: 'injected' | 'external' | 'none' | boolean;
135
}
136

137
interface Ast {
138
  /** HTML template AST */
139
  html: TemplateNode;
140
  /** CSS style block AST */
141
  css?: Style;
142
  /** Instance script AST */
143
  instance?: Script;
144
  /** Module script AST */
145
  module?: Script;
146
}
147
```
148

149
**Usage Examples:**
150

151
```javascript
152
import { parse } from "svelte/compiler";
153

154
const template = `
155
<script>
156
  let count = 0;
157
</script>
158

159
<button on:click={() => count++}>
160
  Count: {count}
161
</button>
162

163
<style>
164
  button { color: blue; }
165
</style>
166
`;
167

168
const ast = parse(template, {
169
  filename: 'Counter.svelte'
170
});
171

172
console.log(ast.html); // Template nodes
173
console.log(ast.instance); // Script block
174
console.log(ast.css); // Style block
175
```
176

177
### Preprocessing
178

179
Transform component source code before compilation using custom preprocessors.
180

181
```javascript { .api }
182
/**
183
 * Applies preprocessors to transform component source
184
 * @param source - Original component source
185
 * @param preprocessor - Preprocessor configuration
186
 * @param options - Processing options
187
 * @returns Processed source code
188
 */
189
function preprocess(
190
  source: string, 
191
  preprocessor: PreprocessorGroup | PreprocessorGroup[], 
192
  options?: { filename?: string }
193
): Promise<Processed>;
194

195
interface PreprocessorGroup {
196
  /** Preprocessor name */
197
  name?: string;
198
  /** Markup preprocessor */
199
  markup?: MarkupPreprocessor;
200
  /** Style preprocessor */
201
  style?: Preprocessor;
202
  /** Script preprocessor */
203
  script?: Preprocessor;
204
}
205

206
type MarkupPreprocessor = (options: {
207
  content: string;
208
  filename?: string;
209
}) => Processed | void | Promise<Processed | void>;
210

211
type Preprocessor = (options: {
212
  content: string;
213
  attributes: Record<string, string | boolean>;
214
  markup: string;
215
  filename?: string;
216
}) => Processed | void | Promise<Processed | void>;
217

218
interface Processed {
219
  /** Transformed code */
220
  code: string;
221
  /** Source map */
222
  map?: string | object;
223
  /** Additional dependencies to watch */
224
  dependencies?: string[];
225
  /** Updated attributes */
226
  attributes?: Record<string, string | boolean>;
227
}
228
```
229

230
**Usage Examples:**
231

232
```javascript
233
import { preprocess } from "svelte/compiler";
234

235
// TypeScript preprocessing
236
const preprocessors = {
237
  script: ({ content, attributes }) => {
238
    if (attributes.lang === 'ts') {
239
      // Transform TypeScript to JavaScript
240
      return {
241
        code: transformTypeScript(content),
242
        map: generateSourceMap()
243
      };
244
    }
245
  },
246
  style: ({ content, attributes }) => {
247
    if (attributes.lang === 'scss') {
248
      // Transform SCSS to CSS
249
      return {
250
        code: compileSass(content)
251
      };
252
    }
253
  }
254
};
255

256
const processed = await preprocess(source, preprocessors, {
257
  filename: 'Component.svelte'
258
});
259

260
console.log(processed.code); // Transformed source
261
```
262

263
### AST Traversal
264

265
Utility for walking and analyzing AST nodes.
266

267
```javascript { .api }
268
/**
269
 * Walk an AST with enter/leave callbacks
270
 * @param ast - AST node to traverse
271
 * @param handlers - Enter and leave callback functions
272
 */
273
function walk(ast: Node, handlers: {
274
  enter?: (node: Node, parent: Node, prop: string, index: number) => void;
275
  leave?: (node: Node, parent: Node, prop: string, index: number) => void;
276
}): void;
277
```
278

279
**Usage Examples:**
280

281
```javascript
282
import { parse, walk } from "svelte/compiler";
283

284
const ast = parse(template);
285

286
// Find all variable references
287
const variables = [];
288

289
walk(ast.html, {
290
  enter(node) {
291
    if (node.type === 'Identifier') {
292
      variables.push(node.name);
293
    }
294
  }
295
});
296

297
console.log('Variables used:', variables);
298
```
299

300
### Version Information
301

302
```javascript { .api }
303
/**
304
 * Current Svelte version
305
 */
306
const VERSION: string;
307
```
308

309
## AST Node Types
310

311
```javascript { .api }
312
interface TemplateNode {
313
  start: number;
314
  end: number;
315
  type: string;
316
  children?: TemplateNode[];
317
}
318

319
interface Element extends TemplateNode {
320
  type: 'Element' | 'InlineComponent' | 'SlotTemplate' | 'Title' | 'Slot' | 'Head' | 'Options' | 'Window' | 'Document' | 'Body';
321
  name: string;
322
  attributes: Array<Attribute | SpreadAttribute | Directive>;
323
}
324

325
interface Text extends TemplateNode {
326
  type: 'Text';
327
  data: string;
328
}
329

330
interface MustacheTag extends TemplateNode {
331
  type: 'MustacheTag' | 'RawMustacheTag';
332
  expression: Node;
333
}
334

335
interface Script extends TemplateNode {
336
  type: 'Script';
337
  context: string;
338
  content: Program;
339
}
340

341
interface Style extends TemplateNode {
342
  type: 'Style';
343
  attributes: any[];
344
  children: any[];
345
  content: {
346
    start: number;
347
    end: number;
348
    styles: string;
349
  };
350
}
351

352
interface Warning {
353
  start?: { line: number; column: number; pos?: number };
354
  end?: { line: number; column: number };
355
  pos?: number;
356
  code: string;
357
  message: string;
358
  filename?: string;
359
  frame?: string;
360
  toString(): string;
361
}
362

363
interface Var {
364
  name: string;
365
  export_name?: string;
366
  injected?: boolean;
367
  module?: boolean;
368
  mutated?: boolean;
369
  reassigned?: boolean;
370
  referenced?: boolean;
371
  writable?: boolean;
372
}
373
```