Tailwind CSS Academy · Lektion

CSS Modules und Tailwind

Verwenden Sie Tailwind-Utilities innerhalb von CSS Modules, um bereichsbezogene Komponentenstile mit dem Utility-First-Ansatz in React- und Next.js-Apps zu kombinieren.

CSS Modules und Tailwind ist eine kostenlose Tailwind CSS Academy-Lektion auf CoddyKit. Dies ist Lektion 3 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des Tailwind CSS Academy-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der Tailwind CSS Academy-Kurs umfasst insgesamt 4 Lektionen.

Teile dieser Lektion wurden noch nicht übersetzt und werden auf Englisch angezeigt.

What Are CSS Modules

CSS Modules are CSS files where class names are locally scoped by default. When you import a CSS Module into a JavaScript component, the class names are transformed into unique identifiers like Button_root__Xk2p1, preventing style leakage between components. CSS Modules are built into Next.js and available in most React setups via webpack or Vite.

/* Button.module.css */
.root {
  display: flex;
  align-items: center;
}

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

const Button = () => (
  // styles.root resolves to 'Button_root__Xk2p1' at runtime
  <button className={styles.root}>Click me</button>
);

Why Combine CSS Modules With Tailwind

Tailwind and CSS Modules seem philosophically opposed — Tailwind avoids naming things while CSS Modules is all about naming things locally. But they complement each other in practice. CSS Modules handle complex selectors, :focus-within chains, and pseudo-element styling that Tailwind cannot express easily. Tailwind handles the bulk of visual styling. Together they cover 100% of styling needs.

Using @apply Inside CSS Modules

The most common pattern for combining the two is using @apply inside a CSS Module file. You define a locally-scoped class in the .module.css file and compose it from Tailwind utilities using @apply. This gives you the scoping benefits of CSS Modules while keeping the styling expressed in Tailwind's vocabulary.

/* Card.module.css */
.card {
  @apply rounded-xl bg-white p-6 shadow-sm;
}

.cardHeader {
  @apply border-b border-gray-100 pb-4 text-lg font-semibold text-gray-900;
}

.cardBody {
  @apply pt-4 text-sm text-gray-600 leading-relaxed;
}

Importing and Using Module Classes

Import the CSS Module in the React component and reference the local class names through the imported object. Combine module class names with global Tailwind utilities in the className prop using string interpolation or clsx. Module classes handle structure, Tailwind utilities handle responsive or state-specific overrides directly in JSX.

import styles from './Card.module.css';
import { clsx } from 'clsx';

interface CardProps {
  highlighted?: boolean;
  children: React.ReactNode;
}

export function Card({ highlighted, children }: CardProps) {
  return (
    <div
      className={clsx(
        styles.card,
        // Tailwind utilities alongside module classes
        highlighted && 'ring-2 ring-blue-500',
        'transition hover:shadow-md'
      )}
    >
      {children}
    </div>
  );
}

CSS Modules for Complex Selectors

Use CSS Modules specifically when Tailwind cannot express a selector. For example, styling a child element based on parent state with a complex selector, or using ::before and ::after pseudo-elements for decorative content that cannot be achieved with ring or shadow utilities. The .module.css file is the right home for these exceptions.

/* Dropdown.module.css */
/* Tailwind cannot easily target this nested state */
.trigger:focus-within .menu {
  opacity: 1;
  pointer-events: auto;
  transform: translateY(0);
}

.menu {
  opacity: 0;
  pointer-events: none;
  transform: translateY(-8px);
  transition: opacity 150ms ease, transform 150ms ease;
}

/* Decorative pseudo-element */
.triangle::after {
  content: '';
  position: absolute;
  border: 6px solid transparent;
  border-bottom-color: white;
  top: -12px;
  left: 50%;
  transform: translateX(-50%);
}

Composing Module Classes

CSS Modules support the composes keyword to inherit styles from another class within the same file or a different module file. This is CSS Modules' native approach to reuse. While @apply brings in Tailwind utilities, composes brings in other module classes — you can combine both in the same file for maximum flexibility.

/* base.module.css */
.baseButton {
  @apply inline-flex items-center rounded-lg px-4 py-2 font-semibold
         transition focus:outline-none focus:ring-2 focus:ring-offset-2;
}

/* Button.module.css */
.primary {
  composes: baseButton from './base.module.css';
  @apply bg-blue-600 text-white focus:ring-blue-500 hover:bg-blue-700;
}

.secondary {
  composes: baseButton from './base.module.css';
  @apply border border-gray-300 text-gray-700 hover:bg-gray-50 focus:ring-gray-400;
}

CSS Modules in Next.js

