CSS

Core Idea

Next.js suporta múltiplas formas de estilização: Tailwind CSS, CSS Modules, Global CSS, stylesheets externos, Sass e CSS-in-JS. Esta página cobre as quatro primeiras e a ordem/merge de CSS no build.

Key Concepts

• Tailwind CSS: framework utility-first; requer tailwindcss + @tailwindcss/postcss, configuração em postcss.config.mjs, e @import 'tailwindcss' no CSS global.
• CSS Modules: escopo local automático via nomes de classe únicos, arquivo .module.css, importado como objeto (styles.blog).
• Global CSS: aplica estilos a toda a aplicação; deve ser importado no root layout (app/global.css); recomendado só para CSS verdadeiramente global (ex.: base do Tailwind).
• External stylesheets: pacotes externos publicados podem ser importados em qualquer lugar de app, incluindo componentes colocalizados (ex.: import 'bootstrap/dist/css/bootstrap.css').
• Ordering and Merging: em produção, Next.js faz chunking automático de stylesheets; a ordem do CSS final segue a ordem de import no código.
• cssChunking: opção em next.config.js para controlar como o CSS é dividido em chunks.

Code Examples

@import 'tailwindcss';

• O que demonstra: import do Tailwind no app/globals.css, após configurar o plugin PostCSS.

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

export default function Page() {
  return <main className={styles.blog}></main>
}

• O que demonstra: uso de CSS Module escopado localmente.

import { BaseButton } from './base-button'
import styles from './page.module.css'

export default function Page() {
  return <BaseButton className={styles.primary} />
}

• O que demonstra: a ordem final do CSS segue a ordem de import no código: base-button.module.css fica antes de page.module.css porque BaseButton é importado primeiro.

Reference Tables

Método	Escopo	Quando usar
Tailwind CSS	Global (classes utilitárias)	Estilização principal recomendada
CSS Modules	Local (por componente)	Estilos customizados quando utilities não bastam
Global CSS	Toda a aplicação	Apenas CSS verdadeiramente global (ex.: base)
External stylesheets	Onde importado	Estilos de pacotes de terceiros

Anti-patterns

• Usar Global CSS para estilos de componente: React/Suspense não remove stylesheets globais na navegação entre rotas, podendo causar conflitos; prefira CSS Modules ou Tailwind por componente.
• Espalhar imports de CSS por múltiplos arquivos sem padrão: torna a ordem final imprevisível; contenha os imports de CSS a um único arquivo de entrada por escopo e evite linters que reordenam imports automaticamente (ex.: sort-imports do ESLint).
• Confiar na ordem do CSS em dev: a ordem pode se comportar diferente em next dev; sempre validar com next build.

Key Takeaways

1. Recomendação oficial: Tailwind para a maioria dos casos, CSS Modules para estilos específicos de componente, Global CSS só para o que é verdadeiramente global.
2. A ordem final do CSS em produção é determinada pela ordem de import no código, não pela ordem dos arquivos no disco.
3. Extrair estilos compartilhados em componentes reutilizáveis evita imports duplicados de CSS.
4. Em dev, CSS atualiza via Fast Refresh; em produção, arquivos são concatenados/minificados/code-split automaticamente.
5. cssChunking em next.config.js dá controle manual sobre o chunking quando o padrão não é suficiente.

Connects To

• Font Optimization (ch014): também usa className aplicado no root layout, mesmo padrão de escopo de estilo global vs. local.