0
# Auto Preprocessing
1

2
The main `sveltePreprocess` function provides automatic language detection and processing for Svelte components. It creates a complete preprocessor group that handles markup, script, and style preprocessing based on `lang` attributes.
3

4
## Capabilities
5

6
### sveltePreprocess Function
7

8
Creates an auto-detecting preprocessor that supports multiple languages with a single configuration.
9

10
```typescript { .api }
11
/**
12
 * Creates a Svelte preprocessor group with automatic language detection
13
 * @param options - Configuration options for the preprocessor
14
 * @returns PreprocessorGroup for use with Svelte compiler
15
 */
16
function sveltePreprocess(options?: AutoPreprocessOptions): AutoPreprocessGroup;
17

18
interface AutoPreprocessOptions {
19
  /** Tag name for markup sections (default: 'template') */
20
  markupTagName?: string;
21
  
22
  /** Language aliases for custom language detection */
23
  aliases?: Array<[string, string]>;
24
  
25
  /** Enable source map generation (default: false, true in development) */
26
  sourceMap?: boolean;
27
  
28
  // Individual processor configurations
29
  /** TypeScript compiler options */
30
  typescript?: TransformerOptions<Options.Typescript>;
31
  
32
  /** Babel transformer options */
33
  babel?: TransformerOptions<Options.Babel>;
34
  
35
  /** SCSS preprocessor options */
36
  scss?: TransformerOptions<Options.Sass>;
37
  
38
  /** Sass preprocessor options (alias for scss with indented syntax) */
39
  sass?: TransformerOptions<Options.Sass>;
40
  
41
  /** Less preprocessor options */
42
  less?: TransformerOptions<Options.Less>;
43
  
44
  /** Stylus preprocessor options */
45
  stylus?: TransformerOptions<Options.Stylus>;
46
  
47
  /** PostCSS processor options */
48
  postcss?: TransformerOptions<Options.Postcss>;
49
  
50
  /** CoffeeScript compiler options */
51
  coffeescript?: TransformerOptions<Options.Coffeescript>;
52
  
53
  /** Pug template engine options */
54
  pug?: TransformerOptions<Options.Pug>;
55
  
56
  /** Global style processor options */
57
  globalStyle?: Options.GlobalStyle | boolean;
58
  
59
  /** String replacement patterns */
60
  replace?: Options.Replace;
61
  
62
  /** Additional language processors */
63
  [languageName: string]: TransformerOptions;
64
}
65

66
type AutoPreprocessGroup = PreprocessorGroup;
67

68
type TransformerOptions<T = any> = boolean | T | Transformer<T>;
69

70
type Transformer<T> = (args: TransformerArgs<T>) => Processed | Promise<Processed>;
71
```
72

73
**Usage Examples:**
74

75
```typescript
76
import { sveltePreprocess } from "svelte-preprocess";
77

78
// Basic configuration
79
const preprocess = sveltePreprocess({
80
  typescript: true,
81
  scss: true,
82
  postcss: true
83
});
84

85
// Advanced configuration
86
const preprocess = sveltePreprocess({
87
  sourceMap: true,
88
  markupTagName: 'template',
89
  
90
  typescript: {
91
    tsconfigFile: './tsconfig.json',
92
    reportDiagnostics: true
93
  },
94
  
95
  scss: {
96
    prependData: `
97
      @import 'src/styles/variables.scss';
98
      @import 'src/styles/mixins.scss';
99
    `
100
  },
101
  
102
  postcss: {
103
    plugins: [
104
      require('autoprefixer'),
105
      require('cssnano')({ preset: 'default' })
106
    ]
107
  },
108
  
109
  babel: {
110
    presets: [['@babel/preset-env', { targets: '> 0.25%' }]]
111
  }
112
});
113

114
// With language aliases
115
const preprocess = sveltePreprocess({
116
  aliases: [
117
    ['customcss', 'scss'],
118
    ['customjs', 'typescript']
119
  ],
120
  
121
  scss: { /* scss options */ },
122
  typescript: { /* typescript options */ }
123
});
124
```
125

