svelte/compiler

En général, vous n'interagirez pas directement avec le compilateur Svelte, mais vous l'intègrerez plutôt dans un processus de build à travers un plugin de bundler. Le plugin que l'équipe Svelte recommande et avec lequel elle travaille est vite-plugin-svelte. Le framework SvelteKit fournit une configuration de vite-plugin-svelte qui permet de compiler des applications et de packager des librairies de composants Svelte. Svelte Society maintient des plugins pour d'autres bundlers (notamment Rollup et Webpack).

Néanmoins, il est utile de comprendre comment utiliser le compilateur, puisque les plugins exposent généralement des options.

compilepermalink

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

C'est ici que la magie opère. svelte.compile convertit le code source des composants en module JavaScript qui exporte des classes.

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

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

Référez-vous à la section CompilerOptions pour voir les options disponibles.

L'objet retourné result contient le code du composant, ainsi que des métadonnées utiles.

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

Référez-vous à la section CompilerResult pour une description du résultat compilé.

parsepermalink

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

La méthode parse convertit un composant pour retourner son arbre de la syntaxe abstraite (AST). Contrairement à la compilation avec l'option generate: false, aucune validation ni analyse n'est effectuée. Notez que l'AST n'est pas considéré comme une API publique ; des changements critiques pourraient survenir à n'importe quel moment.

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

Un certain nombre de plugins de pré-processeur maintenus par la communauté est disponible pour vous permettre d'utiliser Svelte avec des outils comme TypeScript, PostCSS, SCSS, et Less.

Vous pouvez écrire votre propre pré-processeur en utilisant l'API `svelte.

La fonction preprocess fournit des framework pour transformer le code source d'un composant selon vos besoins. Par exemple, elle peut convertir un bloc <style lang="sass"> en css natif.

Le premier argument est le code source du composant lui-même. Le second argument est un tableau de pré-processeurs (ou éventuellement un seul pré-processeur si vous n'en avez qu'un). Un pré-processeur est un objet contenant trois fonctions : markup, script et style, toutes optionnelles.

La fonction markup reçoit en argument le markup du composant, et le nom du composant filename s'il était spécifié comme troisième argument.

Les fonctions script et style reçoivent le contenu des blocs <script> et <style> respectivement (content) ainsi que toute la source textuelle (markup) du composant. En plus du nom du fichier filename, elles reçoivent un objet contenant les attributs de l'élément.

Chaque fonction markup, script et style doit retourner un objet (ou une Promesse qui résout un objet) contenant un attribut code, représentant le code source transformé. Ces fonctions peuvent aussi renvoyer un tableau facultatif de dépendances dependencies qui représente les fichiers dont les changements sont à surveiller, ainsi qu'un objet map qui est une sourcemap renvoyant la transformation vers le code d'origine. Les pré-processeurs script et style peuvent de manière optionnelle renvoyer un ensemble d'attributs qui représentent les attributs mis à jour sur les balises <script>/<style>.

Les fonctions de preprocessing doivent également retourner un objet map en plus de code et dependencies, où map correspond à la sourcemap de la transformation.

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

Si un tableau de dépendances dependencies est retourné, il sera inclus dans l'objet retourné. Ce tableau est utilisé par des librairies comme rollup-plugin-svelte pour surveiller les changements dans les fichiers, par exemple si un bloc <style> contient un import de type @import.

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 }) => {
			// renvoie le code tel quel quand aucune string foo n'est présente
			const pos = content.indexOf('foo');
			if (pos < 0) {
				return;
			}

			// Remplace foo par bar en utilisant MagicString qui fournit
			// une sourcemap en plus du code modifié
			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
2339Property '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 }) => {
			// traite uniquement <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);
					}
				)
			);

			// supprime l'attribut lang de la balise <style>
			delete attributes.lang;

			return {
				code: css.toString(),
				dependencies: stats.includedFiles,
				attributes
			};
		}
	},
	{
		filename: 'App.svelte'
	}
);

