0
# File Matching
1

2
File pattern matching system for identifying CSS module files and handling custom file extensions and naming conventions.
3

4
## Capabilities
5

6
### CSS File Detection
7

8
Core functions for identifying CSS module files based on configurable patterns.
9

10
```typescript { .api }
11
/**
12
 * Function type for checking if a file is a CSS module
13
 */
14
type isCSSFn = (fileName: string) => boolean;
15

16
/**
17
 * Function type for checking if a file is a relative CSS module import
18
 */
19
type isRelativeCSSFn = (fileName: string) => boolean;
20

21
/**
22
 * Creates a CSS file checker function with optional custom pattern
23
 * @param customMatcher - Optional RegExp pattern for matching CSS files
24
 * @returns Function that checks if a filename matches CSS module pattern
25
 */
26
function createIsCSS(customMatcher?: RegExp): isCSSFn;
27

28
/**
29
 * Creates a relative CSS file checker function
30
 * @param isCSS - CSS file checker function
31
 * @returns Function that checks if a filename is a relative CSS import
32
 */
33
function createIsRelativeCSS(isCSS: isCSSFn): isRelativeCSSFn;
34
```
35

36
**Default Pattern:**
37

38
The default regular expression pattern is:
39
```javascript
40
/\.module\.((c|le|sa|sc)ss|styl)$/
41
```
42

43
This matches files with the following patterns:
44
- `.module.css`
45
- `.module.scss`
46
- `.module.sass`
47
- `.module.less` 
48
- `.module.styl`
49

50
**Usage Examples:**
51

52
```typescript
53
// Using default pattern
54
const isCSS = createIsCSS();
55
isCSS('component.module.css');    // true
56
isCSS('styles.module.scss');      // true
57
isCSS('theme.module.sass');       // true
58
isCSS('layout.module.less');      // true
59
isCSS('animations.module.styl');  // true
60
isCSS('regular.css');             // false
61
isCSS('script.js');               // false
62

63
// Using custom pattern
64
const customIsCSS = createIsCSS(/\.m\.(css|scss)$/);
65
customIsCSS('component.m.css');   // true
66
customIsCSS('styles.m.scss');     // true
67
customIsCSS('theme.module.css');  // false
68
```
69

70
### Matcher Creation System
71

72
Factory system for creating file matchers with configuration and error handling.
73

74
```typescript { .api }
75
/**
76
 * Matcher functions interface
77
 */
78
interface Matchers {
79
  /** Function to check if file is a CSS module */
80
  isCSS: isCSSFn;
81
  /** Function to check if file is a relative CSS module import */
82
  isRelativeCSS: isRelativeCSSFn;
83
}
84

85
/**
86
 * Creates matcher functions based on plugin options
87
 * @param logger - Logger instance for error reporting
88
 * @param options - Plugin options containing matcher configuration
89
 * @returns Object containing CSS file matcher functions
90
 */
91
function createMatchers(
92
  logger: Logger,
93
  options?: Options
94
): Matchers;
95
```
96

97
**Configuration Examples:**
98

99
1. **Default Configuration**:
100
```json
101
{
102
  "compilerOptions": {
103
    "plugins": [
104
      {
105
        "name": "typescript-plugin-css-modules"
106
      }
107
    ]
108
  }
109
}
110
```
111

112
2. **Custom Matcher Pattern**:
113
```json
114
{
115
  "compilerOptions": {
116
    "plugins": [
117
      {
118
        "name": "typescript-plugin-css-modules",
119
        "options": {
120
          "customMatcher": "\\.styles\\.(css|scss|sass)$"
121
        }
122
      }
123
    ]
124
  }
125
}
126
```
127

128
3. **Multiple File Extensions**:
129
```json
130
{
131
  "compilerOptions": {
132
    "plugins": [
133
      {
134
        "name": "typescript-plugin-css-modules",
135
        "options": {
136
          "customMatcher": "\\.(module|styles|theme)\\.(css|scss|sass|less|styl)$"
137
        }
138
      }
139
    ]
140
  }
141
}
142
```
143

144
### Relative Import Detection
145

146
System for detecting relative CSS module imports to handle module resolution correctly.
147

148
```typescript { .api }
149
/**
150
 * Checks if a file path is a relative import
151
 * @param fileName - File path to check
152
 * @returns Boolean indicating if the path is relative
153
 */
154
function isRelative(fileName: string): boolean;
155
```
156

157
**Relative Import Patterns:**
158

159
The system recognizes these patterns as relative imports:
160
- `./component.module.css`
161
- `../shared/styles.module.scss`
162
- `./styles/theme.module.sass`
163
- `../../common/layout.module.less`
164

165
**Usage Examples:**
166

167
```typescript
168
const isCSS = createIsCSS();
169
const isRelativeCSS = createIsRelativeCSS(isCSS);
170

171
// Relative imports
172
isRelativeCSS('./component.module.css');     // true
173
isRelativeCSS('../styles/theme.module.scss'); // true
174

175
// Absolute imports  
176
isRelativeCSS('component.module.css');       // false
177
isRelativeCSS('styles/theme.module.scss');   // false
178

179
// Node modules
180
isRelativeCSS('some-package/styles.module.css'); // false
181
```
182

