npm package: @itaylor/parcel-transformer-css-modules-types
Description: Parcel transformer that generates TypeScript definitions for CSS Modules
Author: Ian Taylor
Latest version: 1.0.0

# @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

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

or with pnpm:

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

## Usage

Add the transformer to your `.parcelrc` file:

```json
{
  "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`:

```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`:

```typescript
// 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:

```typescript
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:

```bash
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](https://parceljs.org/languages/css/#css-modules)
- [Lightning CSS](https://lightningcss.dev/)