0
# CSS Processing
1

2
CSS file compilation and processing system supporting multiple preprocessors, PostCSS integration, and custom rendering pipelines.
3

4
## Capabilities
5

6
### File Type Detection
7

8
Automatic detection of CSS file types based on file extensions.
9

10
```typescript { .api }
11
/**
12
 * Supported CSS file types
13
 */
14
enum FileType {
15
  css = 'css',
16
  less = 'less',
17
  sass = 'sass',
18
  scss = 'scss',
19
  styl = 'styl'
20
}
21

22
/**
23
 * Determines CSS file type from filename extension
24
 * @param fileName - Path to the CSS file
25
 * @returns FileType enum value
26
 */
27
function getFileType(fileName: string): FileType;
28
```
29

30
**Usage Examples:**
31

32
```typescript
33
// The plugin automatically detects file types:
34
// component.module.css -> FileType.css
35
// styles.module.scss -> FileType.scss
36
// theme.module.sass -> FileType.sass
37
// layout.module.less -> FileType.less
38
// animations.module.styl -> FileType.styl
39
```
40

41
### Custom Renderer System
42

43
Extensible system for implementing custom CSS processing pipelines.
44

45
```typescript { .api }
46
/**
47
 * Custom renderer function type
48
 */
49
type CustomRenderer = (
50
  css: string,
51
  options: CustomRendererOptions
52
) => string | {
53
  css: string;
54
  sourceMap?: RawSourceMap;
55
};
56

57
/**
58
 * Options passed to custom renderer functions
59
 */
60
interface CustomRendererOptions {
61
  /** Current file being processed */
62
  fileName: string;
63
  /** Logger instance for debugging */
64
  logger: Logger;
65
  /** TypeScript compiler options */
66
  compilerOptions: tsModule.CompilerOptions;
67
}
68
```
69

70
**Custom Renderer Implementation:**
71

72
```javascript
73
// customRenderer.js
74
module.exports = (css, { fileName, logger }) => {
75
  try {
76
    // Custom processing logic
77
    const processedCss = css.replace(/\$primary-color/g, '#007bff');
78
    
79
    return {
80
      css: processedCss,
81
      sourceMap: null // Optional source map
82
    };
83
  } catch (error) {
84
    logger.error(error.message);
85
    return css; // Return original on error
86
  }
87
};
88
```
89

90
**Configuration:**
91

92
```json
93
{
94
  "compilerOptions": {
95
    "plugins": [
96
      {
97
        "name": "typescript-plugin-css-modules",
98
        "options": {
99
          "customRenderer": "./customRenderer.js"
100
        }
101
      }
102
    ]
103
  }
104
}
105
```
106

107
### PostCSS Integration
108

109
Built-in PostCSS processor for handling CSS transformations and plugin execution.
110

111
```typescript { .api }
112
/**
113
 * Creates PostCSS processor instance
114
 * @param userPlugins - Array of PostCSS plugins
115
 * @returns PostCSS Processor instance
116
 */
117
function getProcessor(userPlugins: AcceptedPlugin[]): Processor;
118

119
/**
120
 * Filters PostCSS plugins based on exclusion rules
121
 * @param config - Plugin filtering configuration
122
 * @returns Filtered plugins array
123
 */
124
function filterPlugins(config: {
125
  plugins: AcceptedPlugin[];
126
  exclude?: string[];
127
}): AcceptedPlugin[];
128
```
129

130
**Usage Examples:**
131

132
```json
133
{
134
  "compilerOptions": {
135
    "plugins": [
136
      {
137
        "name": "typescript-plugin-css-modules",
138
        "options": {
139
          "postcssOptions": {
140
            "useConfig": true,
141
            "excludePlugins": ["postcss-mixins"]
142
          }
143
        }
144
      }
145
    ]
146
  }
147
}
148
```
149

150
With a `postcss.config.js`:
151