183
### Error Handling and Validation
184

185
Robust error handling for invalid matcher patterns and configuration issues.
186

187
```typescript { .api }
188
/**
189
 * Error handling for matcher creation
190
 */
191
interface MatcherErrorHandling {
192
  /** Validates regular expression patterns */
193
  validatePattern(pattern: string): boolean;
194
  /** Provides fallback matchers on error */
195
  createFallbackMatcher(): isCSSFn;
196
  /** Logs configuration warnings */
197
  logConfigurationWarnings(logger: Logger): void;
198
}
199
```
200

201
**Error Scenarios:**
202

203
1. **Invalid Regular Expression**:
204
```json
205
{
206
  "customMatcher": "[invalid regex pattern"
207
}
208
```
209
Result: Falls back to default pattern, logs error
210

211
2. **Empty Pattern**:
212
```json
213
{
214
  "customMatcher": ""
215
}
216
```
217
Result: Uses default pattern, logs warning
218

219
3. **Pattern Too Broad**:
220
```json
221
{
222
  "customMatcher": ".*"
223
}
224
```
225
Result: Works but logs performance warning
226

227
### File Extension Support
228

229
Comprehensive support for various CSS preprocessor file extensions.
230

231
```typescript { .api }
232
/**
233
 * Supported file extensions mapping
234
 */
235
interface FileExtensionSupport {
236
  /** Standard CSS files */
237
  css: string[];
238
  /** Sass files */
239
  sass: string[];
240
  /** SCSS files */
241
  scss: string[];
242
  /** Less files */
243
  less: string[];
244
  /** Stylus files */
245
  stylus: string[];
246
}
247
```
248

249
**Supported Extensions:**
250

251
- **CSS**: `.css`
252
- **Sass**: `.sass`
253
- **SCSS**: `.scss`
254
- **Less**: `.less`
255
- **Stylus**: `.styl`
256

257
**Pattern Examples for Different Use Cases:**
258

259
1. **CSS Modules Only**:
260
```javascript
261
/\.module\.css$/
262
```
263

264
2. **SCSS Modules Only**:
265
```javascript
266
/\.module\.scss$/
267
```
268

269
3. **All Preprocessors**:
270
```javascript
271
/\.module\.((c|le|sa|sc)ss|styl)$/
272
```
273

274
4. **Custom Naming Convention**:
275
```javascript
276
/\.(styles|theme|components)\.css$/
277
```
278

279
5. **Scoped Styles**:
280
```javascript
281
/\.scoped\.(css|scss)$/
282
```
283

284
### Module Resolution Integration
285

286
Integration with TypeScript's module resolution system for CSS modules.
287

288
```typescript { .api }
289
/**
290
 * Module resolution for CSS files
291
 */
292
interface CSSModuleResolution {
293
  /** Resolves CSS module paths */
294
  resolveModulePath(moduleName: string, containingFile: string): string | undefined;
295
  /** Checks if module is external CSS library */
296
  isExternalCSSLibrary(moduleName: string): boolean;
297
  /** Handles failed module lookups */
298
  handleFailedLookup(moduleName: string, searchPaths: string[]): string | undefined;
299
}
300
```
301

302
**Resolution Examples:**
303

304
```typescript
305
// Relative imports
306
import styles from './component.module.css';
307
// Resolves to: /project/src/components/component.module.css
308

309
// Parent directory imports  
310
import styles from '../shared/theme.module.scss';
311
// Resolves to: /project/src/shared/theme.module.scss
312

313
// Deep relative imports
314
import styles from '../../styles/global.module.css';
315
// Resolves to: /project/styles/global.module.css
316
```
317

318
### Performance Optimization
319

320
Optimized file matching for large codebases with many CSS files.
321

322
```typescript { .api }
323
/**
324
 * Performance optimization features
325
 */
326
interface PerformanceOptimization {
327
  /** Caches compiled regular expressions */
328
  cacheCompiledPatterns: boolean;
329
  /** Optimizes file system lookups */
330
  optimizeFileSystemAccess: boolean;
331
  /** Batches file matching operations */
332
  batchFileOperations: boolean;
333
}
334
```
335

336
**Optimization Features:**
337

338
- **Pattern Caching**: Compiled regex patterns are cached to avoid recompilation
339
- **Early Exit**: File extension check before regex matching for better performance
340
- **Batch Processing**: Multiple files processed in single operations when possible
341
- **Lazy Loading**: Matchers created only when needed
342

343
### Integration with Build Tools
344

345
Compatibility with various build tools and development environments.
346

347
**Webpack Integration**:
348
- Compatible with css-loader module naming conventions
349
- Supports webpack's resolve.alias for CSS imports
350
- Works with webpack-dev-server hot reloading
351

352
**Vite Integration**:
353
- Supports Vite's CSS module conventions
354
- Compatible with Vite's import.meta.glob patterns
355
- Works with Vite's development server
356

357
**Next.js Integration**:
358
- Compatible with Next.js CSS module conventions  
359
- Supports Next.js global styles exclusions
360
- Works with Next.js app and pages directories
361

362
**Create React App**:
363
- Works out of the box with CRA's CSS module setup
364
- No additional configuration required
365
- Compatible with CRA's build optimizations