0
# PostCSS Processing
1

2
PostCSS integration with plugin support, automatic configuration loading, and seamless integration with other CSS preprocessors.
3

4
## Capabilities
5

6
### PostCSS Preprocessor
7

8
PostCSS processor that can be used standalone or automatically applied after other CSS preprocessors.
9

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

18
namespace Options {
19
  interface Postcss {
20
    /** PostCSS plugins array */
21
    plugins?: any[]; // postcss.AcceptedPlugin[]
22
    
23
    /** Path to PostCSS config file */
24
    configFilePath?: string;
25
    
26
    /** Content to prepend to every file */
27
    prependData?: string;
28
    
29
    /** Remove common leading whitespace */
30
    stripIndent?: boolean;
31
    
32
    // Additional PostCSS process options
33
    // Inherits from postcss.ProcessOptions
34
  }
35
}
36
```
37

38
**Usage Examples:**
39

40
```typescript
41
import { postcss } from "svelte-preprocess";
42

43
// Basic PostCSS with Autoprefixer
44
const preprocess = {
45
  style: postcss({
46
    plugins: [
47
      require('autoprefixer')
48
    ]
49
  })
50
};
51

52
// PostCSS with multiple plugins
53
const preprocess = {
54
  style: postcss({
55
    plugins: [
56
      require('autoprefixer'),
57
      require('cssnano')({
58
        preset: ['default', {
59
          discardComments: { removeAll: true }
60
        }]
61
      }),
62
      require('postcss-custom-properties'),
63
      require('postcss-nesting')
64
    ]
65
  })
66
};
67

68
// Using PostCSS config file
69
const preprocess = {
70
  style: postcss({
71
    configFilePath: './postcss.config.js'
72
  })
73
};
74
```
75

76
### Configuration File Loading
77

78
PostCSS can automatically load configuration from standard config files:
79

80
```typescript
81
// Automatically loads postcss.config.js, .postcssrc, etc.
82
const preprocess = {
83
  style: postcss() // No options needed
84
};
85

86
// Specify custom config file path
87
const preprocess = {
88
  style: postcss({
89
    configFilePath: './config/postcss.config.js'
90
  })
91
};
92

93
// Override config file plugins
94
const preprocess = {
95
  style: postcss({
96
    configFilePath: './postcss.config.js',
97
    plugins: [
98
      // Additional plugins or overrides
99
      require('postcss-custom-media')
100
    ]
101
  })
102
};
103
```
104

105
### Integration with Auto Preprocessor
106

107
PostCSS is automatically applied after other CSS preprocessors when using the auto preprocessor:
108

109
```typescript
110
import { sveltePreprocess } from "svelte-preprocess";
111

112
const preprocess = sveltePreprocess({
113
  // SCSS processed first, then PostCSS
114
  scss: {
115
    prependData: `@import 'variables.scss';`
116
  },
117
  
118
  // PostCSS applied to all styles (including SCSS output)
119
  postcss: {
120
    plugins: [
121
      require('autoprefixer'),
122
      require('postcss-preset-env')
123
    ]
124
  }
125
});
126
```
127

128
Processing order in auto preprocessor:
129
1. CSS preprocessor (SCSS, Less, Stylus)
130
2. PostCSS processing
131
3. Global style handling
132

133
### Common Plugin Configurations
134

135
```typescript
136
// Production optimization
137
const preprocess = {
138
  style: postcss({
139
    plugins: [
140
      require('autoprefixer'),
141
      require('postcss-preset-env')({
142
        stage: 2,
143
        features: {
144
          'nesting-rules': true,
145
          'custom-properties': true
146
        }
147
      }),
148
      process.env.NODE_ENV === 'production' && require('cssnano')({
149
        preset: ['default', {
150
          discardComments: { removeAll: true },
151
          normalizeWhitespace: true
152
        }]
153
      })
154
    ].filter(Boolean)
155
  })
156
};
157

158
// Design system utilities
159
const preprocess = {
160
  style: postcss({
161
    plugins: [
162
      require('postcss-import'),
163
      require('tailwindcss'),
164
      require('postcss-nested'),
165
      require('autoprefixer')
166
    ]
167
  })
168
};
169

170
// CSS-in-JS style features
171
const preprocess = {
172
  style: postcss({
173
    plugins: [
174
      require('postcss-custom-properties'),
175
      require('postcss-color-function'),
176
      require('postcss-calc'),
177
      require('postcss-custom-media')
178
    ]
179
  })
180
};
181
```
182

183
### Global Style Processing
184

185
PostCSS integrates with the global style processor for handling `global` attributes:
186

187
```svelte
188
<!-- This style will be processed by PostCSS then made global -->
189
<style lang="scss" global>
190
  @import 'global-styles.scss';
