madappgang/css-modules

CSS Modules

Overview

CSS Modules provide locally-scoped CSS by automatically generating unique class names at build time. This prevents style conflicts and enables true component encapsulation.

When to Use CSS Modules

| Use Case | CSS Modules | Tailwind | |----------|-------------|----------| | Complex animations | Best | Good | | Third-party component styling | Best | Harder | | Legacy CSS migration | Best | Refactor needed | | Rapid prototyping | Slower | Best | | Design system utilities | Not ideal | Best | | Component encapsulation | Best | N/A | | Team with CSS expertise | Best | Either |

Hybrid Approach: Use both together - Tailwind for utilities, CSS Modules for complex components.

---

Documentation Index

Vite Integration

| Topic | URL | Description | |-------|-----|-------------| | CSS Modules in Vite | https://vite.dev/guide/features#css-modules | Vite's built-in support | | Lightning CSS | https://vite.dev/guide/features#lightning-css | Fast CSS transforms | | PostCSS | https://vite.dev/guide/features#postcss | PostCSS configuration |

Lightning CSS

| Topic | URL | Description | |-------|-----|-------------| | Documentation | https://lightningcss.dev/docs.html | Official docs | | CSS Modules | https://lightningcss.dev/css-modules.html | Module support | | Transpilation | https://lightningcss.dev/transpilation.html | Browser targeting | | Bundling | https://lightningcss.dev/bundling.html | CSS bundling |

CSS Modules Spec

| Topic | URL | Description | |-------|-----|-------------| | CSS Modules | https://github.com/css-modules/css-modules | Specification | | Composition | https://github.com/css-modules/css-modules#composition | Composing classes | | Scoping | https://github.com/css-modules/css-modules#naming | Local vs global |

TypeScript Integration

| Topic | URL | Description | |-------|-----|-------------| | typed-css-modules | https://github.com/Quramy/typed-css-modules | Generate .d.ts files | | vite-plugin-css-modules-dts | https://github.com/mrcjkb/vite-plugin-css-modules-dts | Vite plugin |

---

CSS Modules Fundamentals

File Naming Convention

src/
├── components/
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── Button.module.css      # CSS Module
│   │   └── Button.test.tsx
│   └── Card/
│       ├── Card.tsx
│       ├── Card.module.css        # CSS Module
│       └── index.ts

Files ending in .module.css are automatically processed as CSS Modules.

Basic Usage

/* Button.module.css */
.button {
  padding: 0.5rem 1rem;
  border-radius: 0.375rem;
  font-weight: 500;
  transition: background-color 150ms ease;
}

.primary {
  background-color: hsl(221, 83%, 53%);
  color: white;
}

.primary:hover {
  background-color: hsl(224, 76%, 48%);
}

.secondary {
  background-color: hsl(0, 0%, 96%);
  color: hsl(0, 0%, 9%);
}

// Button.tsx
import styles from './Button.module.css'

interface ButtonProps {
  variant?: 'primary' | 'secondary'
  children: React.ReactNode
}

export function Button({ variant = 'primary', children }: ButtonProps) {
  return (
    <button className={`${styles.button} ${styles[variant]}`}>
      {children}
    </button>
  )
}

Generated Class Names

<!-- Input -->
<button class="${styles.button} ${styles.primary}">

<!-- Output (generated) -->
<button class="Button_button_x7d9f Button_primary_a3k2j">

Local vs Global Scope

/* Local by default */
.button {
  /* Generates: Button_button_hash */
}

/* Explicit local */
:local(.button) {
  /* Same as above */
}

/* Global (escape hatch) */
:global(.external-library-class) {
  /* Kept as-is: .external-library-class */
}

/* Global within local */
.card :global(.markdown-body) {
  /* Scoped parent, global child */
}

---

Composition

composes Keyword

Share styles between classes:

/* base.module.css */
.flexCenter {
  display: flex;
  align-items: center;
  justify-content: center;
}

.interactive {
  cursor: pointer;
  transition: all 150ms ease;
}

/* Button.module.css */
.button {
  composes: flexCenter from './base.module.css';
  composes: interactive from './base.module.css';
  padding: 0.5rem 1rem;
}

