Tailwind CSS v4: novidades, desempenho, configuração e guia de migração

35 milissegundos. Esse é o tempo que o Tailwind v3 leva para fazer um build incremental. No v4, a mesma operação leva apenas 192 microssegundos. Não são milissegundos, mas microssegundos.

Quando vi esse dado pela primeira vez, desconfiei. Afinal, qualquer um sabe escrever uma boa frase de marketing. Mas, depois de fazer uma migração de verdade e ver o HMR cair de 340 ms para 12 ms, percebi que, desta vez, o Tailwind estava falando sério.

Essa é uma mudança concreta proporcionada pelo motor Oxide, reescrito em Rust. Não é aquela impressão subjetiva de que “parece um pouco mais rápido”: você muda um padding e a página atualiza antes mesmo de piscar. E o Tailwind v4 não se resume a uma troca de motor. Ele reformula completamente a configuração, que saiu do JS e foi para o CSS, o processo de instalação, agora praticamente sem configuração, e a sintaxe dos utilitários, com modificadores de opacidade, Container Queries, 3D Transforms e muito mais.

Neste artigo, vou explicar cada uma dessas mudanças e, principalmente, oferecer um checklist de migração que você pode seguir passo a passo.

Motor Oxide: por que o v4 é tão rápido?

Você já passou por esta situação? Alterou uma cor, salvou o arquivo e ficou olhando para o navegador por dois ou três segundos até a mudança aparecer. Em projetos grandes, os builds incrementais do Tailwind v3 realmente podem causar certa ansiedade, especialmente quando o prazo está apertado.

O motor Oxide do v4 foi criado justamente para resolver esse problema. Em vez de fazer pequenos ajustes no antigo motor em JS, a equipe do Tailwind reescreveu todo o compilador do zero em Rust. Foi uma decisão ousada, mas os ganhos são bem concretos.

Qual foi o ganho real de desempenho?

O benchmark oficial foi feito com o projeto Catalyst, e os números são bem claros:

O último número é o mais impressionante. Quando você muda apenas a estrutura HTML, sem adicionar novas classes CSS, o tempo de build do v4 cai para a casa dos microssegundos. É uma latência que você simplesmente não percebe.

Há também dados de um projeto em produção, com uma base de código de mais de 500 componentes:

A redução do HMR de 340 ms para 12 ms tem um impacto enorme na experiência de desenvolvimento. Antes, cada mudança de estilo vinha acompanhada de uma pausa perceptível; agora, o resultado aparece praticamente no mesmo instante.

O que o Oxide fez de diferente?

O motor Oxide combina Rust e Lightning CSS. A vantagem de desempenho do Rust é conhecida, mas a mudança de arquitetura é ainda mais importante:

Toolchain unificada. Na época do v3, o Tailwind dependia do ecossistema do PostCSS e exigia configurações adicionais para ferramentas como autoprefixer e cssnano. O v4 traz tudo isso integrado e depende de um único pacote, o Lightning CSS. Com menos etapas intermediárias, o processo naturalmente fica mais rápido.

Detecção inteligente de conteúdo. Antes, era preciso configurar manualmente o array content em tailwind.config.js para indicar onde o Tailwind deveria procurar nomes de classes. O v4 lê diretamente o .gitignore e o grafo de módulos para descobrir automaticamente os arquivos que precisam ser analisados. Além de exigir menos configuração, isso também torna o processo mais rápido.

Recursos nativos de CSS. O v4 usa regras @layer reais, propriedades personalizadas com @property, a função de cor color-mix() e outros recursos modernos de CSS. Como eles são suportados nativamente pelos navegadores, não precisam ser transformados durante a compilação.

Sinceramente, você não precisa entender todos esses detalhes técnicos. O que importa é o resultado: builds mais rápidos, menos configuração e uma experiência de desenvolvimento melhor.

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

Configuração CSS-first: adeus, tailwind.config.js

Essa é a maior mudança do v4 e também a parte que mais exige trabalho durante a migração.

Antes, escrevíamos a configuração no tailwind.config.js. Agora, ela deve ficar no arquivo CSS, usando a diretiva @theme. Para ser sincero, estranhei no começo. Depois de anos escrevendo configuração em JS, passar de repente para variáveis CSS pareceu um pouco desconfortável. Mas, após algum tempo de uso, percebi que essa abordagem combina melhor com a lógica do próprio CSS.

Migração da configuração: antes e depois

Veja primeiro um exemplo simples, definindo uma cor principal personalizada:

// v3: tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#3b82f6',
      },
    },
  },
}

No v4, tudo vai para o CSS:

/* v4: app.css */
@import "tailwindcss";

