0
# Vite Preprocessing
1

2
Svelte preprocessor that uses Vite's transformation pipeline for processing script and style blocks within Svelte components. This allows Svelte components to use TypeScript, PostCSS, Sass, and other transformations that Vite supports.
3

4
## Capabilities
5

6
### Vite Preprocessor Factory
7

8
Creates a Svelte preprocessor that integrates with Vite's transformation pipeline.
9

10
```typescript { .api }
11
/**
12
 * Creates a Svelte preprocessor that uses Vite's pipeline for script and style processing
13
 * @param opts - Preprocessing options
14
 * @returns Svelte PreprocessorGroup for use in svelte.config.js
15
 */
16
function vitePreprocess(opts?: VitePreprocessOptions): PreprocessorGroup;
17

18
interface VitePreprocessOptions {
19
  /** 
20
   * Preprocess script blocks with vite pipeline
21
   * Since Svelte 5 this is not needed for TypeScript anymore
22
   * @default false
23
   */
24
  script?: boolean;
25
  /** Preprocess style blocks with vite pipeline */
26
  style?: boolean | InlineConfig | ResolvedConfig;
27
}
28
```
29

30
**Usage Examples:**
31

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

36
export default {
37
  preprocess: vitePreprocess({
38
    style: true,
39
    script: false // Not needed for TypeScript in Svelte 5+
40
  })
41
};
42

43
// Enable both script and style preprocessing
44
export default {
45
  preprocess: vitePreprocess({
46
    style: true,
47
    script: true // Only needed for Svelte 4 or specific use cases
48
  })
49
};
50

51
// Pass Vite config for style preprocessing
52
export default {
53
  preprocess: vitePreprocess({
54
    style: {
55
      css: {
56
        devSourcemap: true,
57
        preprocessorOptions: {
58
          scss: {
59
            additionalData: '@import "src/styles/variables.scss";'
60
          }
61
        }
62
      }
63
    }
64
  })
65
};
66
```
67

68
## Script Preprocessing
69

70
### Script Processing Options
71

72
Configure TypeScript and JavaScript preprocessing for script blocks.
73

74
```typescript { .api }
75
interface ScriptProcessingOptions {
76
  /** 
77
   * Enable script block preprocessing
78
   * Note: Since Svelte 5, TypeScript is handled natively and this is usually not needed
79
   * @default false
80
   */
81
  script?: boolean;
82
}
83
```
84

85
**Usage Examples:**
86

87
```javascript
88
// For Svelte 5+ (TypeScript works natively)
89
export default {
90
  preprocess: vitePreprocess({
91
    script: false // Default, TypeScript works without this
92
  })
93
};
94

95
// For Svelte 4 or when you need Vite transformations in script blocks
96
export default {
97
  preprocess: vitePreprocess({
98
    script: true // Enables Vite's esbuild/oxc transformation
99
  })
100
};
101
```
102

103
**Svelte Component Example:**
104

105
```svelte
106
<!-- Works in Svelte 5+ without script preprocessing -->
107
<script lang="ts">
108
  interface User {
109
    name: string;
110
    age: number;
111
  }
112
  
113
  export let user: User;
114
  
115
  // TypeScript features work natively
116
  const displayName: string = user.name.toUpperCase();
117
</script>
118

119
<div>
120
  <h1>{displayName}</h1>
121
  <p>Age: {user.age}</p>
122
</div>
123
```
124

125
## Style Preprocessing
126

127
### Style Processing Options
128

129
Configure CSS, PostCSS, Sass, and other style preprocessing.
130

131
```typescript { .api }
132
interface StyleProcessingOptions {
133
  /** 
134
   * Enable and configure style block preprocessing
135
   * - boolean: enable/disable with default Vite config
136
   * - InlineConfig: provide specific Vite configuration
137
   * - ResolvedConfig: use existing resolved Vite config
138
   */
139
  style?: boolean | InlineConfig | ResolvedConfig;
140
}
141
```
142

143
**Usage Examples:**
144

145
```javascript
146
// Basic style preprocessing (uses default Vite config)
147
export default {
148
  preprocess: vitePreprocess({
149
    style: true
150
  })
151
};
152

