Skip to main content

Compiler and API

svelte/compiler

Edit this page on GitHub

Typically, you won't interact with the Svelte compiler directly, but will instead integrate it into your build system using a bundler plugin. The bundler plugin that the Svelte team most recommends and invests in is vite-plugin-svelte. The SvelteKit framework provides a setup leveraging vite-plugin-svelte to build applications as well as a tool for packaging Svelte component libraries. Svelte Society maintains a list of other bundler plugins for additional tools like Rollup and Webpack.

Nonetheless, it's useful to understand how to use the compiler, since bundler plugins generally expose compiler options to you.

compile

ts
function compile(
source: string,
options?: CompileOptions
): CompileResult;

This is where the magic happens. svelte.compile takes your component source code, and turns it into a JavaScript module that exports a class.

ts
import { compile } from 'svelte/compiler';
const result = compile(source, {
// options
});

Refer to CompileOptions for all the available options.

The returned result object contains the code for your component, along with useful bits of metadata.

ts
const { js, css, ast, warnings, vars, stats } = compile(source);

Refer to CompileResult for a full description of the compile result.

parse

ts
function parse(
template: string,
options?: ParserOptions
): Ast;

The parse function parses a component, returning only its abstract syntax tree. Unlike compiling with the generate: false option, this will not perform any validation or other analysis of the component beyond parsing it. Note that the returned AST is not considered public API, so breaking changes could occur at any point in time.

ts
import { parse } from 'svelte/compiler';
const ast = parse(source, { filename: 'App.svelte' });

preprocess

ts
function preprocess(
source: string,
preprocessor: PreprocessorGroup | PreprocessorGroup[],
options?:
| {
filename?: string | undefined;
}
| undefined
): Promise<Processed>;

A number of official and community-maintained preprocessing plugins are available to allow you to use Svelte with tools like TypeScript, PostCSS, SCSS, and Less.

You can write your own preprocessor using the svelte.preprocess API.

The preprocess function provides convenient hooks for arbitrarily transforming component source code. For example, it can be used to convert a <style lang="sass"> block into vanilla CSS.

The first argument is the component source code. The second is an array of preprocessors (or a single preprocessor, if you only have one), where a preprocessor is an object with a name which is required, and markup, script and style functions, each of which is optional.

The markup function receives the entire component source text, along with the component's filename if it was specified in the third argument.

The script and style functions receive the contents of <script> and <style> elements respectively (content) as well as the entire component source text (markup). In addition to filename, they get an object of the element's attributes.

Each markup, script or style function must return an object (or a Promise that resolves to an object) with a code property, representing the transformed source code. Optionally they can return an array of dependencies which represents files to watch for changes, and a map object which is a sourcemap mapping back the transformation to the original code. script and style preprocessors can optionally return a record of attributes which represent the updated attributes on the script/style tag.

Preprocessor functions should return a map object whenever possible or else debugging becomes harder as stack traces can't link to the original code correctly.

ts
import { preprocess } from 'svelte/compiler';
import MagicString from 'magic-string';
const { code } = await preprocess(
source,
{
markup: ({ content, filename }) => {
const pos = content.indexOf('foo');
if (pos < 0) {
return { code: content };
}
const s = new MagicString(content, { filename });
s.overwrite(pos, pos + 3, 'bar', { storeName: true });
return {
code: s.toString(),
map: s.generateMap()
};
}
},
{
filename: 'App.svelte'
}
);

If a dependencies array is returned, it will be included in the result object. This is used by packages like vite-plugin-svelte and rollup-plugin-svelte to watch additional files for changes, in the case where your <style> tag has an @import (for example).

preprocess-sass.js
ts
import { preprocess } from 'svelte/compiler';
import MagicString from 'magic-string';
import sass from 'sass';
import { dirname } from 'path';
const { code } = await preprocess(
source,
{
name: 'my-fancy-preprocessor',
markup: ({ content, filename }) => {
// Return code as is when no foo string present
const pos = content.indexOf('foo');
if (pos < 0) {
return;
}
// Replace foo with bar using MagicString which provides
// a source map along with the changed code
const s = new MagicString(content, { filename });
s.overwrite(pos, pos + 3, 'bar', { storeName: true });
Property 'css' does not exist on type 'unknown'.
Property 'stats' does not exist on type 'unknown'.
2339
2339
Property 'css' does not exist on type 'unknown'.
Property 'stats' does not exist on type 'unknown'.
return {
code: s.toString(),
map: s.generateMap({ hires: true, file: filename })
};
Argument of type 'string | undefined' is not assignable to parameter of type 'string'. Type 'undefined' is not assignable to type 'string'.2345Argument of type 'string | undefined' is not assignable to parameter of type 'string'. Type 'undefined' is not assignable to type 'string'.
},
style: async ({ content, attributes, filename }) => {
// only process <style lang="sass">
if (attributes.lang !== 'sass') return;
const { css, stats } = await new Promise((resolve, reject) =>
sass.render(
{
file: filename,
data: content,
includePaths: [dirname(filename)]
},
(err, result) => {
if (err) reject(err);
else resolve(result);
}
)
);
// remove lang attribute from style tag
delete attributes.lang;
return {
code: css.toString(),
dependencies: stats.includedFiles,
attributes
};
}
},
{
filename: 'App.svelte'
}
);