@theme {
  --color-primary: #3b82f6;
}

Talvez você tenha notado que o nome da variável mudou de primary para --color-primary. Isso acontece porque o v4 adota regras rígidas para os prefixos dos nomes.

Tabela de prefixos das variáveis

Esse sistema de prefixos pode parecer trabalhoso no início, mas tem uma vantagem: você não precisa adivinhar o nome da variável. Quer saber como escrever uma variável de tamanho de fonte? Ela certamente começa com --text-.

Exemplo de uma configuração mais complexa

Agora, um exemplo mais completo. Imagine que sua configuração do v3 seja assim:

// v3: tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          light: '#f0f9ff',
          DEFAULT: '#0ea5e9',
          dark: '#0369a1',
        },
      },
      fontFamily: {
        display: ['Cal Sans', 'sans-serif'],
      },
      animation: {
        'fade-in': 'fadeIn 0.5s ease-out',
      },
    },
  },
  plugins: [
    require('@tailwindcss/typography'),
  ],
}

Ao migrar para o v4:

/* v4: app.css */
@import "tailwindcss";

@theme {
  /* Cores */
  --color-brand-light: #f0f9ff;
  --color-brand: #0ea5e9;
  --color-brand-dark: #0369a1;

  /* Fontes */
  --font-display: "Cal Sans", sans-serif;

  /* Animações */
  --animate-fade-in: fadeIn 0.5s ease-out;
}

/* Plugin */
@plugin "@tailwindcss/typography";

Observe três mudanças:

1. Os níveis de cor ficam planos. No v3, era possível usar o objeto aninhado brand.light; no v4, ele deve ser escrito como --color-brand-light.
2. Plugins são importados com @plugin. Não é mais necessário usar require no JS.
3. O sufixo DEFAULT desaparece. A cor padrão de brand é escrita diretamente como --color-brand.

Configuração do modo escuro

No v3, a configuração do modo escuro era assim:

// v3
module.exports = {
  darkMode: 'class', // ou 'media'
}

O v4 usa a estratégia media por padrão, seguindo o sistema. Para mudar para class, adicione uma linha ao CSS:

/* v4 */
@import "tailwindcss";
@variant dark (&:where(.dark, .dark *));

Essa linha significa que os estilos do modo escuro serão aplicados quando o próprio elemento ou algum de seus pais tiver a classe .dark.

Configuração da detecção de conteúdo

Antes, era necessário informar manualmente quais arquivos deveriam ser analisados:

// v3
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './public/index.html',
  ],
}

O v4 lê o .gitignore automaticamente, ignora os arquivos excluídos e analisa todos os arquivos relevantes do projeto. Se a estrutura do seu projeto for um pouco incomum, você pode adicionar uma origem manualmente com @source:

/* v4 */
@import "tailwindcss";
@source "../node_modules/my-ui-lib";

A maior vantagem da configuração CSS-first é manter tudo o que se relaciona a estilos em um único arquivo CSS, sem precisar alternar entre JS e CSS. A desvantagem é o período de adaptação, sobretudo para quem já se acostumou à configuração em JS.

Instalação e integração: uma nova experiência quase sem configuração

Quem já instalou o Tailwind v3 conhece bem o processo: instalar três pacotes, criar o arquivo de configuração, configurar o PostCSS, preencher o array content… Não é exatamente complicado, mas é uma sequência que precisa ser repetida em todo projeto novo.

O v4 simplificou esse processo ao máximo.

Instalação mínima

Se você usa Vite, precisa de apenas dois passos:

# 1. Instalar
npm install tailwindcss @tailwindcss/vite

# 2. Adicionar uma linha ao vite.config.js
import tailwindcss from '@tailwindcss/vite'

export default {
  plugins: [tailwindcss()],
}

Depois, adicione uma única importação ao arquivo CSS:

/* app.css ou index.css */
@import "tailwindcss";

É só isso. Sem tailwind.config.js, sem postcss.config.js e sem array content. Funciona imediatamente.

Três formas de integração

Integração com Vite (recomendada):

npm install tailwindcss @tailwindcss/vite

// vite.config.js
import tailwindcss from '@tailwindcss/vite'

export default {
  plugins: [tailwindcss()],
}

Integração com PostCSS:

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

npm install tailwindcss @tailwindcss/postcss

// postcss.config.js
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

Uso pela CLI:

npx tailwindcss -i input.css -o output.css --watch

Na maioria dos projetos modernos, a integração com Vite é suficiente. A opção com PostCSS é adequada para migrar projetos antigos, enquanto a CLI atende cenários sem um processo de build.

