> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/sveltejs/svelte/llms.txt
> Use this file to discover all available pages before exploring further.
# Compiler Options
> Configuration options for the Svelte compiler
The Svelte compiler accepts a `CompileOptions` object that controls how your components are compiled.
## Core Options
Used for debugging hints and sourcemaps. Your bundler plugin will set it automatically.
```js theme={null}
compile(source, { filename: 'App.svelte' })
```
If `true`, causes extra code to be added that performs runtime checks and provides debugging information during development.
```js theme={null}
compile(source, { dev: process.env.NODE_ENV === 'development' })
```
* `'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)
```js theme={null}
// Client-side bundle
compile(source, { generate: 'client' })
// SSR bundle
compile(source, { generate: 'server' })
```
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`.
```js theme={null}
compile(source, { name: 'MyComponent' })
```
## Component Behavior
* `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](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/config.md#dynamiccompileoptions) in Vite instead.
```js theme={null}
compile(source, { runes: true })
```
If `true`, tells the compiler to generate a custom element constructor instead of a regular Svelte component.
```js theme={null}
compile(source, { customElement: true })
```
The namespace of the component's elements.
```js theme={null}
compile(source, { namespace: 'svg' })
```
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
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
* `'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`.
```js theme={null}
compile(source, { css: 'external' })
```
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)}`.
```js theme={null}
compile(source, {
cssHash: ({ hash, css, name, filename }) => {
return `custom-${hash(css)}`;
}
})
```
Type:
```ts theme={null}
type CssHashGetter = (args: {
name: string;
filename: string;
css: string;
hash: (input: string) => string;
}) => string;
```
## Code Generation
If `true`, your HTML comments will be preserved in the output. By default, they are stripped out.
```js theme={null}
compile(source, { preserveComments: true })
```
If `true`, whitespace inside and between elements is kept as you typed it, rather than removed or collapsed to a single space where possible.
```js theme={null}
compile(source, { preserveWhitespace: true })
```
Which strategy to use when cloning DOM fragments:
* `'html'`: Populates a `` 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'`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/require-trusted-types-for).
```js theme={null}
compile(source, { fragments: 'tree' })
```
If `true`, exposes the Svelte major version in the browser by adding it to a `Set` stored in `window.__svelte.v`.
```js theme={null}
compile(source, { discloseVersion: false })
```
## Sourcemaps
An initial sourcemap that will be merged into the final output sourcemap. This is usually the preprocessor sourcemap.
```js theme={null}
compile(source, { sourcemap: preprocessResult.map })
```
Used for your JavaScript sourcemap.
```js theme={null}
compile(source, { outputFilename: 'App.js' })
```
Used for your CSS sourcemap.
```js theme={null}
compile(source, { cssOutputFilename: 'App.css' })
```
## Module Options
Used for ensuring filenames don't leak filesystem information. Your bundler plugin will set it automatically.
```js theme={null}
compile(source, { rootDir: '/path/to/project' })
```
A function that filters warnings. Return `true` to keep the warning, `false` to discard it.
```js theme={null}
compile(source, {
warningFilter: (warning) => {
// Ignore a11y warnings
return !warning.code.startsWith('a11y-');
}
})
```
## Advanced Options
If `true`, compiles components with hot reloading support.
```js theme={null}
compile(source, { hmr: true })
```
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.
```js theme={null}
compile(source, { modernAst: true })
```
Deprecated - Use only as a temporary solution before migrating your code
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
```js theme={null}
compile(source, {
compatibility: { componentApi: 4 }
})
```
Experimental compiler features.
Allow `await` keyword in deriveds, template expressions, and the top level of components.
```js theme={null}
compile(source, {
experimental: { async: true }
})
```
## Usage Examples
### Development Build
```js theme={null}
import { compile } from 'svelte/compiler';
const result = compile(source, {
filename: 'App.svelte',
dev: true,
generate: 'client',
css: 'external',
sourcemap: true
});
```
### Production Build
```js theme={null}
const result = compile(source, {
filename: 'App.svelte',
dev: false,
generate: 'client',
css: 'external',
discloseVersion: false
});
```
### SSR Configuration
```js theme={null}
const result = compile(source, {
filename: 'App.svelte',
generate: 'server',
dev: false,
css: 'external'
});
```
### Custom Element
```js theme={null}
const result = compile(source, {
filename: 'MyElement.svelte',
customElement: true,
css: 'injected',
accessors: true
});
```
### Strict CSP Environment
```js theme={null}
const result = compile(source, {
filename: 'App.svelte',
fragments: 'tree' // Required for strict CSP
});
```
### With Vite Plugin
```js theme={null}
// 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()](/api/compiler/compile) - Main compilation function
* [preprocess()](/api/compiler/preprocess) - Preprocess before compiling
* [migrate()](/api/compiler/migrate) - Migrate from Svelte 4 to 5