0
# Svelte Vite Plugin
1

2
The official Vite plugin for integrating Svelte components into Vite-based development workflows. It enables seamless compilation, bundling, and hot module replacement (HMR) for Svelte components within Vite projects. The plugin handles Svelte component preprocessing, supports advanced configuration options for customizing the Svelte compilation process, integrates with the Svelte Inspector for debugging, and provides optimal build performance through Vite's native ES modules and fast bundling capabilities.
3

4
## Package Information
5

6
- **Package Name**: @sveltejs/vite-plugin-svelte
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install @sveltejs/vite-plugin-svelte`
10

11
## Core Imports
12

13
```javascript
14
import { svelte } from '@sveltejs/vite-plugin-svelte';
15
```
16

17
Additional utilities:
18

19
```javascript
20
import { svelte, vitePreprocess, loadSvelteConfig } from '@sveltejs/vite-plugin-svelte';
21
```
22

23
Standalone Inspector Plugin:
24

25
```javascript
26
import { svelteInspector } from '@sveltejs/vite-plugin-svelte-inspector';
27
```
28

29
## Basic Usage
30

31
```javascript
32
// vite.config.js
33
import { defineConfig } from 'vite';
34
import { svelte } from '@sveltejs/vite-plugin-svelte';
35

36
export default defineConfig({
37
  plugins: [
38
    svelte({
39
      // Plugin options
40
      emitCss: true,
41
      hot: !process.env.VITEST,
42
      compilerOptions: {
43
        dev: !process.env.VITEST
44
      }
45
    })
46
  ]
47
});
48
```
49

50
```javascript
51
// svelte.config.js
52
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
53

54
export default {
55
  preprocess: vitePreprocess({
56
    style: true,
57
    script: false // Not needed for TypeScript in Svelte 5+
58
  }),
59
  compilerOptions: {
60
    runes: true
61
  }
62
};
63
```
64

65
## Architecture
66

67
The plugin is built around several key components:
68

69
- **Plugin Factory**: The main `svelte()` function returns an array of specialized Vite plugins
70
- **Configuration System**: Loads and merges Svelte configuration from various sources
71
- **Preprocessing Pipeline**: Handles TypeScript and CSS preprocessing via Vite
72
- **Compilation Engine**: Compiles Svelte components with hot reload support
73
- **Dependency Optimization**: Automatically handles Svelte library dependencies
74
- **Inspector Integration**: Provides development-time debugging via Svelte Inspector
75

76
## Capabilities
77

78
### Main Plugin Function
79

80
Creates the Vite plugin array for handling Svelte files in development and build processes.
81

82
```typescript { .api }
83
function svelte(inlineOptions?: Partial<Options>): Plugin[];
84

85
interface Options extends Omit<SvelteConfig, 'vitePlugin'>, PluginOptionsInline {}
86

87
interface PluginOptionsInline extends PluginOptions {
88
  /** Path to svelte config file, either absolute or relative to Vite root */
89
  configFile?: string | false;
90
}
91
```
92

93
[Main Plugin Configuration](./main-plugin.md)
94

95
### Vite Preprocessing
96

97
Svelte preprocessor that uses Vite's transformation pipeline for processing script and style blocks within Svelte components.
98

99
```typescript { .api }
100
function vitePreprocess(opts?: VitePreprocessOptions): PreprocessorGroup;
101

102
interface VitePreprocessOptions {
103
  /** Preprocess script blocks with vite pipeline (default: false) */
104
  script?: boolean;
105
  /** Preprocess style blocks with vite pipeline */
106
  style?: boolean | InlineConfig | ResolvedConfig;
107
}
108
```
109

110
[Vite Preprocessing](./vite-preprocessing.md)
111

112
### Configuration Loading
113

114
Utility for loading and parsing Svelte configuration files in custom build scenarios.
115

116
```typescript { .api }
117
function loadSvelteConfig(
118
  viteConfig?: UserConfig,
119
  inlineOptions?: Partial<Options>
120
): Promise<Partial<SvelteConfig> | undefined>;
121
```
122

123
[Configuration Management](./configuration.md)
124

125
### Inspector Plugin
126

127
Standalone development-time debugging tool for interactive Svelte component inspection in the browser.
128

129
```typescript { .api }
130
function svelteInspector(options?: Partial<InspectorOptions>): Plugin;
131

