0
# CSS Preprocessing
1

2
Support for SCSS, Sass, Less, and Stylus CSS preprocessors with configurable options, dependency tracking, and automatic source map generation.
3

4
## Capabilities
5

6
### SCSS/Sass Processing
7

8
SCSS and Sass preprocessor support with full Sass language features and configuration options.
9

10
```typescript { .api }
11
/**
12
 * Creates SCSS preprocessor for style blocks
13
 * @param options - SCSS/Sass configuration options
14
 * @returns PreprocessorGroup with style preprocessing
15
 */
16
function scss(options?: Options.Sass): PreprocessorGroup;
17

18
/**
19
 * Creates Sass preprocessor (indented syntax) for style blocks
20
 * @param options - Sass configuration options (automatically enables indented syntax)
21
 * @returns PreprocessorGroup with style preprocessing
22
 */
23
function sass(options?: Options.Sass): PreprocessorGroup;
24

25
namespace Options {
26
  interface Sass {
27
    /** Content to prepend to every file */
28
    prependData?: string;
29
    
30
    /** Remove common leading whitespace */
31
    stripIndent?: boolean;
32
    
33
    // Additional Sass/SCSS options (subset of Sass LegacyStringOptions)
34
    // Excludes 'file' and 'data' which are handled internally
35
  }
36
}
37
```
38

39
**Usage Examples:**
40

41
```typescript
42
import { scss, sass } from "svelte-preprocess";
43

44
// Basic SCSS support
45
const preprocess = {
46
  style: scss()
47
};
48

49
// SCSS with global imports
50
const preprocess = {
51
  style: scss({
52
    prependData: `
53
      @import 'src/styles/variables.scss';
54
      @import 'src/styles/mixins.scss';
55
    `
56
  })
57
};
58

59
// Sass indented syntax
60
const preprocess = {
61
  style: sass({
62
    prependData: `
63
      @import 'src/styles/variables'
64
      @import 'src/styles/mixins'
65
    `
66
  })
67
};
68
```
69

70
### Less Processing
71

72
Less CSS preprocessor integration with variable support and plugin configuration.
73

74
```typescript { .api }
75
/**
76
 * Creates Less preprocessor for style blocks
77
 * @param options - Less configuration options
78
 * @returns PreprocessorGroup with style preprocessing
79
 */
80
function less(options?: Options.Less): PreprocessorGroup;
81

82
namespace Options {
83
  interface Less {
84
    /** Import paths for @import statements */
85
    paths?: string[];
86
    
87
    /** Less plugins */
88
    plugins?: any[];
89
    
90
    /** Enable strict import checking */
91
    strictImports?: boolean;
92
    
93
    /** Maximum line length for output */
94
    maxLineLen?: number;
95
    
96
    /** Line number output format */
97
    dumpLineNumbers?: 'comment' | string;
98
    
99
    /** Suppress output */
100
    silent?: boolean;
101
    
102
    /** Enforce strict unit checking */
103
    strictUnits?: boolean;
104
    
105
    /** Global variables */
106
    globalVars?: Record<string, string>;
107
    
108
    /** Variables to modify */
109
    modifyVars?: Record<string, string>;
110
    
111
    /** Content to prepend to every file */
112
    prependData?: string;
113
    
114
    /** Remove common leading whitespace */
115
    stripIndent?: boolean;
116
  }
117
}
118
```
119

120
**Usage Examples:**
121

122
```typescript
123
import { less } from "svelte-preprocess";
124

125
// Basic Less support
126
const preprocess = {
127
  style: less()
128
};
129

130
// Less with custom configuration
131
const preprocess = {
132
  style: less({
133
    paths: ['src/styles', 'node_modules'],
134
    globalVars: {
135
      primaryColor: '#3498db',
136
      fontSize: '16px'
137
    },
138
    modifyVars: {
139
      'theme-color': '#e74c3c'
140
    }
141
  })
142
};
143

144
// Less with prepended variables
145
const preprocess = {
146
  style: less({
147
    prependData: `
148
      @import 'variables.less';
149
      @base-font-size: 16px;
150
    `
151
  })
152
};
153
```
154

155
### Stylus Processing
156

157
Stylus CSS preprocessor with support for functions, mixins, and custom configuration.
158

159
```typescript { .api }
160
/**
161
 * Creates Stylus preprocessor for style blocks
162
 * @param options - Stylus configuration options
163
 * @returns PreprocessorGroup with style preprocessing
164
 */
165
function stylus(options?: Options.Stylus): PreprocessorGroup;
166

167
namespace Options {
168
  interface Stylus {
169
    /** Global variables */
170
    globals?: Record<string, any>;
171
    
172
    /** Custom functions */
173
    functions?: Record<string, any>;
174
    
175
    /** Files to import automatically */
176
    imports?: string[];
177
    
178
    /** Import paths */
179
    paths?: string[];
180
    
181
    /** Enable source map generation */
182
    sourcemap?: boolean;
183
    
184
    /** Content to prepend to every file */
185
    prependData?: string;
186
    
187
    /** Remove common leading whitespace */
188
    stripIndent?: boolean;
189
  }
190
}
191
```
192

193
**Usage Examples:**
194

