config.md

Configuration

vite-plugin-svelte accepts inline options that can be used to change its behaviour. An object can be passed to the first argument of the svelte plugin:

export default defineConfig({
	plugins: [
		svelte({
			/* plugin options */
		})
	]
});

Explore the various options below!

Config file

Config file resolving

Besides inline options, vite-plugin-svelte will also automatically resolve options from a Svelte config file if one exists. The default search paths are:

• svelte.config.js
• svelte.config.mjs
• svelte.config.cjs

To set a specific config file, use the configFile inline option. The path can be absolute or relative to the Vite root. For example:

export default defineConfig({
	plugins: [
		svelte({
			configFile: 'my-svelte.config.js'
		})
	]
});

A basic Svelte config looks like this:

// svelte.config.js
export default {
	// config options
};

Config file extension

Depending on Node's mode, make sure you're using the correct extension and syntax so it can be resolved safely.

• If type: "module" is defined in package.json, using .js only allows ESM code. Use .cjs to allow CJS code.
• If type: "module" is not defined, using .js only allows CJS code. Use .mjs to allows ESM code.

Try to stick with the .js extension whenever possible.

Svelte options

These options are specific to the Svelte compiler and are generally shared across many bundler integrations.

compilerOptions

• Type: CompileOptions - See svelte.compile

  The options to be passed to the Svelte compiler. A few options are set by default, including dev, format and css. However, some options are non-configurable, like filename, generate, and cssHash.

preprocess

• Type: PreprocessorGroup | PreprocessorGroup[] - See svelte.preprocess

  An array of preprocessors to transform the Svelte source code before compilation.

  Example:

  import sveltePreprocess from 'svelte-preprocess';
  
  export default defineConfig({
  	plugins: [
  		svelte({
  			preprocess: [sveltePreprocess({ typescript: true })]
  		})
  	]
  });

Plugin options

These options are specific to the Vite plugin itself.

include

• Type: string | string[]

A picomatch pattern, or array of patterns, which specifies the files the plugin should operate on. By default, all svelte files are included.

exclude

• Type: string | string[]

A picomatch pattern, or array of patterns, which specifies the files to be ignored by the plugin. By default, no files are ignored.

extensions

• Type: string[]

• Default: ['.svelte']

  A list of file extensions to be compiled by Svelte. Useful for custom extensions like .svg and .svx.

emitCss

• Type: boolean

• Default: true

  Emit Svelte styles as virtual CSS files for Vite and other plugins to process.

onwarn

• Type: (warning: Warning, defaultHandler?: (warning: Warning) => void) => void - See Warning

  Handles warning emitted from the Svelte compiler. Useful to suppress warning messages.

  Example:

  export default defineConfig({
  	plugins: [
  		svelte({
  			onwarn(warning, defaultHandler) {
  				// don't warn on <marquee> elements, cos they're cool
  				if (warning.code === 'a11y-distracting-elements') return;
  
  				// handle all other warnings normally
  				defaultHandler(warning);
  			}
  		})
  	]
  });

hot

• Type: boolean | SvelteHotOptions - See svelte-hmr

• Default: true for development, always false for production

  Enable or disable Hot Module Replacement (HMR).

  Do not customize the options unless you know exactly what you are doing.

ignorePluginPreprocessors

• Type: boolean | string[]

• Default: false

  Some Vite plugins can contribute additional preprocessors by defining api.sveltePreprocess. If you don't want to use them, set this to true to ignore them all or use an array of strings with plugin names to specify which.

disableDependencyReinclusion

• Type: boolean | string[]

• Default: false

  vite-plugin-svelte automatically manages pre-bundling for Svelte components. To opt-out of this automatic behavior you can use:

  • disableDependencyReinclusion: true to disable all re-inclusions
  • disableDependencyReinclusion: ['foo'] to disable re-inclusions only for dependencies of foo.

  If you want to manually re-include the dependency bar of foo, you can add {optimizeDeps:{include:['foo > bar']}} to your Vite config

  This is currently required for hybrid packages like Routify, that export both Node and browser code.

Experimental options

These options are considered experimental and breaking changes to them can occur in any release! Specify them under the experimental option.

export default defineConfig({
	plugins: [
		svelte({
			experimental: {
				// experimental options
			}
		})
	]
});

useVitePreprocess

• Type: boolean

• Default: false

  Use extra preprocessors that delegate style and TypeScript preprocessing to native Vite plugins. Do not use together with svelte-preprocess!

prebundleSvelteLibraries

• Type: boolean

• Default: false

  Force Vite to pre-bundle Svelte libraries. Currently, vite-plugin-svelte implements a complex mechanism to address pre-bundling Svelte libraries, which had an impact on large Svelte component libraries and the initial page load. See the FAQ for more information.

  Setting this option to true will directly pre-bundle Svelte libraries, which should improve initial page load performance. However, please note some caveats:

  1. Deeply importing Svelte components is not supported. Either import all components from one entrypoint, or always stick to deep imports, otherwise it could cause multiple instance of the Svelte library running.

  2. When updating the Svelte compiler options in svelte.config.js or vite.config.js, delete the node_modules/.vite folder to trigger pre-bundling in Vite again.

generateMissingPreprocessorSourcemaps

• Type: boolean

• Default: false

  If a preprocessor does not provide a sourcemap, a best-effort fallback sourcemap will be provided. This option requires diff-match-patch to be installed as a peer dependency.

dynamicCompileOptions

• Type:

  type DynamicCompileOptions = (data: {
  	filename: string; // The file to be compiled
  	code: string; // The preprocessed Svelte code
  	compileOptions: Partial<CompileOptions>; // The current compiler options
  }) => Promise<Partial<CompileOptions> | void> | Partial<CompileOptions> | void;

  A function to update the compilerOptions before compilation. To change part of the compiler options, return an object with the changes you need.

  Example:

  export default defineConfig({
  	plugins: [
  		svelte({
  			experimental: {
  				dynamicCompileOptions({ filename, compileOptions }) {
  					// Dynamically set hydration per Svelte file
  					if (compileWithHydratable(filename) && !compileOptions.hydratable) {
  						return { hydratable: true };
  					}
  				}
  			}
  		})
  	]
  });