Tailwind CSS 4: o que mudou e como migrar sem sofrimento

1. Visão geral do Tailwind CSS 4: por que essa versão é um marco?

O Tailwind CSS 4 representa a maior reformulação da biblioteca desde seu lançamento. A engine foi reescrita do zero em Rust, resultando em ganhos expressivos de performance — builds que antes levavam segundos agora ocorrem em milissegundos. O tamanho do pacote também encolheu drasticamente: a versão 4 ocupa cerca de 60% menos espaço que sua antecessora.

A mudança mais paradigmática é o fim da configuração via tailwind.config.js. O Tailwind v4 adota uma abordagem CSS-first, onde toda personalização é feita diretamente em arquivos CSS usando diretivas nativas. Isso elimina a necessidade de um arquivo JavaScript separado para configuração, simplificando o setup e reduzindo a complexidade do projeto.

Quanto à compatibilidade com versões anteriores, a Tailwind Labs optou por quebrar algumas APIs para avançar mais rapidamente. Cerca de 80% dos utilitários básicos continuam funcionando, mas plugins customizados, @apply com classes responsivas e a configuração via JavaScript exigem adaptação.

2. Principais novidades da v4: o que realmente mudou?

A diretiva @theme é o coração da nova abordagem. Em vez de definir tokens no tailwind.config.js, você declara tudo diretamente no CSS:

@theme {
  --color-primary: #3b82f6;
  --color-primary-dark: #2563eb;
  --font-family-base: 'Inter', sans-serif;
  --spacing-page: 1.5rem;
}

Essas variáveis CSS nativas são automaticamente convertidas em classes utilitárias como bg-primary, text-primary-dark, font-base e p-page.

Os breakpoints responsivos foram unificados. Agora todos os prefixos seguem o mesmo padrão: sm:, md:, lg:, xl:, 2xl:. Não há mais distinção entre breakpoints de grid e breakpoints de display — tudo funciona de forma consistente.

O suporte nativo a container queries e estilos aninhados elimina a necessidade de plugins PostCSS adicionais:

.card {
  @container;

  .title {
    font-size: 1.25rem;
  }

  @container (min-width: 400px) {
    .title {
      font-size: 1.5rem;
    }
  }
}

3. CSS-first: como configurar sem JavaScript?

Para iniciar um projeto com Tailwind v4, o setup é minimalista. No seu arquivo CSS principal:

@import "tailwindcss";

Isso substitui toda a configuração complexa de PostCSS. Não é mais necessário instalar tailwindcss, postcss, autoprefixer e configurar arquivos separados. Um único @import resolve.

Para personalizar cores, fontes e espaçamentos:

@import "tailwindcss";

@theme {
  --color-brand: #7c3aed;
  --color-brand-light: #a78bfa;
  --font-heading: 'Poppins', sans-serif;
  --font-body: 'Inter', sans-serif;
  --spacing-section: 4rem;
  --radius-card: 0.75rem;
}

Plugins e variantes também são declarados no CSS:

@plugin "my-custom-plugin";
@variant dark {
  --color-brand: #c4b5fd;
}

4. Migração prática: passo a passo para não quebrar o projeto

Substituindo o tailwind.config.js

Antes (v3):

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#3b82f6',
      },
      fontFamily: {
        heading: ['Poppins', 'sans-serif'],
      },
    },
  },
}

Depois (v4):

@theme {
  --color-primary: #3b82f6;
  --font-heading: 'Poppins', sans-serif;
}

Atualizando plugins customizados

Antes (v3):

// tailwind.config.js
plugins: [
  require('@tailwindcss/forms'),
  require('@tailwindcss/typography'),
]

Depois (v4):

@plugin "@tailwindcss/forms";
@plugin "@tailwindcss/typography";

Lidando com @apply que mudou

No v4, @apply não aceita mais classes responsivas diretamente:

Antes (v3):

.btn {
  @apply px-4 py-2 text-white bg-blue-500 hover:bg-blue-600;
}

Depois (v4):

.btn {
  @apply px-4 py-2 text-white bg-blue-500;
}
.btn:hover {
  @apply bg-blue-600;
}

5. Performance e bundle: o que melhorou para o usuário final?

O tree-shaking no v4 é automático e mais inteligente. Enquanto a v3 exigia PurgeCSS configurado manualmente, a v4 analisa seu HTML/JSX em tempo real e gera apenas as classes realmente utilizadas. Em um projeto de dashboard com 200 componentes, o bundle caiu de 380KB (v3 com PurgeCSS) para 45KB (v4 nativo).

A compilação incremental reduz o tempo de hot reload em aproximadamente 70%. Em projetos com mais de 500 classes únicas, a primeira compilação caiu de 2.3s (v3) para 0.4s (v4). Recompilações após alterações ficam abaixo de 50ms.

6. Casos de migração sem sofrimento: exemplos reais

Projeto pequeno (landing page)

Migração em 15 minutos. Basta substituir o tailwind.config.js por um @theme com as cores da marca, ajustar alguns @apply e testar. Como landing pages usam utilitários padrão, 95% do código funciona sem alterações.

Projeto médio (dashboard com temas dinâmicos)

Requer cerca de 2 horas. O maior trabalho é mapear as variáveis de tema para @theme e ajustar plugins como @tailwindcss/forms. A troca de temas via CSS custom properties fica mais natural:

[data-theme="dark"] {
  --color-bg: #1a1a2e;
  --color-text: #e0e0e0;
}

Projeto legado com muitas customizações

Pode levar um dia inteiro. O roteiro de compatibilidade inclui: extrair todos os extend do config para @theme, reescrever plugins como @plugin, e substituir @variants por aninhamento CSS nativo.

7. Armadilhas comuns e como evitá-las

@apply com classes responsivas: No v4, @apply não aceita hover:, focus: ou breakpoints. Solução: use pseudo-classes CSS diretamente ou crie componentes com classes separadas.

Conflitos com variáveis CSS de terceiros: Shadcn/ui e Radix usam variáveis CSS próprias que podem sobrescrever as do @theme. Solução: use namespaces ou importe o tema do Tailwind antes dos temas de terceiros.

Ferramentas de terceiros: tailwind-merge funciona, mas clsx e classnames precisam de adaptação para trabalhar com a nova sintaxe de variantes. O PostCSS tailwindcss/nesting não é mais necessário — o nesting nativo do CSS já cobre 99% dos casos.

8. Próximos passos: ecossistema e futuro do Tailwind

Para projetos novos, o setup recomendado é:
- Next.js 15: npx create-next-app@latest --tailwind já usa v4
- Vite 6: npm create vite@latest com template vanilla-ts + @import "tailwindcss"
- Remix: suporte oficial via @remix-run/css-bundle

O Headless UI ainda está em fase de adaptação para v4. A versão 2.0 (em beta) já funciona, mas alguns componentes como Transition exigem configuração extra.

O roadmap oficial indica para v4.1: suporte a @config para compatibilidade retroativa, e para v5: remoção completa de APIs legadas e integração com CSS Layers do navegador.

Referências