0
# Svelte Preprocess
1

2
Svelte Preprocess is a comprehensive Svelte preprocessor wrapper that enables developers to use multiple languages and preprocessors within Svelte components. It provides baked-in support for TypeScript, SCSS, Less, Stylus, CoffeeScript, Pug, PostCSS, and Babel with sensible defaults and minimal configuration.
3

4
## Package Information
5

6
- **Package Name**: svelte-preprocess
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install svelte-preprocess`
10

11
## Core Imports
12

13
```typescript
14
import { sveltePreprocess } from "svelte-preprocess";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { sveltePreprocess } = require("svelte-preprocess");
21
```
22

23
Individual processors:
24

25
```typescript
26
import { 
27
  typescript, 
28
  scss, 
29
  sass,
30
  less,
31
  stylus,
32
  postcss, 
33
  babel,
34
  coffeescript,
35
  pug,
36
  globalStyle,
37
  replace
38
} from "svelte-preprocess";
39
```
40

41
## Basic Usage
42

43
```typescript
44
import { sveltePreprocess } from "svelte-preprocess";
45

46
// Basic configuration with default settings
47
const preprocess = sveltePreprocess({
48
  // TypeScript support
49
  typescript: true,
50
  
51
  // SCSS support  
52
  scss: {
53
    prependData: `@import 'src/styles/variables.scss';`
54
  },
55
  
56
  // PostCSS with Autoprefixer
57
  postcss: {
58
    plugins: [require('autoprefixer')]
59
  }
60
});
61

62
export default {
63
  preprocess
64
};
65
```
66

67
## Architecture
68

69
Svelte Preprocess is built around several key components:
70

71
- **Auto Preprocessor**: The main `sveltePreprocess` function that auto-detects languages and applies appropriate processors
72
- **Individual Processors**: Standalone processors for each supported language that can be used independently
73
- **Transform System**: Core transformation engine that handles content processing with source maps and dependency tracking
74
- **Language Detection**: Automatic language detection based on `lang` attributes and file extensions
75
- **Configuration System**: Flexible options system supporting both global and processor-specific configurations
76

77
## Capabilities
78

79
### Auto Preprocessing
80

81
Main preprocessor function that automatically detects and processes different languages within Svelte components. Supports TypeScript, SCSS, Less, Stylus, CoffeeScript, Pug, PostCSS, and Babel.
82

83
```typescript { .api }
84
function sveltePreprocess(options?: AutoPreprocessOptions): AutoPreprocessGroup;
85

86
interface AutoPreprocessOptions {
87
  markupTagName?: string;
88
  aliases?: Array<[string, string]>;
89
  sourceMap?: boolean;
90
  
91
  // Individual processor options
92
  typescript?: TransformerOptions<Options.Typescript>;
93
  babel?: TransformerOptions<Options.Babel>;
94
  scss?: TransformerOptions<Options.Sass>;
95
  sass?: TransformerOptions<Options.Sass>;
96
  less?: TransformerOptions<Options.Less>;
97
  stylus?: TransformerOptions<Options.Stylus>;
98
  postcss?: TransformerOptions<Options.Postcss>;
99
  coffeescript?: TransformerOptions<Options.Coffeescript>;
100
  pug?: TransformerOptions<Options.Pug>;
101
  globalStyle?: Options.GlobalStyle | boolean;
102
  replace?: Options.Replace;
103
  
104
  [languageName: string]: TransformerOptions;
105
}
106

107
type AutoPreprocessGroup = PreprocessorGroup;
108

109
type TransformerOptions<T = any> = boolean | T | Transformer<T>;
110

111
type Transformer<T> = (args: TransformerArgs<T>) => Processed | Promise<Processed>;
112
```
113

114
[Auto Preprocessing](./auto-preprocessing.md)
115

116
### TypeScript Processing
117

118
TypeScript compiler integration with configurable options including tsconfig support and diagnostics reporting.
119

120
```typescript { .api }
121
function typescript(options?: Options.Typescript): PreprocessorGroup;
122

123
namespace Options {
124
  interface Typescript {
125
    compilerOptions?: any;
126
    tsconfigFile?: string | boolean;
127
    tsconfigDirectory?: string | boolean;
128
    reportDiagnostics?: boolean;
129
    prependData?: string;
130
    stripIndent?: boolean;
131
  }
132
}
133
```
134

135
[TypeScript Processing](./typescript.md)
136

137
### CSS Preprocessing
138

139
Support for SCSS, Sass, Less, and Stylus CSS preprocessors with configurable options and automatic dependency tracking.
140

141
```typescript { .api }
142
function scss(options?: Options.Sass): PreprocessorGroup;
143
function sass(options?: Options.Sass): PreprocessorGroup;
144
function less(options?: Options.Less): PreprocessorGroup;
145
function stylus(options?: Options.Stylus): PreprocessorGroup;
146