191
  
192
  body {
193
    font-family: system-ui;
194
  }
195
</style>
196
```
197

198
```typescript
199
const preprocess = sveltePreprocess({
200
  scss: true,
201
  
202
  postcss: {
203
    plugins: [require('autoprefixer')]
204
  },
205
  
206
  // Global style processing happens after PostCSS
207
  globalStyle: true
208
});
209
```
210

211
### Development vs Production
212

213
```typescript
214
const isDev = process.env.NODE_ENV === 'development';
215

216
const preprocess = sveltePreprocess({
217
  postcss: {
218
    plugins: [
219
      require('postcss-import'),
220
      require('autoprefixer'),
221
      
222
      // Development plugins
223
      isDev && require('postcss-reporter')({
224
        clearReportedMessages: true
225
      }),
226
      
227
      // Production plugins
228
      !isDev && require('postcss-preset-env')({
229
        stage: 1
230
      }),
231
      
232
      !isDev && require('cssnano')({
233
        preset: 'default'
234
      })
235
    ].filter(Boolean)
236
  }
237
});
238
```
239

240
### Tailwind CSS Integration
241

242
```typescript
243
// Tailwind CSS with PostCSS
244
const preprocess = sveltePreprocess({
245
  postcss: {
246
    plugins: [
247
      require('postcss-import'),
248
      require('tailwindcss'),
249
      require('autoprefixer'),
250
      
251
      // Production optimization
252
      process.env.NODE_ENV === 'production' && require('@fullhuman/postcss-purgecss')({
253
        content: ['./src/**/*.{html,js,svelte,ts}'],
254
        defaultExtractor: content => content.match(/[\w-/:]+(?<!:)/g) || []
255
      })
256
    ].filter(Boolean)
257
  }
258
});
259
```
260

261
### Custom Properties and Modern CSS
262

263
```typescript
264
const preprocess = {
265
  style: postcss({
266
    plugins: [
267
      // CSS imports
268
      require('postcss-import'),
269
      
270
      // Modern CSS features
271
      require('postcss-preset-env')({
272
        stage: 2,
273
        features: {
274
          'custom-properties': {
275
            preserve: false // Convert to static values
276
          },
277
          'color-mod-function': true,
278
          'nesting-rules': true
279
        }
280
      }),
281
      
282
      // Fallbacks
283
      require('autoprefixer'),
284
      
285
      // Optimization
286
      require('postcss-combine-duplicated-selectors'),
287
      require('postcss-merge-rules')
288
    ]
289
  })
290
};
291
```
292

293
## Advanced Configuration
294

295
### Plugin Order and Dependencies
296

297
```typescript
298
const preprocess = {
299
  style: postcss({
300
    plugins: [
301
      // 1. Import resolution (must be first)
302
      require('postcss-import'),
303
      
304
      // 2. Syntax transformations
305
      require('postcss-nested'),
306
      require('postcss-custom-properties'),
307
      
308
      // 3. Vendor prefixes
309
      require('autoprefixer'),
310
      
311
      // 4. Optimization (must be last)
312
      require('cssnano')
313
    ]
314
  })
315
};
316
```
317

318
### Source Maps
319

320
```typescript
321
const preprocess = sveltePreprocess({
322
  sourceMap: true, // Enables source maps for PostCSS
323
  
324
  postcss: {
325
    plugins: [require('autoprefixer')]
326
    // Source maps handled automatically
327
  }
328
});
329
```
330

331
### Error Handling
332

333
```typescript
334
const preprocess = {
335
  style: postcss({
336
    plugins: [
337
      require('postcss-reporter')({
338
        clearReportedMessages: true,
339
        throwError: process.env.NODE_ENV === 'production'
340
      })
341
    ]
342
  })
343
};
344
```
345

346
## Types
347

348
```typescript { .api }
349
interface PostcssOptions {
350
  /** Array of PostCSS plugins */
351
  plugins?: Array<any>; // postcss.AcceptedPlugin[]
352
  
353
  /** Path to PostCSS configuration file */
354
  configFilePath?: string;
355
  
356
  /** Content to prepend to source */
357
  prependData?: string;
358
  
359
  /** Remove leading whitespace */
360
  stripIndent?: boolean;
361
  
362
  // Additional options from postcss.ProcessOptions:
363
  /** Override the source file path for error reporting */
364
  from?: string;
365
  
366
  /** Set the destination file path for source maps */
367
  to?: string;
368
  
369
  /** Enable or configure parser */
370
  parser?: any;
371
  
372
  /** Enable or configure stringifier */
373
  stringifier?: any;
374
  
375
  /** Enable or configure syntax */
376
  syntax?: any;
377
}
378
```