Configuração CSS-First

O arquivo tailwind.config.js historicamente foi o centro de configuração do Tailwind CSS. No entanto, com a chegada do Tailwind CSS v4, o framework passou por uma reformulação arquitetônica profunda, adotando uma abordagem baseada em CSS nativo (CSS-first).

Abaixo está o artigo atualizado, explicando o papel desse arquivo nas versões anteriores (v3 e anteriores) e como a configuração funciona no ecossistema atual da v4.

O Papel do tailwind.config.js (v3 e anteriores)

Nas versões anteriores do Tailwind CSS (como a v3), o arquivo tailwind.config.js era essencial. Ele servia como o cérebro do framework, escrito em JavaScript (Node.js), responsável por definir o comportamento, estender o tema e gerenciar os arquivos que deveriam ser escaneados.

Esse arquivo era gerado automaticamente com o comando:

Bash

npx tailwindcss init

Ou com suporte a PostCSS:

Bash

npx tailwindcss init -p

Estrutura básica na v3

Um arquivo tailwind.config.js padrão continha a seguinte estrutura:

JavaScript

module.exports = {
  content: [],
  theme: {
    extend: {},
  },
  plugins: [],
}

• Seção content: Definia os caminhos de todos os arquivos de template (HTML, JS, JSX, TS, TSX) para que o motor do Tailwind pudesse escanear as classes utilizadas e remover o CSS não utilizado em produção (processo de purge).

• Seção theme: Permitia redefinir ou estender o design padrão (cores, espaçamentos, fontes). Usando extend, os valores eram adicionados ao tema existente; fora dele, o tema padrão era sobrescrito.

• Seção plugins: Utilizada para registrar plugins oficiais (como @tailwindcss/forms) ou personalizados para injetar novos utilitários ou componentes via JavaScript.

A Evolução no Tailwind CSS v4: Configuração CSS-First

No Tailwind CSS v4, a configuração baseada em JavaScript tornou-se opcional para a grande maioria dos projetos. O framework foi reescrito para ser CSS-first, o que significa que toda a personalização do tema, variáveis e diretivas agora acontece diretamente no seu arquivo CSS principal utilizando variáveis e diretivas nativas do CSS (@theme, @import, etc.).

O que mudou?

1. Sem arquivo de configuração obrigatório: O arquivo tailwind.config.js não é mais gerado por padrão.

2. Detecção automática de conteúdo: A seção content foi eliminada na v4. O Tailwind agora escaneia automaticamente os arquivos do projeto com base no seu sistema de build (Vite, Next.js, etc.), tornando o processo mais rápido e inteligente.

3. Configuração via CSS: Variáveis de tema e customizações são feitas usando a diretiva @theme.

Se você ainda precisar usar um arquivo tailwind.config.js na v4 (por exemplo, para compatibilidade com ferramentas legadas ou plugins complexos baseados em JS), ele ainda é detectado e suportado como uma camada de compatibilidade, mas o padrão recomendado mudou.

Estrutura Atualizada do Artigo (Padrão Tailwind v4)

Abaixo está a versão atualizada do artigo refletindo as práticas modernas do framework.

O arquivo CSS principal é o novo centro de configuração do Tailwind CSS v4. Através de uma abordagem baseada em CSS nativo (CSS-first), você pode personalizar completamente o comportamento e a aparência do framework, ajustando desde cores e espaçamentos até temas e variantes diretamente com a diretiva @theme.

Estrutura básica

Em vez de um arquivo JavaScript, o Tailwind v4 é inicializado no seu arquivo CSS principal (ex: src/input.css ou app.css) importando o framework:

CSS

@import "tailwindcss";

Seção @theme

A diretiva @theme permite redefinir ou estender o design padrão do Tailwind utilizando variáveis CSS nativas. É aqui que você altera as escalas de espaçamento, cores, fontes, larguras, breakpoints e mais.

Adicionando ou estendendo valores:

Na v4, qualquer valor adicionado dentro de @theme define uma nova variável ou estende o tema de forma inteligente.

CSS

@import "tailwindcss";

@theme {
  --font-sans: "Inter", sans-serif;
  
  --color-primary: #1e40af;
  --color-secondary: #64748b;

  --spacing-72: 18rem;
  --spacing-84: 21rem;
  --spacing-96: 24rem;
}

Ao definir --color-primary, o Tailwind gera automaticamente as classes utilitárias correspondentes, como bg-primary, text-primary e border-primary.

Redefinindo o tema por completo:

Se o objetivo for remover o tema padrão do Tailwind e começar do zero, utiliza-se a palavra-chave default:

CSS

@theme default {
  --color-black: #000;
  --color-white: #fff;
}

Gerenciamento de Plugins e Utilitários

Na v4, utilitários personalizados e plugins que antes dependiam de funções JavaScript no arquivo de configuração agora podem ser escritos diretamente em CSS puro utilizando a diretiva @utility.

CSS

@utility card {
  background-color: var(--color-white);
  padding: var(--spacing-6);
  border-radius: var(--radius-lg);
  box-shadow: var(--shadow-md);
}

Para plugins oficiais da comunidade (como o plugin de formulários), a inclusão é feita diretamente via folha de estilo ou integrada na etapa de compilação do seu bundler (Vite, PostCSS, Rust CLI).

Temas personalizados e Modo Escuro

O suporte ao modo escuro e variantes customizadas também foi simplificado, utilizando seletores CSS padrões ou variáveis de ambiente.

CSS

@import "tailwindcss";

@theme {
  --color-background: #1f2937;
  --color-surface: #374151;
}

/* Customização de variantes de mídia ou classes diretamente no CSS se necessário */

Benefícios do uso do modelo CSS-First na v4

• Performance aprimorada: A compilação baseada no novo motor em Rust é até 10x mais rápida que nas versões anteriores.

• Sintaxe nativa: Menos dependência de APIs JavaScript proprietárias e maior alinhamento com os padrões modernos da Web (CSS Variables).

• Zero configuração de arquivos: A detecção automática de código elimina a necessidade de mapear manualmente diretórios em propriedades content.

• Interoperabilidade: Facilidade para compartilhar tokens de design com outras ferramentas que consomem variáveis CSS nativas.

Com a nova arquitetura da versão 4, o Tailwind consolida-se como um compilador de CSS de alta performance, onde a folha de estilo principal se torna a única fonte de verdade para a identidade visual do projeto.