Compiler Options

Configuration options for the Svelte compiler

The Svelte compiler accepts a CompileOptions object that controls how your components are compiled.

Core Options

filename · string

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

compile(source, { filename: 'App.svelte' })

dev · boolean · default: "false"

If true, causes extra code to be added that performs runtime checks and provides debugging information during development.

compile(source, { dev: process.env.NODE_ENV === 'development' })

generate · 'client' | 'server' | false · default: "'client'"

• 'client': Emits code designed to run in the browser
• 'server': Emits code suitable for server-side rendering
• false: Generates nothing (useful for tooling that only needs warnings)

// Client-side bundle
compile(source, { generate: 'client' })

// SSR bundle
compile(source, { generate: 'server' })

name · string

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

compile(source, { name: 'MyComponent' })

Component Behavior

runes · boolean | undefined · default: "undefined"

• true: Forces runes mode for the entire component
• false: Forces the compiler to ignore runes, even if detected
• undefined: Infers runes mode from component code (default)

Setting this to true in your svelte.config.js will force runes mode for your entire project, including node_modules. Use dynamicCompileOptions in Vite instead.

compile(source, { runes: true })

customElement · boolean · default: "false"

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

compile(source, { customElement: true })

namespace · 'html' | 'svg' | 'mathml' · default: "'html'"

The namespace of the component’s elements.

compile(source, { namespace: 'svg' })

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. If compiling with customElement: true, this defaults to true.

Deprecated in Svelte 5 - Has no effect in runes mode

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.

Deprecated in Svelte 5 - Has no effect in runes mode

CSS Options

css · 'injected' | 'external'

• 'injected': Styles are included in the head when using render(), and injected when the component mounts. For custom elements, styles are injected to the shadow root.
• 'external': CSS is only returned in the css field of the compilation result. Most bundler plugins use this for better performance (smaller JS bundles, cacheable CSS files).

Always 'injected' when customElement: true.

compile(source, { css: 'external' })

cssHash · CssHashGetter

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

compile(source, {
  cssHash: ({ hash, css, name, filename }) => {
    return `custom-${hash(css)}`;
  }
})

Type:

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

Code Generation

preserveComments · boolean · default: "false"

If true, your HTML comments will be preserved in the output. By default, they are stripped out.

compile(source, { preserveComments: true })

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.

compile(source, { preserveWhitespace: true })

fragments · 'html' | 'tree' · default: "'html'"

Which strategy to use when cloning DOM fragments:

• 'html': Populates a <template> with innerHTML and clones it (faster, but incompatible with strict CSP)
• 'tree': Creates the fragment one element at a time and then clones it (slower, works everywhere)

Use 'tree' if your Content Security Policy includes require-trusted-types-for 'script'.

compile(source, { fragments: 'tree' })

discloseVersion · boolean · default: "true"

If true, exposes the Svelte major version in the browser by adding it to a Set stored in window.__svelte.v.

compile(source, { discloseVersion: false })

Sourcemaps

sourcemap · object | string

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

compile(source, { sourcemap: preprocessResult.map })

outputFilename · string

Used for your JavaScript sourcemap.

compile(source, { outputFilename: 'App.js' })

cssOutputFilename · string

Used for your CSS sourcemap.

compile(source, { cssOutputFilename: 'App.css' })

Module Options

rootDir · string · default: "process.cwd()"

Used for ensuring filenames don’t leak filesystem information. Your bundler plugin will set it automatically.

compile(source, { rootDir: '/path/to/project' })

warningFilter · (warning: Warning) => boolean

A function that filters warnings. Return true to keep the warning, false to discard it.

compile(source, {
  warningFilter: (warning) => {
    // Ignore a11y warnings
    return !warning.code.startsWith('a11y-');
  }
})

Advanced Options

hmr · boolean · default: "false"

If true, compiles components with hot reloading support.

compile(source, { hmr: true })

modernAst · boolean · default: "false"

If true, returns the modern version of the AST. Will become true by default in Svelte 6, and the option will be removed in Svelte 7.

compile(source, { modernAst: true })

compatibility · object

Deprecated - Use only as a temporary solution before migrating your code

compatibility.componentApi · 4 | 5 · default: "5"

Applies a transformation so the default export can be instantiated the same way as in Svelte 4:

• As a class when compiling for the browser (like using createClassComponent() from svelte/legacy)
• As an object with a .render() method when compiling for the server

compile(source, {
  compatibility: { componentApi: 4 }
})

experimental · object

Experimental compiler features.

experimental.async · boolean

Allow await keyword in deriveds, template expressions, and the top level of components.

compile(source, {
  experimental: { async: true }
})

Usage Examples

Development Build

import { compile } from 'svelte/compiler';

const result = compile(source, {
  filename: 'App.svelte',
  dev: true,
  generate: 'client',
  css: 'external',
  sourcemap: true
});

Production Build

const result = compile(source, {
  filename: 'App.svelte',
  dev: false,
  generate: 'client',
  css: 'external',
  discloseVersion: false
});

SSR Configuration

const result = compile(source, {
  filename: 'App.svelte',
  generate: 'server',
  dev: false,
  css: 'external'
});

Custom Element

const result = compile(source, {
  filename: 'MyElement.svelte',
  customElement: true,
  css: 'injected',
  accessors: true
});

Strict CSP Environment

const result = compile(source, {
  filename: 'App.svelte',
  fragments: 'tree' // Required for strict CSP
});

With Vite Plugin

// vite.config.js
import { defineConfig } from 'vite';
import { svelte } from '@sveltejs/vite-plugin-svelte';

export default defineConfig({
  plugins: [
    svelte({
      compilerOptions: {
        dev: process.env.NODE_ENV === 'development',
        css: 'external',
        preserveComments: false,
        runes: undefined // Infer from code
      }
    })
  ]
});

Related

• compile() - Main compilation function
• preprocess() - Preprocess before compiling
• migrate() - Migrate from Svelte 4 to 5