Compiler and API

svelte/compiler

通常、Svelte コンパイラと直接やり取りすることはありません。その代わり、バンドラープラグイン(bundler plugin)を使ってビルドシステムにインテグレートします。Svelte チームが最も推奨している、また注力もしているバンドラープラグインは vite-plugin-svelte です。SvelteKit フレームワークは vite-plugin-svelte を活用し、アプリケーションをビルドするためのセットアップと、Svelte コンポーネントライブラリをパッケージングするツールを提供しています。Svelte Society には、Rollup や Webpack などのツール向けのその他のバンドラープラグインのリストがあります。

とはいえ、バンドラープラグインは一般的にコンパイラのオプションを公開しているので、コンパイラの使い方を理解しておくと便利です。

compilepermalink

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

ここでマジックが起こります。svelte.compile はあなたのコンポーネントのソースコードを使用して、クラスをエクスポートするJavaScriptモジュールに変えます。

ts
import { compile } from 'svelte/compiler';

const result = compile(source, {
	// options
});

使用可能なすべてのオプションについては、CompileOptions をご参照ください。

戻り値の result オブジェクトには、あなたのコンポーネントのコードと、ちょっとした便利なメタデータが含まれています。

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

コンパイルの result の完全な詳細については、CompileResult をご参照ください。

parsepermalink

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

parse 関数はコンポーネントをパースし、その抽象構文木(abstract syntax tree)のみを返します。generate: false オプションを指定してコンパイルするのとは異なり、これはコンポーネントをパースするだけで、バリデーションやその他の解析を行いません。戻り値の AST はパブリックな API とは見なされないため、将来どこかのタイミングで破壊的な変更が発生する可能性があることにご注意ください。

ts
import { parse } from 'svelte/compiler';

const ast = parse(source, { filename: 'App.svelte' });

preprocesspermalink

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

Svelte で TypeScript、PostCSS、SCSS、Less などのツールを利用できるようにするためのコミュニティでメンテナンスされているプリプロセッサプラグインが多数用意されています。

svelte.preprocess API を使って独自のプリプロセッサを書くことができます。

preprocess 関数は、コンポーネントのソースコードを任意に変換するための便利なフックを提供します。例えば、<style lang="sass"> ブロックを純粋なCSSに変換するために使うことができます。

最初の引数はコンポーネントのソースコードです。2番目の引数は、 プリプロセッサ(preprocessor) の配列で (1つしかない場合は単独のプリプロセッサになります)、プリプロセッサは name (必須)と、markup、script、style 関数(それぞれオプション)を持つオブジェクトです。

markup 関数は、コンポーネントのソーステキスト全体と、第3引数にコンポーネントの filename が指定されている場合はそのコンポーネントの filename を受け取ります。

script 関数と style 関数はそれぞれ <script> と <style> 要素の内容 (content) とコンポーネントのソーステキスト全体 (markup) を受け取ります。これらの関数は filename に加えて要素の属性のオブジェクトを取得します。

markup、script、style 関数は、変換後のソースコードを表す code プロパティを持つオブジェクト (または resolve するとオブジェクトを返す promise) を返す必要があります。オプションで、変更を監視するファイルを表す dependencies の配列と、オリジナルと変換後のコードのマッピングをする sourcemap である map オブジェクトを返すことができます。script と style のプロプロセッサは、オプションで、script/style タグで更新された属性のレコードを返すことができます。

プリプロセッサ関数は、可能な限り map オブジェクトを返すべきです。そうしないと、スタックトレースがオリジナルのコードに正しくリンクできないため、デバッグが難しくなります。

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'
	}
);

dependencies の配列が返される場合、それは result オブジェクトに含まれます。これは例えば、vite-plugin-svelte や rollup-plugin-svelte のようなパッケージで、<style> タグに @import がある場合など、追加のファイルのヘンクを監視するために使われます。

preprocess-sass.js

ts
import { preprocess } from 'svelte/compiler';
import MagicString from 'magic-string';
Type 'string | undefined' is not assignable to type 'string'.
  Type 'undefined' is not assignable to type 'string'.2322Type 'string | undefined' is not assignable to type 'string'.
  Type 'undefined' is not assignable to type 'string'.import sass from 'sass';
import { dirname } from 'path';
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'.
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 });

			return {
				code: s.toString(),
				map: s.generateMap({ hires: true, file: filename })
			};
		},
		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'
	}
);

複数のプリプロセッサを併用することができます。最初のプリプロセッサの出力は、2番目のプリプロセッサへの入力になります。プリプロセッサの中では、最初に markup 関数が実行され、次に script、そして style が実行されます。

Svelte 3 では、すべての markup 関数がまず実行され、それからすべての script、そしてすべての style が実行されていました。この順番は、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',
	},
);

walkpermalink

walk 関数はパーサーによって生成された抽象構文木(abstract syntax trees)をウォークする方法を提供します。コンパイラの組み込みの estree-walker のインスタンスを使用します。

walker は、walk する抽象構文木と、オプションの2つのメソッド enter と leave を持つオブジェクトを受け取ります。各ノードに対して、(存在すれば) enter が呼び出されます。そして enter を実行している間に this.skip() が呼ばれない限り、それぞれの子を巡回し、それからノード上で leave が呼ばれます。

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);
	},
});

VERSIONpermalink

ts
const VERSION: string;

package.json に設定されている現在のバージョンです。

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

Typespermalink

CompileOptionspermalink

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 in the browser by adding it to a Set stored in the global window.__svelte.v.

CompileResultpermalink

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!

CssHashGetterpermalink

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

EnableSourcemappermalink

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

MarkupPreprocessorpermalink

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>;

Preprocessorpermalink

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>;

PreprocessorGrouppermalink

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;

Processedpermalink

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;

SveltePreprocessorpermalink

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>>;

previous svelte/action

next Client-side component API