@itaylor/parcel-transformer-css-modules-types

A Parcel transformer that automatically generates TypeScript definition files for CSS Modules, providing type safety and IntelliSense support for your CSS module imports.

Features

• 🎯 Automatic Type Generation: Generates .d.ts files for all .module.css files
• 🔗 Lightning CSS Integration: Leverages Parcel's existing Lightning CSS dependency

Installation

npm install --save-dev @itaylor/parcel-transformer-css-modules-types

or with pnpm:

pnpm add -D @itaylor/parcel-transformer-css-modules-types

Usage

Add the transformer to your .parcelrc file:

{
  "extends": "@parcel/config-default",
  "transformers": {
    "*.module.css": [
      "@itaylor/parcel-transformer-css-modules-types",
      "@parcel/transformer-css"
    ]
  }
}

Important: The transformer must be placed before @parcel/transformer-css in the array to ensure it can process the CSS before it's transformed.

How It Works

The transformer processes .module.css files and generates corresponding .d.ts files with TypeScript definitions for all CSS classes.

Example

Given a CSS module file styles.module.css:

.container {
  display: flex;
  flex-direction: column;
}

.header-title {
  font-size: 2rem;
  color: blue;
}

.nav-item {
  padding: 0.5rem;
}

The transformer will generate styles.module.css.d.ts:

// Auto-generated CSS module types

declare const styles: {
  readonly container: string;
  readonly headerTitle: string;
  readonly navItem: string;
};

export default styles;
export const container: string;
export const headerTitle: string;
export const navItem: string;

You can then import and use the styles with full type safety:

import styles from './styles.module.css';
// or
import { container, headerTitle, navItem } from './styles.module.css';

// TypeScript will provide autocomplete and type checking
const className = styles.container; // ✅ Type safe
const invalid = styles.nonExistent; // ❌ TypeScript error

Lightning CSS Dependency

This transformer relies on Lightning CSS to process CSS modules and extract class names. It intelligently resolves Lightning CSS from Parcel's existing dependency chain, so you don't need to install it separately.

The transformer looks for Lightning CSS in this order:

1. Your project's dependencies (if you've explicitly installed lightningcss)
2. Parcel's CSS transformer (@parcel/transformer-css)
3. Parcel's CSS optimizer (@parcel/optimizer-css)
4. Parcel's default config (@parcel/config-default)

This approach ensures compatibility with your Parcel version and avoids dependency conflicts.

Manual Lightning CSS Installation (Optional)

If you want to pin a specific version of Lightning CSS, you can install it directly:

npm install --save-dev lightningcss

The transformer will prefer your project's version if available.

Requirements

• Node.js: >= 12.0.0
• Parcel: ^2.0.0
• Lightning CSS: Available through Parcel's CSS pipeline (automatic)

Class Name Processing

The transformer automatically converts CSS class names to valid TypeScript identifiers:

• kebab-case to camelCase: .nav-item → navItem
• Invalid identifiers: Skipped with a warning (e.g., classes starting with numbers)
• Reserved words: Skipped with a warning (e.g., class, function, etc.)
• Duplicates: Automatically deduplicated

Error Handling

If the transformer encounters issues:

• Lightning CSS not found: Throws an error with installation instructions
• Invalid class names: Logs warnings and skips invalid identifiers
• CSS parsing errors: Logs warnings and continues processing other files

Integration with Development Tools

This transformer works seamlessly with:

• VS Code: Provides IntelliSense and autocomplete for CSS module imports
• TypeScript: Full type checking for CSS class names
• ESLint: Works with TypeScript ESLint rules
• Prettier: Generated .d.ts files can be formatted with Prettier

License

MIT

Related

• Parcel CSS Modules Documentation
• Lightning CSS