0
# TypeScript Plugin CSS Modules
1

2
TypeScript Plugin CSS Modules is a TypeScript language service plugin that provides comprehensive CSS Modules support for TypeScript development environments. It enables intelligent type information, auto-completion, and go-to-definition functionality for CSS module imports, supporting multiple CSS preprocessors including SASS, SCSS, Less, and Stylus.
3

4
## Package Information
5

6
- **Package Name**: typescript-plugin-css-modules
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install -D typescript-plugin-css-modules`
10

11
## Core Imports
12

13
The plugin is configured in `tsconfig.json` rather than imported directly:
14

15
```json
16
{
17
  "compilerOptions": {
18
    "plugins": [{ "name": "typescript-plugin-css-modules" }]
19
  }
20
}
21
```
22

23
**Note**: This package is a TypeScript language service plugin and does not export types for direct import. Types are used internally by the plugin for configuration and custom renderer/template development.
24

25
## Basic Usage
26

27
1. **Installation and Configuration**:
28

29
```bash
30
npm install -D typescript-plugin-css-modules
31
```
32

33
```json
34
{
35
  "compilerOptions": {
36
    "plugins": [
37
      {
38
        "name": "typescript-plugin-css-modules",
39
        "options": {
40
          "classnameTransform": "camelCase",
41
          "customMatcher": "\\.module\\.((c|le|sa|sc)ss|styl)$"
42
        }
43
      }
44
    ]
45
  }
46
}
47
```
48

49
2. **Using CSS Modules in TypeScript**:
50

51
```typescript
52
// Import CSS module
53
import styles from './component.module.css';
54

55
// Access class names with full type safety
56
const className = styles.myClass;
57
const anotherClass = styles['my-other-class'];
58

59
// Named exports for compatible class names
60
import styles, { myClass } from './component.module.css';
61
```
62

63
3. **Type Declarations (if needed)**:
64

65
```typescript
66
declare module '*.module.css' {
67
  const classes: { [key: string]: string };
68
  export default classes;
69
}
70
```
71

72
## Architecture
73

74
The plugin integrates with TypeScript's language service architecture through several key components:
75

76
- **Plugin Factory**: Main entry point that creates the language service plugin
77
- **File Matchers**: Regex-based system for identifying CSS module files
78
- **CSS Processors**: Support for CSS, SCSS, Sass, Less, and Stylus compilation
79
- **Type Generation**: Automatic TypeScript declaration generation for CSS classes
80
- **Module Resolution**: Custom resolution logic for CSS module imports
81
- **Transform System**: Configurable class name transformations (camelCase, dashes, etc.)
82
- **Custom Renderers**: Extensible system for custom CSS processing pipelines
83

84
## Capabilities
85

86
### Plugin Configuration
87

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

90
```typescript { .api }
91
interface Options {
92
  additionalData?: string;
93
  allowUnknownClassnames?: boolean;
94
  classnameTransform?: ClassnameTransformOptions;
95
  customMatcher?: string;
96
  customRenderer?: string;
97
  customTemplate?: string;
98
  dotenvOptions?: Omit<DotenvConfigOptions, 'path'> & { path?: string };
99
  goToDefinition?: boolean;
100
  namedExports?: boolean;
101
  noUncheckedIndexedAccess?: boolean;
102
  postcssOptions?: PostcssOptions;
103
  /** @deprecated To align with naming in other projects. */
104
  postCssOptions?: PostcssOptions;
105
  rendererOptions?: RendererOptions;
106
}
107

108
type ClassnameTransformOptions = 
109
  | 'asIs' 
110
  | 'camelCase' 
111
  | 'camelCaseOnly' 
112
  | 'dashes' 
113
  | 'dashesOnly';
114
```
115

116
[Plugin Configuration](./plugin-configuration.md)
117

118
### CSS Processing
119

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

122
```typescript { .api }
123
enum FileType {
124
  css = 'css',
125
  less = 'less',
126
  sass = 'sass',
127
  scss = 'scss',
128
  styl = 'styl'
129
}
130

131
type CustomRenderer = (
132
  css: string,
133
  options: CustomRendererOptions
134
) => string | {
135
  css: string;
136
  sourceMap?: RawSourceMap;
137
};
138
```
139

140
[CSS Processing](./css-processing.md)
141

142
### Type Generation
143

144
Automatic TypeScript declaration generation system that creates type-safe interfaces for CSS module class names and handles class name transformations.
145

146
```typescript { .api }
147
type CustomTemplate = (
148
  dts: string,
149
  options: CustomTemplateOptions
150
) => string;
151

152
interface CustomTemplateOptions {
153
  classes: CSSExports;
154
  fileName: string;
155
  logger: Logger;
156
}
157
```
158

159
[Type Generation](./type-generation.md)
160

161
### File Matching
162

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

165
```typescript { .api }
166
type isCSSFn = (fileName: string) => boolean;
167
type isRelativeCSSFn = (fileName: string) => boolean;
168

169
function createIsCSS(customMatcher?: RegExp): isCSSFn;
170
function createIsRelativeCSS(isCSS: isCSSFn): isRelativeCSSFn;
171
```
172

173
[File Matching](./file-matching.md)
174

175
## Types
176

177
### Core Configuration Types
178

179
```typescript { .api }
180
interface PostcssOptions {
181
  excludePlugins?: string[];
182
  useConfig?: boolean;
183
}
184

185
interface RendererOptions {
186
  less?: Partial<Less.Options>;
187
  sass?: Partial<SassOptions<'sync'>>;
188
  stylus?: Partial<StylusRenderOptions>;
189
}
190

191
interface CustomRendererOptions {
192
  fileName: string;
193
  logger: Logger;
194
  compilerOptions: tsModule.CompilerOptions;
195
}
196
```
197

198
### Logging Interface
199

200
```typescript { .api }
201
interface Logger {
202
  log: (message: string) => void;
203
  error: (error: unknown) => void;
204
}
205

206
function createLogger(
207
  info: tsModule.server.PluginCreateInfo
208
): Logger;
209
```