Multiple preprocessors can be used together. The output of the first becomes the input to the second. Within one preprocessor, markup runs first, then script and style.

In Svelte 3, all markup functions ran first, then all script and then all style preprocessors. This order was changed in Svelte 4.

multiple-preprocessor.js
ts
import { preprocess } from 'svelte/compiler';
const { code } = await preprocess(source, [
{
name: 'first preprocessor',
markup: () => {
console.log('this runs first');
},
script: () => {
console.log('this runs second');
},
style: () => {
console.log('this runs third');
}
},
{
name: 'second preprocessor',
markup: () => {
console.log('this runs fourth');
},
script: () => {
console.log('this runs fifth');
},
style: () => {
console.log('this runs sixth');
}
}
], {
filename: 'App.svelte'
});
multiple-preprocessor.ts
ts
import { preprocess } from 'svelte/compiler';
const { code } = await preprocess(
source,
[
{
name: 'first preprocessor',
markup: () => {
console.log('this runs first');
},
script: () => {
console.log('this runs second');
},
style: () => {
console.log('this runs third');
},
},
{
name: 'second preprocessor',
markup: () => {
console.log('this runs fourth');
},
script: () => {
console.log('this runs fifth');
},
style: () => {
console.log('this runs sixth');
},
},
],
{
filename: 'App.svelte',
},
);

walk

The walk function provides a way to walk the abstract syntax trees generated by the parser, using the compiler's own built-in instance of estree-walker.

The walker takes an abstract syntax tree to walk and an object with two optional methods: enter and leave. For each node, enter is called (if present). Then, unless this.skip() is called during enter, each of the children are traversed, and then leave is called on the node.

compiler-walk.js
ts
import { walk } from 'svelte/compiler';
walk(ast, {
enter(node, parent, prop, index) {
do_something(node);
if (should_skip_children(node)) {
this.skip();
}
},
leave(node, parent, prop, index) {
do_something_else(node);
}
});
compiler-walk.ts
ts
import { walk } from 'svelte/compiler';
walk(ast, {
enter(node, parent, prop, index) {
do_something(node);
if (should_skip_children(node)) {
this.skip();
}
},
leave(node, parent, prop, index) {
do_something_else(node);
},
});

VERSION

ts
const VERSION: string;

The current version, as set in package.json.

ts
import { VERSION } from 'svelte/compiler';
console.log(`running svelte version ${VERSION}`);

Types

CompileOptions

ts
interface CompileOptions {}
ts
name?: string;
  • default 'Component'

Sets the name of the resulting JavaScript class (though the compiler will rename it if it would otherwise conflict with other variables in scope). It will normally be inferred from filename

ts
filename?: string;
  • default null

Used for debugging hints and sourcemaps. Your bundler plugin will set it automatically.

ts
generate?: 'dom' | 'ssr' | false;
  • default 'dom'

If "dom", Svelte emits a JavaScript class for mounting to the DOM. If "ssr", Svelte emits an object with a render method suitable for server-side rendering. If false, no JavaScript or CSS is returned; just metadata.

ts
errorMode?: 'throw' | 'warn';
  • default 'throw'

If "throw", Svelte throws when a compilation error occurred. If "warn", Svelte will treat errors as warnings and add them to the warning report.

ts
varsReport?: 'full' | 'strict' | false;
  • default 'strict'

If "strict", Svelte returns a variables report with only variables that are not globals nor internals. If "full", Svelte returns a variables report with all detected variables. If false, no variables report is returned.

ts
sourcemap?: object | string;
  • default null

An initial sourcemap that will be merged into the final output sourcemap. This is usually the preprocessor sourcemap.

ts
enableSourcemap?: EnableSourcemap;
  • default true

If true, Svelte generate sourcemaps for components. Use an object with js or css for more granular control of sourcemap generation.

ts
outputFilename?: string;
  • default null

Used for your JavaScript sourcemap.

ts
cssOutputFilename?: string;
  • default null

Used for your CSS sourcemap.

ts
sveltePath?: string;
  • default 'svelte'

The location of the svelte package. Any imports from svelte or svelte/[module] will be modified accordingly.

ts
dev?: boolean;
  • default false

If true, causes extra code to be added to components that will perform runtime checks and provide debugging information during development.

ts
accessors?: boolean;
  • default false

If true, getters and setters will be created for the component's props. If false, they will only be created for readonly exported values (i.e. those declared with const, class and function). If compiling with customElement: true this option defaults to true.

ts
immutable?: boolean;
  • default false

If true, tells the compiler that you promise not to mutate any objects. This allows it to be less conservative about checking whether values have changed.

ts
hydratable?: boolean;
  • default false

If true when generating DOM code, enables the hydrate: true runtime option, which allows a component to upgrade existing DOM rather than creating new DOM from scratch. When generating SSR code, this adds markers to <head> elements so that hydration knows which to replace.