Multiple Compositions

.primaryButton {
  composes: button;
  composes: primary from './colors.module.css';
  composes: rounded from './shapes.module.css';
}

Usage in React

// Composed class automatically includes all composed classes
<button className={styles.primaryButton}>
  {/* Renders: Button_primaryButton_x Button_button_y colors_primary_z shapes_rounded_w */}
</button>

---

Vite Configuration

Lightning CSS (Recommended)

Lightning CSS is 100x faster than PostCSS for transforms:

npm install lightningcss browserslist

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import browserslistToTargets from 'lightningcss/browserslist'
import browserslist from 'browserslist'

export default defineConfig({
  plugins: [react()],
  css: {
    transformer: 'lightningcss',
    lightningcss: {
      targets: browserslistToTargets(browserslist('>= 0.25%')),
      cssModules: {
        // Class name pattern
        pattern: '[name]__[local]_[hash:5]',
        // Or for production:
        // pattern: '[hash:8]'
      }
    }
  },
  build: {
    cssMinify: 'lightningcss'
  }
})

Class Name Patterns

| Pattern | Example Output | |---------|----------------| | [name]__[local]_[hash:5] | Button__primary_a3k2j | | [local]_[hash:8] | primary_a3k2j9x1 | | [hash:8] | a3k2j9x1 (production) |

Lightning CSS Features (Included)

Lightning CSS automatically handles:

• Vendor prefixing (replaces autoprefixer)
• Modern syntax transpilation
• Nesting
• Custom media queries
• Color functions (oklch, lab, lch)

PostCSS Configuration (When Needed)

For plugins Lightning CSS doesn't support:

// postcss.config.js
export default {
  plugins: {
    'postcss-import': {},
    'postcss-custom-media': {},
    // Don't use: autoprefixer (Lightning CSS handles this)
    // Don't use: postcss-nested (Lightning CSS handles this)
  }
}

Note: Use Lightning CSS for transforms, PostCSS only for unsupported plugins.

---

TypeScript Integration

Type Declarations

Without types, TypeScript doesn't know the shape of CSS modules:

// This would error without declarations
import styles from './Button.module.css'
styles.button  // TS error: Property 'button' does not exist

Option 1: Wildcard Declaration (Simple)

// src/vite-env.d.ts or src/types/css-modules.d.ts
declare module '*.module.css' {
  const classes: { [key: string]: string }
  export default classes
}

Pros: No extra tooling Cons: No autocomplete, no type safety

Option 2: Generated Declarations (Recommended)

npm install -D vite-plugin-css-modules-dts

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import cssModulesDts from 'vite-plugin-css-modules-dts'

export default defineConfig({
  plugins: [
    react(),
    cssModulesDts({
      // Generate .d.ts next to .module.css files
      outputDir: '.',
    })
  ]
})

Generated files:

// Button.module.css.d.ts (auto-generated)
declare const styles: {
  readonly button: string
  readonly primary: string
  readonly secondary: string
}
export default styles

Pros: Full autocomplete, type safety, catches typos Cons: Generated files in source (add to .gitignore)

Option 3: CLI Generation

npm install -D typed-css-modules

# Generate declarations
npx tcm src --pattern '**/*.module.css'

# Watch mode
npx tcm src --pattern '**/*.module.css' --watch

Add to package.json:

{
  "scripts": {
    "css:types": "tcm src --pattern '**/*.module.css'",
    "css:types:watch": "tcm src --pattern '**/*.module.css' --watch"
  }
}

---

Patterns

Component-Scoped Styling

/* Card.module.css */
.card {
  border-radius: 0.5rem;
  background: white;
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
  overflow: hidden;
}

.header {
  padding: 1rem;
  border-bottom: 1px solid hsl(0, 0%, 90%);
}

.content {
  padding: 1.5rem;
}

.footer {
  padding: 1rem;
  background: hsl(0, 0%, 98%);
}

// Card.tsx
import styles from './Card.module.css'

export function Card({ children }: { children: React.ReactNode }) {
  return <div className={styles.card}>{children}</div>
}