152
```javascript
153
module.exports = {
154
  plugins: [
155
    require('postcss-nested'),
156
    require('postcss-preset-env'),
157
    require('postcss-mixins') // Will be excluded
158
  ]
159
};
160
```
161

162
### CSS Export Extraction
163

164
System for extracting CSS class names and generating TypeScript-compatible exports.
165

166
```typescript { .api }
167
/**
168
 * CSS exports extraction configuration
169
 */
170
interface CSSExportConfig {
171
  /** CSS content to process */
172
  css: string;
173
  /** Source file name */
174
  fileName: string;
175
  /** Logger instance */
176
  logger: Logger;
177
  /** Plugin options */
178
  options: Options;
179
  /** PostCSS processor */
180
  processor: Processor;
181
  /** TypeScript compiler options */
182
  compilerOptions: tsModule.CompilerOptions;
183
  /** Project directory */
184
  directory: string;
185
}
186

187
/**
188
 * CSS exports with optional source map
189
 */
190
interface CSSExportsWithSourceMap {
191
  /** Extracted CSS class names */
192
  classes: CSSExports;
193
  /** Optional source map */
194
  sourceMap?: RawSourceMap;
195
}
196
```
197

198
### Sass Tilde Importer
199

200
Custom Sass importer for resolving Webpack-style tilde imports from node_modules.
201

202
```typescript { .api }
203
/**
204
 * Resolves tilde-prefixed URLs to node_modules paths
205
 * @param url - Import URL starting with ~
206
 * @param extensions - File extensions to try (default: ['scss', 'sass', 'css'])
207
 * @returns Array of possible file paths to try
208
 */
209
function resolveUrls(url: string, extensions?: string[]): string[];
210

211
/**
212
 * Sass file importer for tilde imports
213
 */
214
const sassTildeImporter: sass.FileImporter<'sync'>;
215
```
216

217
**Usage Examples:**
218

219
In Sass files, you can now use:
220

221
```scss
222
// These imports are resolved by the tilde importer
223
@import '~bootstrap/scss/variables';
224
@import '~@fortawesome/fontawesome-free/scss/fontawesome';
225
@import '~some-package/styles/theme';
226
```
227

228
The importer resolves these to:
229

230
```scss
231
// Actual resolved paths
232
@import 'node_modules/bootstrap/scss/variables';
233
@import 'node_modules/@fortawesome/fontawesome-free/scss/fontawesome';
234
@import 'node_modules/some-package/styles/theme';
235
```
236

237
### Class Name Transformations
238

239
System for transforming CSS class names to match different naming conventions.
240

241
```typescript { .api }
242
/**
243
 * Creates class name transformation function
244
 * @param camelCaseOption - Transformation mode
245
 * @returns Function that transforms a class name to an array of variants
246
 */
247
function transformClasses(
248
  camelCaseOption?: ClassnameTransformOptions
249
): (classname: string) => string[];
250
```
251

252
**Usage Examples:**
253

254
```typescript
255
// With classnameTransform: "camelCase"
256
// CSS: .my-component-header
257
// Available as: styles['my-component-header'] and styles.myComponentHeader
258

259
// With classnameTransform: "camelCaseOnly"  
260
// CSS: .my-component-header
261
// Available as: styles.myComponentHeader only
262

263
// With classnameTransform: "dashes"
264
// CSS: .my_component_header  
265
// Available as: styles['my_component_header'] and styles.myComponentHeader
266
```
267

268
### Error Handling
269

270
The CSS processing system includes comprehensive error handling for common issues:
271

272
- **File not found**: Graceful handling when CSS files are missing
273
- **Compilation errors**: Detailed error reporting for preprocessor compilation failures
274
- **Invalid syntax**: Clear error messages for malformed CSS
275
- **Plugin errors**: Isolated error handling for PostCSS plugin failures
276
- **Custom renderer errors**: Error boundary for custom renderer exceptions
277

278
All errors are logged through the integrated logging system with context information including file names and error details.