Como funciona a detecção automática de conteúdo

No v4, você não precisa configurar o array content: os arquivos que devem ser analisados são descobertos automaticamente. Como isso funciona?

O Tailwind lê o arquivo .gitignore, exclui diretórios que não precisam ser analisados, como node_modules e dist, e depois procura nomes de classes do Tailwind nos arquivos restantes.

Esse mecanismo pressupõe uma estrutura convencional de projeto Node.js. Se os arquivos de template estiverem em um local incomum, como uma pasta fora da raiz do projeto, você terá de informar o caminho manualmente:

@import "tailwindcss";
@source "../templates";  /* Adiciona o caminho de análise manualmente */

A detecção automática também traz outra vantagem: não é preciso atualizar a configuração quando um arquivo é criado. Antes, a cada novo componente, talvez fosse necessário alterar o array content no tailwind.config.js, exceto em projetos que já usavam um curinga como **/*. Agora, você não precisa fazer nada; as classes funcionam no novo arquivo imediatamente.

Breaking changes e checklist de migração

Esta é a parte central da migração. Não se preocupe: a maioria das mudanças segue padrões claros, e o Tailwind oferece uma ferramenta oficial para automatizar boa parte do processo.

Mudança nos modificadores de opacidade

Esta é a alteração de maior impacto. No v3, a opacidade do fundo era definida assim:

<!-- v3 -->
<div class="bg-blue-500 bg-opacity-50">...</div>

No v4, a opacidade foi incorporada ao valor da cor:

<!-- v4 -->
<div class="bg-blue-500/50">...</div>

A sintaxe não se limita à cor de fundo: ela funciona em todas as propriedades relacionadas a cor.

<!-- Opacidade da cor do texto -->
<p class="text-gray-900/75">...</p>

<!-- Opacidade da cor da borda -->
<div class="border-red-500/30">...</div>

E o que fazer com classes como bg-opacity-*? Basta removê-las. O v4 não oferece mais suporte a elas.

Utilitários renomeados

No v4, alguns utilitários foram renomeados, principalmente para simplificar nomes e ajustar sua semântica:

Preste atenção às mudanças de shadow e rounded: o antigo shadow virou shadow-sm, e o antigo shadow-sm virou shadow-xs. Esse é um ajuste semântico que deixa os nomes de tamanho mais consistentes.

Mudanças nos valores padrão

Alguns valores padrão mudaram e podem causar diferenças visuais:

Cor padrão de border: no v3, era gray-200; no v4, passou a ser currentColor. Isso significa que a borda acompanha a cor do texto.

<!-- v3: a borda é cinza -->
<div class="border text-blue-500">A borda é gray-200</div>

<!-- v4: a borda acompanha a cor do texto -->
<div class="border text-blue-500">A borda é blue-500</div>

Valor padrão de ring: no v3, a largura padrão era 3px e a cor, blue-500; no v4, a largura passou a ser 1px e a cor, currentColor.

<!-- v3: o ring é azul e tem 3px -->
<button class="ring">...</button>

<!-- v4: o ring usa currentColor e tem 1px -->
<button class="ring">...</button>

<!-- Para reproduzir o efeito do v3 -->
<button class="ring-3 ring-blue-500">...</button>

Checklist completo de migração

Siga estes passos na ordem:

1. Atualize as dependências

   npm install tailwindcss@latest @tailwindcss/vite@latest

2. Execute a ferramenta de migração automática

   npx @tailwindcss/upgrade

   A ferramenta converte automaticamente a maior parte da sintaxe, incluindo as diretivas @tailwind, as classes de opacidade e os utilitários renomeados.

3. Converta o arquivo CSS de entrada

   /* v3 */
   @tailwind base;
   @tailwind components;
   @tailwind utilities;
   
   /* v4 */
   @import "tailwindcss";

4. Migre o arquivo de configuração: transfira a configuração do tailwind.config.js para o bloco @theme no CSS.

5. Atualize os plugins: troque os plugins JS pela sintaxe @plugin.

   @plugin "@tailwindcss/typography";

6. Confira as classes de opacidade: faça uma busca global por bg-opacity, text-opacity e border-opacity e substitua tudo pela nova sintaxe.

7. Confira as classes renomeadas: concentre-se em shadow-*, rounded-*, flex-grow-* e flex-shrink-*.

8. Confira as mudanças nos valores padrão: preste atenção principalmente à cor de border e ao estilo de ring.

9. Teste a regressão visual: execute seus testes visuais para garantir que nenhuma alteração tenha passado despercebida.

