Tailwind CSS Academy · 课时

CSS Modules 与 Tailwind

在 CSS Modules 中使用 Tailwind 工具类，将有作用域的组件样式与工具优先方法结合到 React 和 Next.js 应用中。

CSS Modules 与 Tailwind 是 CoddyKit 上的免费 Tailwind CSS Academy 课时。这是第 3 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Tailwind CSS Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Tailwind CSS Academy 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

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.

常见问题解答

「CSS Modules 与 Tailwind」课时是免费的吗？

是的 — 「CSS Modules 与 Tailwind」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Tailwind CSS Academy 课程的其余内容，请升级到 CoddyKit PRO。 Tailwind CSS Academy 课程共包含 4 节课。

「CSS Modules 与 Tailwind」这节课中我会学到什么？

在 CSS Modules 中使用 Tailwind 工具类，将有作用域的组件样式与工具优先方法结合到 React 和 Next.js 应用中。你通过在浏览器中直接运行的动手代码来练习 Tailwind CSS Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Tailwind CSS Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Tailwind CSS Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 3 节课，共 4 节。

「CSS Modules 与 Tailwind」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Tailwind CSS Academy 课中编写并运行代码吗？

能。每节 Tailwind CSS Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Tailwind CSS Academy