ts
legacy?: boolean;
  • default false

If true, generates code that will work in IE9 and IE10, which don't support things like element.dataset.

ts
customElement?: boolean;
  • default false

If true, tells the compiler to generate a custom element constructor instead of a regular Svelte component.

ts
tag?: string;
  • default null

A string that tells Svelte what tag name to register the custom element with. It must be a lowercase alphanumeric string with at least one hyphen, e.g. "my-element".

ts
css?: 'injected' | 'external' | 'none' | boolean;
  • 'injected' (formerly true), styles will be included in the JavaScript class and injected at runtime for the components actually rendered.
  • 'external' (formerly false), the CSS will be returned in the css field of the compilation result. Most Svelte bundler plugins will set this to 'external' and use the CSS that is statically generated for better performance, as it will result in smaller JavaScript bundles and the output can be served as cacheable .css files.
  • 'none', styles are completely avoided and no CSS output is generated.
ts
loopGuardTimeout?: number;
  • default 0

A number that tells Svelte to break the loop if it blocks the thread for more than loopGuardTimeout ms. This is useful to prevent infinite loops. Only available when dev: true.

ts
namespace?: string;
  • default 'html'

The namespace of the element; e.g., "mathml", "svg", "foreign".

ts
cssHash?: CssHashGetter;
  • default undefined

A function that takes a { hash, css, name, filename } argument and returns the string that is used as a classname for scoped CSS. It defaults to returning svelte-${hash(css)}.

ts
preserveComments?: boolean;
  • default false

If true, your HTML comments will be preserved during server-side rendering. By default, they are stripped out.

ts
preserveWhitespace?: boolean;
  • default false

If true, whitespace inside and between elements is kept as you typed it, rather than removed or collapsed to a single space where possible.

ts
discloseVersion?: boolean;
  • default true

If true, exposes the Svelte major version on the global window object in the browser.

CompileResult

The returned shape of compile from svelte/compiler

ts
interface CompileResult {}
ts
js: {}

The resulting JavaScript code from compling the component

ts
code: string;

Code as a string

ts
map: any;

A source map

ts
css: CssResult;

The resulting CSS code from compling the component

ts
ast: Ast;

The abstract syntax tree representing the structure of the component

ts
warnings: Warning[];

An array of warning objects that were generated during compilation. Each warning has several properties:

  • code is a string identifying the category of warning
  • message describes the issue in human-readable terms
  • start and end, if the warning relates to a specific location, are objects with line, column and character properties
  • frame, if applicable, is a string highlighting the offending code with line numbers
ts
vars: Var[];

An array of the component's declarations used by tooling in the ecosystem (like our ESLint plugin) to infer more information

ts
stats: {
timings: {
total: number;
};
};

An object used by the Svelte developer team for diagnosing the compiler. Avoid relying on it to stay the same!

CssHashGetter

ts
type CssHashGetter = (args: {
name: string;
filename: string | undefined;
css: string;
hash: (input: string) => string;
}) => string;

EnableSourcemap

ts
type EnableSourcemap =
| boolean
| { js: boolean; css: boolean };

MarkupPreprocessor

A markup preprocessor that takes a string of code and returns a processed version.

ts
type MarkupPreprocessor = (options: {
/**
* The whole Svelte file content
*/
content: string;
/**
* The filename of the Svelte file
*/
filename?: string;
}) => Processed | void | Promise<Processed | void>;

Preprocessor

A script/style preprocessor that takes a string of code and returns a processed version.

ts
type Preprocessor = (options: {
/**
* The script/style tag content
*/
content: string;
/**
* The attributes on the script/style tag
*/
attributes: Record<string, string | boolean>;
/**
* The whole Svelte file content
*/
markup: string;
/**
* The filename of the Svelte file
*/
filename?: string;
}) => Processed | void | Promise<Processed | void>;

PreprocessorGroup

A preprocessor group is a set of preprocessors that are applied to a Svelte file.

ts
interface PreprocessorGroup {}
ts
name?: string;

Name of the preprocessor. Will be a required option in the next major version

ts
markup?: MarkupPreprocessor;
ts
style?: Preprocessor;
ts
script?: Preprocessor;

Processed

The result of a preprocessor run. If the preprocessor does not return a result, it is assumed that the code is unchanged.

ts
interface Processed {}
ts
code: string;

The new code

ts
map?: string | object;

A source map mapping back to the original code

ts
dependencies?: string[];

A list of additional files to watch for changes

ts
attributes?: Record<string, string | boolean>;

Only for script/style preprocessors: The updated attributes to set on the tag. If undefined, attributes stay unchanged.

ts
toString?: () => string;

SveltePreprocessor

Utility type to extract the type of a preprocessor from a preprocessor group

ts
interface SveltePreprocessor<
PreprocessorType extends keyof PreprocessorGroup,
Options = any
> {}
ts
(options?: Options): Required<Pick<PreprocessorGroup, PreprocessorType>>;