126
### Language Detection
127

128
The preprocessor automatically detects languages based on:
129

130
1. **`lang` attribute**: `<script lang="ts">`, `<style lang="scss">`
131
2. **File extensions**: For external file imports
132
3. **Custom aliases**: User-defined language mappings
133

134
**Supported Languages:**
135

136
- **Script**: `typescript`, `ts`, `coffeescript`, `coffee`, `babel`, `js`
137
- **Style**: `scss`, `sass`, `less`, `stylus`, `postcss`, `pcss`, `sugarss`, `sss`
138
- **Markup**: `pug`, `jade`
139

140
### Processing Pipeline
141

142
The auto preprocessor follows this processing order:
143

144
1. **Replace Processing**: String replacements applied to markup (if configured)
145
2. **Markup Processing**: Pug or other markup preprocessors
146
3. **Script Processing**: Language-specific script processing, followed by optional Babel transformation
147
4. **Style Processing**: CSS preprocessor processing, followed by PostCSS and global style handling
148

149
### Configuration Patterns
150

151
```typescript
152
// Minimal configuration - enable preprocessors with defaults
153
const preprocess = sveltePreprocess({
154
  typescript: true,
155
  scss: true
156
});
157

158
// Function-based custom processing
159
const preprocess = sveltePreprocess({
160
  typescript: ({ content, filename, attributes }) => {
161
    // Custom TypeScript processing logic
162
    return { code: processedContent };
163
  }
164
});
165

166
// Mixed configuration
167
const preprocess = sveltePreprocess({
168
  typescript: true, // Use default options
169
  
170
  scss: {
171
    // Custom SCSS options
172
    includePaths: ['src/styles', 'node_modules']
173
  },
174
  
175
  babel: ({ content, filename }) => {
176
    // Custom Babel processing
177
    return require('@babel/core').transform(content, {
178
      filename,
179
      presets: ['@babel/preset-env']
180
    });
181
  }
182
});
183
```
184

185
### Source Maps
186

187
Source map generation can be controlled globally or per-processor:
188

189
```typescript
190
const preprocess = sveltePreprocess({
191
  // Global source map setting
192
  sourceMap: process.env.NODE_ENV === 'development',
193
  
194
  typescript: {
195
    // TypeScript-specific source map options
196
    compilerOptions: {
197
      sourceMap: true,
198
      inlineSourceMap: false
199
    }
200
  },
201
  
202
  scss: {
203
    // SCSS source maps handled automatically based on global setting
204
  }
205
});
206
```
207

208
## Core Transform Function
209

210
Internal transformation function used by the auto preprocessor.
211

212
```typescript { .api }
213
/**
214
 * Core transformation function used internally by the auto preprocessor
215
 * @param name - Language/processor name
216
 * @param options - Transformer options
217
 * @param args - Transformation arguments
218
 * @returns Processed result with code, map, and dependencies
219
 */
220
function transform(
221
  name: string | null | undefined,
222
  options: TransformerOptions,
223
  args: TransformerArgs<any>
224
): Promise<Processed>;
225
```
226

227
## Types
228

229
```typescript { .api }
230
interface TransformerArgs<T> {
231
  /** Source content to transform */
232
  content: string;
233
  
234
  /** Source filename for error reporting and source maps */
235
  filename?: string;
236
  
237
  /** Element attributes from the Svelte component */
238
  attributes?: Record<string, any>;
239
  
240
  /** Source map from previous transformations */
241
  map?: string | object;
242
  
243
  /** Full markup content for context */
244
  markup?: string;
245
  
246
  /** Diagnostics from previous transformations */
247
  diagnostics?: unknown[];
248
  
249
  /** Processor-specific options */
250
  options?: T;
251
}
252

253
interface Processed {
254
  /** Transformed code */
255
  code: string;
256
  
257
  /** Source map */
258
  map?: string | object;
259
  
260
  /** File dependencies for watch mode */
261
  dependencies?: string[];
262
  
263
  /** TypeScript or other diagnostics */
264
  diagnostics?: any[];
265
}
266
```