Next.js supports CSS Modules out of the box with zero configuration — any file ending in .module.css is automatically scoped. The PostCSS pipeline that processes Tailwind also processes CSS Modules, so @apply works inside module files without any additional setup. This makes Next.js the ideal environment for the Tailwind + CSS Modules combination.

// next.config.js — no extra config needed
// CSS Modules and Tailwind work automatically

// Any .module.css file is locally scoped:
// components/Hero/Hero.module.css  ← scoped
// styles/globals.css               ← global (Tailwind entry)

// Verify your postcss.config.js has tailwindcss:
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

When NOT to Use CSS Modules

CSS Modules add a file per component and a layer of indirection that is overkill for most Tailwind components. Avoid them for simple components where all styling fits comfortably in className with utilities. Reserve CSS Modules for components with genuinely complex CSS that exceeds what utility classes can express — this is usually less than 10% of components in a typical Tailwind project.

// DON'T: CSS Module for a simple button — overkill
/* Button.module.css */
/* .btn { @apply px-4 py-2 rounded bg-blue-600 text-white; } */

// DO: Just use classes directly — much simpler
const Button = ({ children }) => (
  <button className="rounded bg-blue-600 px-4 py-2 font-semibold text-white
                     transition hover:bg-blue-700">
    {children}
  </button>
);

Global vs Local CSS in Next.js

In Next.js, only global stylesheets (globals.css) can be imported in _app.js or layout.tsx. CSS Modules are imported only inside the component that uses them. This constraint is intentional — it prevents accidental global style leakage. Tailwind's global directives always live in globals.css; module files contain only component-scoped rules.

// app/layout.tsx — import globals (Tailwind entry) here
import '../styles/globals.css';     // ✅ global CSS
// import './Card.module.css';      // ❌ Error: CSS Modules not allowed here

// components/Card.tsx — import module CSS here
import styles from './Card.module.css'; // ✅ scoped to this file

export function Card() {
  return <div className={styles.card}>...</div>;
}

Debugging CSS Module Class Names

In development mode, CSS Module class names include the file name and original class name for readability: Card_root__Xk2p1. In production, they are shortened to opaque hashes for size. If a module class is not applying, inspect the element in browser DevTools to see the generated class name and confirm it appears in the element's class list. Check for typos in the property access: styles.cardHeader not styles.card-header (camelCase required).

/* Card.module.css */
.card-header { /* ← hyphenated CSS class */ }

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

// Accessing hyphenated classes requires bracket notation:
const el = <div className={styles['card-header']}>...</div>;

// Better: use camelCase in the module file:
/* .cardHeader { } */
const el2 = <div className={styles.cardHeader}>...</div>;

TypeScript Support for CSS Modules

TypeScript does not know the shape of CSS Module imports by default, causing styles.anyClass to type-check as any. Install typescript-plugin-css-modules or use typed-css-modules to generate .d.ts type declarations for each module file. This gives autocomplete for class names in your editor and catches typos at compile time.

npm install -D typescript-plugin-css-modules

// tsconfig.json
{
  "compilerOptions": {
    "plugins": [
      { "name": "typescript-plugin-css-modules" }
    ]
  }
}

// Now styles.cardHeader shows autocomplete in VS Code
// and TypeScript warns if you access a class that does not exist

Quick Check

Test your understanding of Tailwind CSS Mastery concepts from this lesson.

Lesson Recap

In this lesson you learned: using @apply inside CSS Modules to combine scoped class names with Tailwind utilities, when to reach for CSS Modules versus staying in className (complex selectors and pseudo-elements), and TypeScript support for type-safe CSS Module class access. Next up we explore scaling Tailwind across monorepos.

Häufig gestellte Fragen

Ist die Lektion „CSS Modules und Tailwind“ kostenlos?

Ja — der vollständige Text von „CSS Modules und Tailwind“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des Tailwind CSS Academy-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der Tailwind CSS Academy-Kurs umfasst insgesamt 4 Lektionen.

Was lerne ich in „CSS Modules und Tailwind“?

Verwenden Sie Tailwind-Utilities innerhalb von CSS Modules, um bereichsbezogene Komponentenstile mit dem Utility-First-Ansatz in React- und Next.js-Apps zu kombinieren. Du übst Tailwind CSS Academy mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.

Brauche ich Erfahrung, um Tailwind CSS Academy zu starten?

Keine Vorkenntnisse erforderlich. Tailwind CSS Academy auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 3 von 4.

Wie lange dauert die Lektion „CSS Modules und Tailwind“?

Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.

Kann ich in dieser Tailwind CSS Academy-Lektion Code schreiben und ausführen?

Ja. Jede Tailwind CSS Academy-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.

Alle Lektionen in diesem Kurs

← Zurück zu Tailwind CSS Academy