0
# Plugin Configuration
1

2
Core plugin configuration interface and options for customizing CSS module processing behavior, file matching patterns, and compilation settings.
3

4
## Capabilities
5

6
### Options Interface
7

8
Main configuration interface for the TypeScript plugin.
9

10
```typescript { .api }
11
/**
12
 * Main plugin configuration interface
13
 */
14
interface Options {
15
  /** String to append to the top of source files */
16
  additionalData?: string;
17
  /** Disables TypeScript warnings on unknown classnames */
18
  allowUnknownClassnames?: boolean;
19
  /** Class name transformation mode */
20
  classnameTransform?: ClassnameTransformOptions;
21
  /** Custom regex pattern for CSS files */
22
  customMatcher?: string;
23
  /** Path to custom CSS renderer */
24
  customRenderer?: string;
25
  /** Path to custom TypeScript template */
26
  customTemplate?: string;
27
  /** Dotenv configuration options */
28
  dotenvOptions?: Omit<DotenvConfigOptions, 'path'> & { path?: string };
29
  /** Enable jump to definition functionality */
30
  goToDefinition?: boolean;
31
  /** Enable named exports for classnames */
32
  namedExports?: boolean;
33
  /** TypeScript compatibility option */
34
  noUncheckedIndexedAccess?: boolean;
35
  /** PostCSS configuration */
36
  postcssOptions?: PostcssOptions;
37
  /** @deprecated To align with naming in other projects. */
38
  postCssOptions?: PostcssOptions;
39
  /** Renderer-specific options */
40
  rendererOptions?: RendererOptions;
41
}
42
```
43

44
### Class Name Transformations
45

46
Configuration options for transforming CSS class names to match different naming conventions.
47

48
```typescript { .api }
49
/**
50
 * Class name transformation options
51
 */
52
type ClassnameTransformOptions = 
53
  | 'asIs'          // Leave class names unchanged
54
  | 'camelCase'     // Add camelCase variants alongside original
55
  | 'camelCaseOnly' // Transform to camelCase only
56
  | 'dashes'        // Add dashCase variants alongside original
57
  | 'dashesOnly';   // Transform to dashCase only
58
```
59

60
**Usage Examples:**
61

62
```json
63
{
64
  "compilerOptions": {
65
    "plugins": [
66
      {
67
        "name": "typescript-plugin-css-modules",
68
        "options": {
69
          "classnameTransform": "camelCase"
70
        }
71
      }
72
    ]
73
  }
74
}
75
```
76

77
With `"classnameTransform": "camelCase"`, a CSS class `.my-component` becomes accessible as both `styles['my-component']` and `styles.myComponent`.
78

79
### PostCSS Configuration
80

81
Options for integrating with PostCSS configuration and plugins.
82

83
```typescript { .api }
84
/**
85
 * PostCSS integration options
86
 */
87
interface PostcssOptions {
88
  /** Array of async plugins to exclude */
89
  excludePlugins?: string[];
90
  /** Whether to load plugins from PostCSS config */
91
  useConfig?: boolean;
92
}
93
```
94

95
**Usage Examples:**
96

97
```json
98
{
99
  "compilerOptions": {
100
    "plugins": [
101
      {
102
        "name": "typescript-plugin-css-modules",
103
        "options": {
104
          "postcssOptions": {
105
            "useConfig": true,
106
            "excludePlugins": ["postcss-mixins"]
107
          }
108
        }
109
      }
110
    ]
111
  }
112
}
113
```
114

115
### Renderer Options
116

117
Preprocessor-specific configuration options for CSS compilation.
118

119
```typescript { .api }
120
/**
121
 * Renderer-specific options for CSS preprocessors
122
 */
123
interface RendererOptions {
124
  /** Less compiler options */
125
  less?: Partial<Less.Options>;
126
  /** Sass compiler options */
127
  sass?: Partial<SassOptions<'sync'>>;
128
  /** Stylus compiler options */
129
  stylus?: Partial<StylusRenderOptions>;
130
}
131
```
132

133
**Usage Examples:**
134

135
```json
136
{
137
  "compilerOptions": {
138
    "plugins": [
139
      {
140
        "name": "typescript-plugin-css-modules",
141
        "options": {
142
          "rendererOptions": {
143
            "sass": {
144
              "includePaths": ["node_modules", "src/styles"]
145
            }
146
          }
147
        }
148
      }
149
    ]
150
  }
151
}
152
```
153

154
### Custom File Matching
155

156
Configure custom patterns for identifying CSS module files.
157

158
```typescript { .api }
159
/**
160
 * Custom matcher configuration
161
 */
162
interface CustomMatcherConfig {
163
  /** Regular expression pattern as string */
164
  customMatcher?: string;
165
}
166
```
167

168
**Usage Examples:**
169

170
```json
171
{
172
  "compilerOptions": {
173
    "plugins": [
174
      {
175
        "name": "typescript-plugin-css-modules",
176
        "options": {
177
          "customMatcher": "\\.m\\.(css|scss|sass)$"
178
        }
179
      }
180
    ]
181
  }
182
}
183
```
184

185
The default pattern is `\\.module\\.((c|le|sa|sc)ss|styl)$` which matches files like:
186
- `component.module.css`
187
- `styles.module.scss`
188
- `theme.module.sass`
189
- `layout.module.less`
190
- `animations.module.styl`
191

192
### Dotenv Integration
193

194
Configure environment variable loading for CSS processing.
195

196
```typescript { .api }
197
/**
198
 * Dotenv configuration options
199
 */
200
interface DotenvConfig {
201
  /** Path to .env file (relative to project root) */
202
  path?: string;
203
  /** Additional dotenv options */
204
  [key: string]: any;
205
}
206
```
207

208
**Usage Examples:**
209

210
```json
211
{
212
  "compilerOptions": {
213
    "plugins": [
214
      {
215
        "name": "typescript-plugin-css-modules",
216
        "options": {
217
          "dotenvOptions": {
218
            "path": ".env.local"
219
          }
220
        }
221
      }
222
    ]
223
  }
224
}
225
```
226

227
This enables loading environment variables like `SASS_PATH` for configuring preprocessor search paths.
228

229
### Advanced Options
230

231
Additional configuration options for specialized use cases.
232

233
```typescript { .api }
234
/**
235
 * Advanced configuration options
236
 */
237
interface AdvancedOptions {
238
  /** Enable go-to-definition for CSS classes */
239
  goToDefinition?: boolean;
240
  /** Enable named exports for compatible classnames */
241
  namedExports?: boolean;
242
  /** Allow unknown classnames without TypeScript warnings */
243
  allowUnknownClassnames?: boolean;
244
  /** Compatibility with TypeScript's noUncheckedIndexedAccess */
245
  noUncheckedIndexedAccess?: boolean;
246
  /** String to prepend to all CSS files */
247
  additionalData?: string;
248
}
249
```
250

251
**Usage Examples:**
252

253
```json
254
{
255
  "compilerOptions": {
256
    "plugins": [
257
      {
258
        "name": "typescript-plugin-css-modules",
259
        "options": {
260
          "goToDefinition": true,
261
          "namedExports": true,
262
          "additionalData": "@import 'variables.scss';"
263
        }
264
      }
265
    ]
266
  }
267
}
268
```