converting-css-modules-to-tailwind

Converting CSS Modules to Tailwind

Migrate a component from CSS Modules (.module.css / .module.scss) to Tailwind utility classes.

Workflow

1. Inventory the Module

Read the .module.css file and the component that imports it. Map every styles.xxx reference to the CSS rule it resolves to.

// Before
import styles from './Card.module.css';
<div className={styles.card}>
  <h2 className={styles.title}>{title}</h2>
  <p className={styles.body}>{children}</p>
</div>

/* Card.module.css */
.card { display: flex; flex-direction: column; gap: 16px; padding: 24px; border-radius: 12px; background: white; box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
.title { font-size: 20px; font-weight: 600; color: #111827; }
.body { font-size: 14px; color: #6b7280; line-height: 1.6; }

2. Convert Each Class

Replace styles.xxx with equivalent Tailwind utilities:

// After
<div className="flex flex-col gap-4 p-6 rounded-xl bg-white shadow-sm">
  <h2 className="text-xl font-semibold text-gray-900">{title}</h2>
  <p className="text-sm text-gray-500 leading-relaxed">{children}</p>
</div>

3. Handle CSS Modules Patterns

composes keyword:

.base { padding: 8px 16px; border-radius: 4px; }
.primary { composes: base; background: blue; color: white; }

→ Flatten into a single set of utilities. If reuse is needed, extract a component, not a class.

Conditional classNames with clsx/classnames:

// Before
className={clsx(styles.button, isActive && styles.active)}
// After
className={clsx("px-4 py-2 rounded", isActive && "bg-blue-600 text-white")}

Dynamic class selection:

// Before
className={styles[variant]}
// After — use a lookup object
const variantClasses = {
  primary: "bg-blue-600 text-white hover:bg-blue-700",
  secondary: "bg-gray-100 text-gray-900 hover:bg-gray-200",
  danger: "bg-red-600 text-white hover:bg-red-700",
};
className={variantClasses[variant]}

CSS Modules global overrides:

:global(.some-library-class) { ... }

→ Move to globals.css with @layer components { } or use Tailwind's @apply in the global stylesheet.