147
namespace Options {
148
  interface Sass {
149
    // Sass configuration options
150
    prependData?: string;
151
    stripIndent?: boolean;
152
    // Additional Sass options omitted for brevity
153
  }
154
  
155
  interface Less {
156
    paths?: string[];
157
    plugins?: any[];
158
    globalVars?: Record<string, string>;
159
    modifyVars?: Record<string, string>;
160
    prependData?: string;
161
    stripIndent?: boolean;
162
  }
163
  
164
  interface Stylus {
165
    globals?: Record<string, any>;
166
    functions?: Record<string, any>;
167
    imports?: string[];
168
    paths?: string[];
169
    sourcemap?: boolean;
170
    prependData?: string;
171
    stripIndent?: boolean;
172
  }
173
}
174
```
175

176
[CSS Preprocessing](./css-preprocessing.md)
177

178
### PostCSS Processing
179

180
PostCSS integration with plugin support and automatic configuration loading.
181

182
```typescript { .api }
183
function postcss(options?: Options.Postcss): PreprocessorGroup;
184

185
namespace Options {
186
  interface Postcss {
187
    plugins?: any[]; // postcss.AcceptedPlugin[]
188
    configFilePath?: string;
189
    prependData?: string;
190
    stripIndent?: boolean;
191
    // Additional PostCSS options from postcss.ProcessOptions
192
  }
193
}
194
```
195

196
[PostCSS Processing](./postcss.md)
197

198
### JavaScript Processing
199

200
Babel integration for modern JavaScript transformation and CoffeeScript compilation support.
201

202
```typescript { .api }
203
function babel(options?: Options.Babel): PreprocessorGroup;
204
function coffeescript(options?: Options.Coffeescript): PreprocessorGroup;
205

206
namespace Options {
207
  interface Babel {
208
    sourceType?: 'module';
209
    minified?: false;
210
    ast?: false;
211
    code?: true;
212
    sourceMaps?: boolean;
213
    prependData?: string;
214
    stripIndent?: boolean;
215
    // Additional Babel options from @babel/core TransformOptions
216
  }
217
  
218
  interface Coffeescript {
219
    sourceMap?: boolean;
220
    filename?: never;
221
    bare?: never;
222
    prependData?: string;
223
    stripIndent?: boolean;
224
  }
225
}
226
```
227

228
[JavaScript Processing](./javascript.md)
229

230
### Template Processing
231

232
Pug template engine integration for markup preprocessing and global style handling.
233

234
```typescript { .api }
235
function pug(options?: Options.Pug): PreprocessorGroup;
236
function globalStyle(): PreprocessorGroup;
237

238
namespace Options {
239
  interface Pug {
240
    markupTagName?: string;
241
    prependData?: string;
242
    stripIndent?: boolean;
243
    // Additional Pug options from pug.Options (excluding filename, doctype, compileDebug)
244
  }
245
  
246
  interface GlobalStyle {
247
    sourceMap: boolean;
248
  }
249
}
250
```
251

252
[Template Processing](./template-processing.md)
253

254
### Utility Processing
255

256
String replacement and content manipulation utilities.
257

258
```typescript { .api }
259
function replace(options: Options.Replace): PreprocessorGroup;
260

261
namespace Options {
262
  type Replace = Array<
263
    | [string | RegExp, string]
264
    | [RegExp, (substring: string, ...args: any[]) => string]
265
  >;
266
}
267
```
268

269
[Utility Processing](./utility-processing.md)
270

271
## Core Types
272

273
```typescript { .api }
274
interface TransformerArgs<T> {
275
  content: string;
276
  filename?: string;
277
  attributes?: Record<string, any>;
278
  map?: string | object;
279
  markup?: string;
280
  diagnostics?: unknown[];
281
  options?: T;
282
}
283

284
interface Processed {
285
  code: string;
286
  map?: string | object;
287
  dependencies?: string[];
288
  diagnostics?: any[];
289
}
290

291
// Re-exported from svelte/compiler
292
interface PreprocessorGroup {
293
  markup?: (options: { content: string; filename?: string }) => Processed | Promise<Processed>;
294
  script?: (options: { content: string; attributes: Record<string, any>; markup: string; filename?: string }) => Processed | Promise<Processed>;
295
  style?: (options: { content: string; attributes: Record<string, any>; markup: string; filename?: string }) => Processed | Promise<Processed>;
296
}
297
```