Skip to main content
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
      }
    })
  ]
});