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:
// vite.config.js
export default defineConfig({
plugins: [
svelte({
/* plugin options */
})
]
});
Explore the various options below!
Besides inline options in Vite config, 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:
// vite.config.js
export default defineConfig({
plugins: [
svelte({
configFile: 'my-svelte.config.js'
})
]
});
A basic Svelte config looks like this:
// svelte.config.js
export default {
// svelte options
extensions: ['.svelte'],
compilerOptions: {},
preprocess: [],
onwarn: (warning, handler) => handler(warning),
// plugin options
vitePlugin: {
exclude: [],
// experimental options
experimental: {}
}
};
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 inpackage.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.
Use configFile: false
to prevent vite-plugin-svelte
from reading the config file or restarting the Vite dev server when it changes.
// vite.config.js
export default defineConfig({
plugins: [
svelte({
configFile: false
// your svelte config here
})
]
});
Warning: This option primarily exists for frameworks like SvelteKit that do their own parsing of Svelte config and control the Vite dev server. You are responsible to provide the complete inline config when used.
These options are specific to the Svelte compiler and are generally shared across many bundler integrations.
-
Type:
CompileOptions
- See svelte.compileThe options to be passed to the Svelte compiler. A few options are set by default, including
dev
andcss
. However, some options are non-configurable, likefilename
,format
,generate
, andcssHash
(in dev).
-
Type:
PreprocessorGroup | PreprocessorGroup[]
- See svelte.preprocessAn array of preprocessors to transform the Svelte source code before compilation.
Example:
// vite.config.js import sveltePreprocess from 'svelte-preprocess'; export default defineConfig({ plugins: [ svelte({ preprocess: [sveltePreprocess({ typescript: true })] }) ] });
-
Type:
string[]
-
Default:
['.svelte']
A list of file extensions to be compiled by Svelte. Useful for custom extensions like
.svg
and.svx
.
-
Type:
(warning: Warning, defaultHandler?: (warning: Warning) => void) => void
- See WarningHandles 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); } }) ] });
These options are specific to the Vite plugin itself.
- 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.
- 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.
-
Type:
boolean
-
Default:
true
Emit Svelte styles as virtual CSS files for Vite and other plugins to process.
-
Type:
boolean | SvelteHotOptions
- See svelte-hmr -
Default:
true
for development, alwaysfalse
for productionEnable or disable Hot Module Replacement (HMR).
Do not customize the options unless you know exactly what you are doing.
-
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.
-
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-inclusionsdisableDependencyReinclusion: ['foo']
to disable re-inclusions only for dependencies offoo
.
If you want to manually re-include the dependency
bar
offoo
, you can add{optimizeDeps:{include:['foo > bar']}}
to your Vite configThis is currently required for hybrid packages like Routify, that export both Node and browser code.
These options are considered experimental and breaking changes to them can occur in any release! Specify them under the experimental
option.
Either in Vite config:
// vite.config.js
export default defineConfig({
plugins: [
svelte({
experimental: {
// experimental options
}
})
]
});
or in Svelte config:
// svelte.config.js
export default {
vitePlugin: {
experimental: {
// experimental options
}
}
};
-
Type:
boolean
-
Default:
false
Use extra preprocessors that delegate style and TypeScript preprocessing to native Vite plugins. TypeScript will be transformed with esbuild. Styles will be transformed using Vite's CSS plugin, which handles
@imports
,url()
references, PostCSS, CSS Modules, and.scss
/.sass
/.less
/.styl
/.stylus
files. Do not use together with TypeScript or style preprocessors fromsvelte-preprocess
as attempts to transform the content twice will fail!
-
Type:
boolean
-
Default:
false
Force Vite to pre-bundle Svelte libraries. Setting this
true
should improve initial page load performance, especially when using large Svelte libraries. See the FAQ for details of the pre-bundling implementation.
-
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.
-
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:
// vite.config.js export default defineConfig({ plugins: [ svelte({ experimental: { dynamicCompileOptions({ filename, compileOptions }) { // Dynamically set hydration per Svelte file if (compileWithHydratable(filename) && !compileOptions.hydratable) { return { hydratable: true }; } } } }) ] });
-
Type:
InspectorOptions | boolean
interface InspectorOptions { /** * define a key combo to toggle inspector, * @default 'control-shift' on windows, 'meta-shift' on other os * * any number of modifiers `control` `shift` `alt` `meta` followed by zero or one regular key, separated by - * examples: control-shift, control-o, control-alt-s meta-x control-meta * Some keys have native behavior (e.g. alt-s opens history menu on firefox). * To avoid conflicts or accidentally typing into inputs, modifier only combinations are recommended. */ toggleKeyCombo?: string; /** * define keys to drill from the active element (up selects parent, down selects child). * @default {up: 'ArrowUp',down: 'ArrowDown'} * * This is useful when components wrap another one without providing any hoverable area between them */ drillKeys?: { up: string; down: string }; /** * inspector is automatically disabled when releasing toggleKeyCombo after holding it for a longpress * @default false */ holdMode?: boolean; /** * when to show the toggle button * @default 'active' */ showToggleButton?: 'always' | 'active' | 'never'; /** * where to display the toggle button * @default top-right */ toggleButtonPos?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'; /** * inject custom styles when inspector is active */ customStyles?: boolean; /** * append an import to the module id ending with `appendTo` instead of adding a script into body * useful for frameworks that do not support trannsformIndexHtml hook * * WARNING: only set this if you know exactly what it does. * Regular users of vite-plugin-svelte or SvelteKit do not need it */ appendTo?: string; }
Set to
true
or customizedInspectorOptions
to enable svelte inspector during development.When enabled, inspector mode shows you the file location where the element under cursor is defined and you can click to quickly open your code editor at this location.
Example:
// vite.config.js export default defineConfig({ plugins: [ svelte({ experimental: { inspector: { toggleKeyCombo: 'meta-shift', holdMode: true, showToggleButton: 'always', toggleButtonPos: 'bottom-right' } } }) ] });
-
Type:
boolean
-
Default:
false
Sends a websocket message
svelte:warnings
with the warnings that are passed toonwarn
. This is only useful if you build a custom browser based integration where you want to display these.Example
import.meta.hot.on('svelte:warnings', (message) => { // handle warnings message, eg log to console console.warn(`Warnings for ${message.filename}`, message.warnings); });
Message format
type SvelteWarningsMessage = { id: string; filename: string; normalizedFilename: string; timestamp: number; warnings: Warning[]; // allWarnings filtered by warnings where onwarn did not call the default handler allWarnings: Warning[]; // includes warnings filtered by onwarn and our extra vite plugin svelte warnings rawWarnings: Warning[]; // raw compiler output };