A ferramenta de migração automática cuida de 80% do trabalho, mas os 20% restantes ainda exigem verificação manual. Isso vale principalmente para mudanças nos valores padrão: a ferramenta não pode adivinhar o visual que você espera, então cabe a você fazer os ajustes.

Novidades: Container Queries, 3D Transforms e outros destaques

Além dos avanços em desempenho e configuração, o v4 trouxe alguns recursos novos bastante úteis.

Suporte nativo a Container Queries

Antes, era necessário instalar um plugin para usar Container Queries. Agora, o recurso tem suporte nativo:

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

<!-- Define o contêiner -->
<div class="@container">
  <!-- Responde à largura do contêiner -->
  <div class="@md:grid-cols-2 @lg:grid-cols-3">
    ...
  </div>
</div>

@container equivale a container-type: inline-size, enquanto @md: é um breakpoint de consulta ao contêiner. A sintaxe se parece bastante com o breakpoint responsivo md:, mas inclui um @ no início.

Esse recurso é especialmente útil em bibliotecas de componentes: o estilo do componente pode se adaptar à largura do contêiner pai, e não à largura da tela.

Utilitários de 3D Transform

O v4 adicionou um conjunto de utilitários de transformação 3D:

<!-- Perspectiva 3D -->
<div class="perspective-distant">
  <!-- Rotação no eixo X -->
  <div class="rotate-x-45">...</div>
</div>

<!-- Rotação no eixo Y -->
<div class="rotate-y-12">...</div>

<!-- Escala no eixo Z -->
<div class="scale-z-150">...</div>

As classes disponíveis incluem rotate-x-*, rotate-y-*, rotate-z-*, scale-z-*, perspective-*, translate-z-* e outras. Agora fica bem mais fácil criar interações como cartões que viram ou menus em 3D.

Variante @starting-style

Essa variante trabalha com o recurso nativo @starting-style do CSS e define o estilo do elemento em sua primeira renderização:

<!-- O elemento aparece em uma transição do transparente ao opaco -->
<div class="starting:opacity-0 opacity-100 transition-opacity">
  ...
</div>

É possível criar uma animação de entrada sem JavaScript. Antes, você precisaria de uma animação personalizada como animate-fade-in; agora, uma única linha de classes resolve.

Variante not-*

O v4 oferece suporte à pseudoclasse CSS :not():

<!-- Todos os filhos, exceto o último -->
<li class="not-last:mb-4">...</li>

<!-- Todos os botões que não estão desabilitados -->
<button class="not-disabled:opacity-100">...</button>

Antes, esse tipo de necessidade exigia uma abordagem invertida, como last:mb-0. Com not-*, a intenção fica mais direta.

Gradient API ampliada

Os gradientes ficaram mais completos no v4:

<!-- Gradiente cônico -->
<div class="bg-conic/from-red-500 via-yellow-500 to-blue-500">...</div>

<!-- Gradiente radial -->
<div class="bg-radial from-white to-transparent">...</div>

<!-- Modo de interpolação do gradiente -->
<div class="bg-linear-to-r from-blue-500 to-purple-500 via-oklch">...</div>

via-oklch é um novo modo de interpolação que produz transições de gradiente mais naturais, sobretudo durante conversões entre espaços de cor.

Conclusão

Depois de tudo isso, vale a pena atualizar?

Se o seu projeto ainda está em desenvolvimento ativo, minha recomendação é atualizar. A queda do HMR de centenas de milissegundos para pouco mais de dez economiza bastante tempo de espera todos os dias. Somada à redução do tamanho do CSS e do uso de memória, a melhoria é especialmente valiosa em projetos grandes.

O custo da migração está principalmente na conversão da configuração e na troca dos nomes de classes. Felizmente, a ferramenta automática npx @tailwindcss/upgrade resolve a maior parte do trabalho repetitivo. Eu mesmo testei: um projeto de porte médio, com mais de 200 componentes, levou cerca de meio dia para ser migrado, incluindo os testes.

Em projetos novos, use o v4 diretamente. Instalação praticamente sem configuração, detecção automática de conteúdo e configuração CSS-first tornam o Tailwind mais fácil de usar, sem bons motivos para começar na versão anterior.

Por fim, fique atento à compatibilidade com navegadores: o v4 exige Safari 16.4+, Chrome 111+ e Firefox 128+. Se o projeto precisa oferecer suporte a navegadores antigos, talvez seja melhor esperar.

Recomendações práticas:

• Use o v4 diretamente em projetos novos.
• Em projetos existentes, faça a migração automática com npx @tailwindcss/upgrade.
• Confira principalmente a mudança na cor padrão de border e no valor padrão de ring.
• Se houver problemas, consulte o guia oficial de atualização.