195
```typescript
196
import { stylus } from "svelte-preprocess";
197

198
// Basic Stylus support
199
const preprocess = {
200
  style: stylus()
201
};
202

203
// Stylus with globals and functions
204
const preprocess = {
205
  style: stylus({
206
    globals: {
207
      'primary-color': '#3498db',
208
      'base-font': 'Arial, sans-serif'
209
    },
210
    
211
    functions: {
212
      // Custom Stylus functions
213
      'rem': (px) => (px / 16) + 'rem'
214
    },
215
    
216
    imports: [
217
      'src/styles/variables.styl',
218
      'src/styles/mixins.styl'
219
    ]
220
  })
221
};
222

223
// Stylus with paths and imports
224
const preprocess = {
225
  style: stylus({
226
    paths: ['src/styles', 'node_modules'],
227
    prependData: `
228
      @import 'variables'
229
      @import 'mixins'
230
    `
231
  })
232
};
233
```
234

235
## Integration with Auto Preprocessor
236

237
All CSS preprocessors integrate seamlessly with the auto preprocessor:
238

239
```typescript
240
import { sveltePreprocess } from "svelte-preprocess";
241

242
const preprocess = sveltePreprocess({
243
  // Enable multiple CSS preprocessors
244
  scss: {
245
    prependData: `@import 'src/styles/variables.scss';`
246
  },
247
  
248
  less: {
249
    paths: ['src/styles'],
250
    globalVars: { primaryColor: '#007acc' }
251
  },
252
  
253
  stylus: {
254
    imports: ['src/styles/mixins.styl']
255
  }
256
});
257
```
258

259
The auto preprocessor detects CSS preprocessors based on:
260
- `<style lang="scss">`, `<style lang="sass">`
261
- `<style lang="less">`
262
- `<style lang="stylus">`, `<style lang="styl">`
263
- External file extensions
264

265
## Common Configuration Patterns
266

267
### Global Variable Import
268

269
```typescript
270
// SCSS
271
const preprocess = sveltePreprocess({
272
  scss: {
273
    prependData: `
274
      @import 'src/lib/styles/variables.scss';
275
      @import 'src/lib/styles/mixins.scss';
276
    `
277
  }
278
});
279

280
// Less
281
const preprocess = sveltePreprocess({
282
  less: {
283
    prependData: `@import 'src/lib/styles/variables.less';`,
284
    globalVars: {
285
      'theme-primary': '#007acc'
286
    }
287
  }
288
});
289

290
// Stylus
291
const preprocess = sveltePreprocess({
292
  stylus: {
293
    imports: ['src/lib/styles/variables.styl'],
294
    globals: {
295
      'primary-color': '#007acc'
296
    }
297
  }
298
});
299
```
300

301
### Development vs Production
302

303
```typescript
304
const isDev = process.env.NODE_ENV === 'development';
305

306
const preprocess = sveltePreprocess({
307
  scss: {
308
    // Include debug information in development
309
    outputStyle: isDev ? 'expanded' : 'compressed',
310
    sourceMap: isDev,
311
    
312
    prependData: `
313
      $env: ${isDev ? 'development' : 'production'};
314
      @import 'src/styles/variables.scss';
315
    `
316
  }
317
});
318
```
319

320
### Monorepo Setup
321

322
```typescript
323
const preprocess = sveltePreprocess({
324
  scss: {
325
    includePaths: [
326
      'packages/ui/src/styles',
327
      'packages/shared/styles',
328
      'node_modules'
329
    ],
330
    
331
    prependData: `
332
      @import 'packages/shared/styles/variables';
333
      @import 'packages/ui/src/styles/mixins';
334
    `
335
  }
336
});
337
```
338

339
## Source Maps and Dependencies
340

341
All CSS preprocessors automatically handle:
342

343
- **Source Maps**: Generated when `sourceMap: true` in auto preprocessor options
344
- **Dependencies**: File imports are tracked for hot reload and watch mode
345
- **Error Reporting**: Compilation errors include source location information
346

347
```typescript
348
// Source maps enabled globally
349
const preprocess = sveltePreprocess({
350
  sourceMap: true, // Enables source maps for all preprocessors
351
  
352
  scss: {
353
    // SCSS-specific options
354
  }
355
});
356
```
357

358
## Types
359

360
```typescript { .api }
361
interface SassOptions {
362
  prependData?: string;
363
  stripIndent?: boolean;
364
  // Additional Sass compiler options (LegacyStringOptions<'sync'> excluding 'file' | 'data')
365
}
366

367
interface LessOptions {
368
  paths?: string[];
369
  plugins?: any[];
370
  strictImports?: boolean;
371
  maxLineLen?: number;
372
  dumpLineNumbers?: 'comment' | string;
373
  silent?: boolean;
374
  strictUnits?: boolean;
375
  globalVars?: Record<string, string>;
376
  modifyVars?: Record<string, string>;
377
  prependData?: string;
378
  stripIndent?: boolean;
379
}
380

381
interface StylusOptions {
382
  globals?: Record<string, any>;
383
  functions?: Record<string, any>;
384
  imports?: string[];
385
  paths?: string[];
386
  sourcemap?: boolean;
387
  prependData?: string;
388
  stripIndent?: boolean;
389
}
390
```