153
// Custom Vite configuration for style processing
154
export default {
155
  preprocess: vitePreprocess({
156
    style: {
157
      css: {
158
        devSourcemap: true,
159
        preprocessorOptions: {
160
          scss: {
161
            additionalData: `@import "src/styles/variables.scss";`
162
          },
163
          less: {
164
            modifyVars: {
165
              'primary-color': '#1890ff'
166
            }
167
          }
168
        }
169
      }
170
    }
171
  })
172
};
173

174
// Advanced PostCSS configuration
175
export default {
176
  preprocess: vitePreprocess({
177
    style: {
178
      css: {
179
        postcss: {
180
          plugins: [
181
            require('autoprefixer'),
182
            require('tailwindcss'),
183
            require('postcss-nesting')
184
          ]
185
        }
186
      }
187
    }
188
  })
189
};
190
```
191

192
**Svelte Component Style Examples:**
193

194
```svelte
195
<!-- PostCSS with nesting -->
196
<style lang="postcss">
197
  .card {
198
    padding: 1rem;
199
    border-radius: 0.5rem;
200
    
201
    &:hover {
202
      transform: scale(1.02);
203
    }
204
    
205
    .title {
206
      font-size: 1.25rem;
207
      font-weight: bold;
208
    }
209
  }
210
</style>
211

212
<!-- Sass/SCSS -->
213
<style lang="scss">
214
  $primary-color: #3498db;
215
  
216
  .button {
217
    background-color: $primary-color;
218
    padding: 0.5rem 1rem;
219
    border: none;
220
    border-radius: 0.25rem;
221
    
222
    &:hover {
223
      background-color: darken($primary-color, 10%);
224
    }
225
  }
226
</style>
227

228
<!-- CSS with imports -->
229
<style>
230
  @import 'modern-normalize';
231
  @import './component-styles.css';
232
  
233
  .container {
234
    max-width: 1200px;
235
    margin: 0 auto;
236
  }
237
</style>
238
```
239

240
### CSS Module Support
241

242
Support for CSS modules and scoped styles.
243

244
```svelte
245
<!-- CSS Modules -->
246
<style module>
247
  .button {
248
    background: blue;
249
    color: white;
250
  }
251
</style>
252

253
<script>
254
  // Access CSS module classes
255
  export let styles;
256
</script>
257

258
<button class={styles.button}>Click me</button>
259
```
260

261
### Style Dependencies and Imports
262

263
Handle CSS dependencies and asset imports.
264

265
```svelte
266
<!-- Import external stylesheets -->
267
<style>
268
  @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap');
269
  @import '../styles/global.css';
270
  
271
  /* Local asset imports work through Vite */
272
  .background {
273
    background-image: url('../assets/pattern.svg');
274
  }
275
</style>
276
```
277

278
## Advanced Configuration
279

280
### Integration with Vite Config
281

282
Coordinate preprocessing with your main Vite configuration.
283

284
```javascript
285
// vite.config.js
286
import { defineConfig } from 'vite';
287
import { svelte } from '@sveltejs/vite-plugin-svelte';
288

289
export default defineConfig({
290
  css: {
291
    devSourcemap: true,
292
    preprocessorOptions: {
293
      scss: {
294
        additionalData: '@import "src/styles/variables.scss";'
295
      }
296
    }
297
  },
298
  plugins: [
299
    svelte({
300
      preprocess: vitePreprocess({
301
        style: true // Will use the CSS config above
302
      })
303
    })
304
  ]
305
});
306
```
307

308
### Multiple Preprocessors
309

310
Combine vitePreprocess with other Svelte preprocessors.
311

312
```javascript
313
// svelte.config.js
314
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
315
import { mdsvex } from 'mdsvex';
316

317
export default {
318
  extensions: ['.svelte', '.md'],
319
  preprocess: [
320
    mdsvex({
321
      extensions: ['.md']
322
    }),
323
    vitePreprocess({
324
      style: true
325
    })
326
  ]
327
};
328
```
329

330
### Development vs Production
331

332
Different preprocessing settings for different environments.
333

334
```javascript
335
// svelte.config.js
336
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
337

338
const dev = process.env.NODE_ENV === 'development';
339

340
export default {
341
  preprocess: vitePreprocess({
342
    style: {
343
      css: {
344
        devSourcemap: dev,
345
        minify: !dev
346
      }
347
    }
348
  })
349
};
350
```
351

352
## Error Handling
353

354
The vitePreprocess function handles errors from Vite's transformation pipeline and provides meaningful error messages with source mapping information for debugging.