Plusieurs pré-processeurs peuvent être utilisés ensemble. La sortie du premier devient l'argument du second. Les fonctions sont exécutées dans l'ordre suivant : markup, script puis style.

En Svelte 3, toutes les fonctions markup étaient exécutées en premier, puis toutes les fonctions script et enfin toutes les fonctions style. Cet ordre a été changé dans Svelte 4.

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

const { code } = await preprocess(source, [
	{
		name: 'premier pré-processeur',
		markup: () => {
			console.log('ceci est éxécuté en premier');
		},
		script: () => {
			console.log('ça en second');
		},
		style: () => {
			console.log('ça en troisième');
		}
	},
	{
		name: 'second pré-processeur',
		markup: () => {
			console.log('ça en quatrième');
		},
		script: () => {
			console.log('ça en cinquième');
		},
		style: () => {
			console.log('ça en sixième');
		}
	}
], {
	filename: 'App.svelte'
});

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

const { code } = await preprocess(
	source,
	[
		{
			name: 'premier pré-processeur',
			markup: () => {
				console.log('ceci est éxécuté en premier');
			},
			script: () => {
				console.log('ça en second');
			},
			style: () => {
				console.log('ça en troisième');
			},
		},
		{
			name: 'second pré-processeur',
			markup: () => {
				console.log('ça en quatrième');
			},
			script: () => {
				console.log('ça en cinquième');
			},
			style: () => {
				console.log('ça en sixième');
			},
		},
	],
	{
		filename: 'App.svelte',
	},
);

walkpermalink

La fonction walk fournit un un moyen de parcourir les arbres AST générés par le parser, en utilisant l'utilitaire estree-walker du compilateur.

La fonction prend comme argument l'arbre AST à traiter et un objet contenant 2 méthodes facultatives : enter et leave. enter est appelée pour chaque noeud (si la méthode est définie). Puis, à moins que this.skip() n'ait été appelée lors de l'exécution de enter, chaque enfant est également traversé. Enfin, la méthode leave est appelée pour le noeud actuel.

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

walk(ast, {
	enter(node, parent, prop, index) {
		faire_quelque_chose(node);
		if (doit_ignorer_les_enfants(node)) {
			this.skip();
		}
	},
	leave(node, parent, prop, index) {
		faire_autre_chose(node);
	}
});

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

walk(ast, {
	enter(node, parent, prop, index) {
		faire_quelque_chose(node);
		if (doit_ignorer_les_enfants(node)) {
			this.skip();
		}
	},
	leave(node, parent, prop, index) {
		faire_autre_chose(node);
	},
});

VERSIONpermalink

ts
const VERSION: string;

La version actuelle, définie dans le fichier package.json.

ts
import { VERSION } from 'svelte/compiler';
console.log(`la version ${VERSION} de Svelte est en cours d'exécution`);

Typespermalink

CompileOptionspermalink

ts
interface CompileOptions {…}

ts
name?: string;

ts
filename?: string;

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

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

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

ts
sourcemap?: object | string;

ts
enableSourcemap?: EnableSourcemap;

ts
outputFilename?: string;

ts
cssOutputFilename?: string;

ts
sveltePath?: string;

ts
dev?: boolean;

ts
accessors?: boolean;

ts
immutable?: boolean;

ts
hydratable?: boolean;

ts
legacy?: boolean;

ts
customElement?: boolean;

ts
tag?: string;

ts
css?: 'injected' | 'external' | 'none' | boolean;

ts
loopGuardTimeout?: number;

ts
namespace?: string;

ts
cssHash?: CssHashGetter;

ts
preserveComments?: boolean;

ts
preserveWhitespace?: boolean;

ts
discloseVersion?: boolean;

CompileResultpermalink

The returned shape of compile from svelte/compiler

ts
interface CompileResult {…}

ts
js: {…}

ts
code: string;

ts
map: any;

ts
css: CssResult;

ts
ast: Ast;

ts
warnings: Warning[];

ts
vars: Var[];

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

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;

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;

ts
map?: string | object;

ts
dependencies?: string[];

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

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