Card.Header = ({ children }: { children: React.ReactNode }) => (
  <header className={styles.header}>{children}</header>
)

Card.Content = ({ children }: { children: React.ReactNode }) => (
  <div className={styles.content}>{children}</div>
)

Card.Footer = ({ children }: { children: React.ReactNode }) => (
  <footer className={styles.footer}>{children}</footer>
)

CSS Variables with Modules

/* theme.css (global) */
:root {
  --color-primary: hsl(221, 83%, 53%);
  --color-primary-dark: hsl(224, 76%, 48%);
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
}

/* Button.module.css */
.button {
  background-color: var(--color-primary);
  padding: var(--spacing-sm) var(--spacing-md);
}

.button:hover {
  background-color: var(--color-primary-dark);
}

Theming with CSS Variables

/* theme.module.css */
.light {
  --bg: white;
  --text: hsl(0, 0%, 9%);
  --border: hsl(0, 0%, 90%);
}

.dark {
  --bg: hsl(0, 0%, 9%);
  --text: hsl(0, 0%, 98%);
  --border: hsl(0, 0%, 20%);
}

/* Component.module.css */
.component {
  background-color: var(--bg);
  color: var(--text);
  border: 1px solid var(--border);
}

Complex Animations

CSS Modules excel at complex animations:

/* Modal.module.css */
.overlay {
  position: fixed;
  inset: 0;
  background: rgba(0, 0, 0, 0.5);
  opacity: 0;
  transition: opacity 200ms ease;
}

.overlayVisible {
  composes: overlay;
  opacity: 1;
}

.modal {
  position: fixed;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%) scale(0.95);
  opacity: 0;
  transition: all 200ms cubic-bezier(0.16, 1, 0.3, 1);
}

.modalVisible {
  composes: modal;
  transform: translate(-50%, -50%) scale(1);
  opacity: 1;
}

@keyframes slideIn {
  from {
    transform: translate(-50%, -50%) translateY(20px) scale(0.95);
    opacity: 0;
  }
  to {
    transform: translate(-50%, -50%) translateY(0) scale(1);
    opacity: 1;
  }
}

.modalAnimated {
  animation: slideIn 300ms cubic-bezier(0.16, 1, 0.3, 1);
}

---

Hybrid Approach: CSS Modules + Tailwind

Use both together for maximum flexibility:

import styles from './ComplexCard.module.css'

function ComplexCard({ title, children }: Props) {
  return (
    // Tailwind for layout, CSS Module for complex styles
    <div className={`${styles.card} p-4 md:p-6`}>
      <h2 className={`${styles.title} text-lg font-semibold mb-2`}>
        {title}
      </h2>
      <div className={styles.animatedContent}>
        {children}
      </div>
    </div>
  )
}

When to Use Which

| Scenario | Approach | |----------|----------| | Layout utilities (flex, grid, spacing) | Tailwind | | Responsive utilities | Tailwind | | State variants (hover, focus) | Tailwind | | Complex animations | CSS Modules | | Keyframe animations | CSS Modules | | Third-party component overrides | CSS Modules | | Component state classes | CSS Modules | | Design system utilities | Tailwind | | One-off complex styles | CSS Modules |

---

Performance Benefits

Lightning CSS Advantages

| Feature | Speed Improvement | |---------|-------------------| | CSS parsing | 100x faster than PostCSS | | Vendor prefixing | Built-in, instant | | Minification | Faster than cssnano | | Bundling | Parallel processing |

Dead Code Elimination

Vite automatically eliminates unused CSS:

• CSS Modules are naturally tree-shaken (only imported classes included)
• Lightning CSS removes unused selectors

Bundle Size Optimization

// vite.config.ts
export default defineConfig({
  build: {
    cssMinify: 'lightningcss',
    cssCodeSplit: true,  // Separate CSS per chunk
  }
})

---

Related Skills

• tailwindcss - Utility-first CSS (complementary approach)
• shadcn-ui - Component library using CSS variables
• react-typescript - Component patterns with className
• testing-frontend - Testing styled components