0Pricing
Tailwind CSS Academy · Aula

Módulos CSS e Tailwind

Use utilidades do Tailwind dentro de Módulos CSS para combinar estilos de componentes com escopo definido e a abordagem baseada em utilidades em aplicações React e Next.js.

Módulos CSS e Tailwind é uma aula grátis de Tailwind CSS Academy no CoddyKit. Esta é a aula 3 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Tailwind CSS Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Tailwind CSS Academy inclui 4 aulas no total.

Partes desta aula ainda não foram traduzidas e aparecem em inglês.

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.

Perguntas Frequentes

A aula “Módulos CSS e Tailwind” é grátis?

Sim — o texto completo de “Módulos CSS e Tailwind” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Tailwind CSS Academy, atualize para CoddyKit PRO. O curso de Tailwind CSS Academy inclui 4 aulas no total.

O que vou aprender em “Módulos CSS e Tailwind”?

Use utilidades do Tailwind dentro de Módulos CSS para combinar estilos de componentes com escopo definido e a abordagem baseada em utilidades em aplicações React e Next.js. Você pratica Tailwind CSS Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Tailwind CSS Academy?

Nenhuma experiência prévia é necessária. Tailwind CSS Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 3 de 4.

Quanto tempo leva a aula “Módulos CSS e Tailwind”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Tailwind CSS Academy?

Sim. Cada aula de Tailwind CSS Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Organização de arquivos e pastas
  2. Coexistindo com CSS legado
  3. Módulos CSS e Tailwind
  4. Expandindo o Tailwind em monorrepositórios
← Voltar para Tailwind CSS Academy