132
interface InspectorOptions {
133
  /** Key combo to toggle inspector (default: 'alt-x') */
134
  toggleKeyCombo?: string;
135
  /** Keyboard navigation keys */
136
  navKeys?: {
137
    parent: string;
138
    child: string; 
139
    next: string;
140
    prev: string;
141
  };
142
  /** Key to open editor (default: 'Enter') */
143
  openKey?: string;
144
  /** Keys to close inspector (default: ['Backspace', 'Escape']) */
145
  escapeKeys?: string[];
146
  /** Auto-disable on key release (default: true) */
147
  holdMode?: boolean;
148
  /** When to show toggle button (default: 'active') */
149
  showToggleButton?: 'always' | 'active' | 'never';
150
  /** Toggle button position (default: 'top-right') */
151
  toggleButtonPos?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
152
  /** Inject custom styles when active */
153
  customStyles?: boolean;
154
}
155
```
156

157
[Inspector Plugin](./inspector-plugin.md)
158

159
## Core Types
160

161
```typescript { .api }
162
interface PluginOptions {
163
  /** Files to include (picomatch patterns) */
164
  include?: Arrayable<string | RegExp>;
165
  /** Files to exclude (picomatch patterns) */
166
  exclude?: Arrayable<string | RegExp>;
167
  /** Emit Svelte styles as virtual CSS files (default: true) */
168
  emitCss?: boolean;
169
  /** Enable/disable Hot Module Replacement (deprecated, use compilerOptions.hmr) */
170
  hot?: boolean;
171
  /** Ignore preprocessors from other plugins */
172
  ignorePluginPreprocessors?: boolean | string[];
173
  /** Control automatic dependency optimization */
174
  disableDependencyReinclusion?: boolean | string[];
175
  /** Enable Svelte library prebundling (default: true for dev, false for build) */
176
  prebundleSvelteLibraries?: boolean;
177
  /** Configure Svelte Inspector */
178
  inspector?: InspectorOptions | boolean;
179
  /** Dynamic compiler options function */
180
  dynamicCompileOptions?: (data: {
181
    filename: string;
182
    code: string;
183
    compileOptions: Partial<CompileOptions>;
184
  }) => Promise<Partial<CompileOptions> | void> | Partial<CompileOptions> | void;
185
  /** Experimental features */
186
  experimental?: ExperimentalOptions;
187
}
188

189
interface SvelteConfig {
190
  /** File extensions to compile (default: ['.svelte']) */
191
  extensions?: string[];
192
  /** Preprocessors for Svelte source code */
193
  preprocess?: Arrayable<PreprocessorGroup>;
194
  /** Svelte compiler options */
195
  compilerOptions?: Omit<CompileOptions, 'filename' | 'format' | 'generate'>;
196
  /** Warning handler function */
197
  onwarn?: (warning: Warning, defaultHandler: (warning: Warning) => void) => void;
198
  /** Plugin-specific options */
199
  vitePlugin?: PluginOptions;
200
}
201

202
interface ExperimentalOptions {
203
  /** Send compiler warnings to browser via WebSocket */
204
  sendWarningsToBrowser?: boolean;
205
  /** Disable svelte field resolve warnings */
206
  disableSvelteResolveWarnings?: boolean;
207
  /** Disable api.sveltePreprocess deprecation warnings */
208
  disableApiSveltePreprocessWarnings?: boolean;
209
  /** Module compilation options */
210
  compileModule?: CompileModuleOptions;
211
}
212

213
interface CompileModuleOptions {
214
  /** Required filename infixes (default: ['.svelte.']) */
215
  infixes?: string[];
216
  /** Module extensions (default: ['.ts', '.js']) */
217
  extensions?: string[];
218
  /** Include patterns */
219
  include?: Arrayable<string | RegExp>;
220
  /** Exclude patterns */
221
  exclude?: Arrayable<string | RegExp>;
222
}
223

224
type Arrayable<T> = T | T[];
225
```