Tailwind CSS v4: Guia de migração e novos recursos

Tailwind CSS v4 é a reescrita mais significativa desde o lançamento da estrutura. O arquivo de configuração JavaScript desapareceu – substituído pela primeira configuração CSS usando propriedades personalizadas. A API da classe permanece praticamente inalterada, mas os componentes internos são completamente novos: um mecanismo baseado em Rust (oxide), suporte de primeira classe para a gama de cores P3, consultas de contêiner nativas e um pipeline de construção que se integra diretamente com CSS em vez de por meio de plug-ins PostCSS.

Este guia mostra o que mudou, por que mudou e como migrar um aplicativo de produção real do Tailwind v3 para v4. Abordaremos as principais alterações que irão atrapalhar você e os novos recursos que valem a pena adotar imediatamente.

Principais conclusões

• tailwind.config.js está obsoleto — a configuração muda para CSS usando a diretiva @theme
• Importação alterada de @tailwind base/components/utilities para um único @import "tailwindcss"
• Cores personalizadas agora usam propriedades personalizadas CSS no namespace --color-*
• A configuração content é automática – Tailwind v4 verifica arquivos automaticamente via glob
• Consultas de contêiner agora são integradas com variantes @container e @sm:, @lg:
• Suporte à gama de cores P3 via espaço de cores oklch() para todas as cores integradas
• @apply ainda funciona, mas é menos necessário com propriedades personalizadas CSS
• O mecanismo JIT foi substituído pelo Oxide (Rust) — compilação dramaticamente mais rápida

---

O que mudou e por quê

Tailwind v3 usou PostCSS como pipeline de processamento, um arquivo de configuração JavaScript e gerou classes de utilitários por meio de um mecanismo JIT escrito em JavaScript. Isso funcionou bem, mas teve limitações:

• Configuração necessária de JavaScript, tornando-o inacessível a partir de ferramentas somente CSS
• As propriedades personalizadas tiveram que ser definidas separadamente da configuração do Tailwind
• Consultas de contêiner exigiam um plugin
• O sistema de cores não suportava a gama P3

O Tailwind v4 aborda tudo isso movendo a configuração para o próprio CSS, usando o sistema de propriedades personalizadas CSS nativo do navegador e reescrevendo o mecanismo em Rust para compilações 5 a 10x mais rápidas.

---

Instalação

# Tailwind v4
pnpm add tailwindcss@^4.0.0 @tailwindcss/vite

# For Next.js
pnpm add tailwindcss@^4.0.0 @tailwindcss/postcss

O plugin @tailwindcss/vite integra-se diretamente com o Vite. Para Next.js (que usa PostCSS internamente), use @tailwindcss/postcss.

---

Configuração CSS-Primeira

Esta é a maior mudança conceitual. Seu globals.css se torna a fonte da verdade para a configuração do Tailwind:

/* Before: globals.css with v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* After: globals.css with v4 */
@import "tailwindcss";

/* Theme configuration replaces tailwind.config.js */
@theme {
  /* Custom colors as CSS custom properties */
  --color-brand-50: oklch(97% 0.02 250);
  --color-brand-100: oklch(94% 0.04 250);
  --color-brand-500: oklch(62% 0.18 250);
  --color-brand-900: oklch(28% 0.09 250);

  /* Custom font families */
  --font-sans: 'Inter', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;

  /* Custom spacing */
  --spacing-18: 4.5rem;
  --spacing-88: 22rem;

  /* Custom breakpoints */
  --breakpoint-3xl: 1920px;

  /* Custom shadows */
  --shadow-card: 0 1px 3px oklch(0% 0 0 / 12%), 0 1px 2px oklch(0% 0 0 / 8%);
}

Seu tailwind.config.js pode ser excluído (ou mantido por enquanto — a v4 oferece suporte a ambos durante a migração).

---

Detecção de conteúdo

Tailwind v4 detecta automaticamente arquivos de modelo. A configuração content que você manteve meticulosamente na v3 desapareceu:

// v3 tailwind.config.js — you needed this
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx}',
  ],
  // ...
}

Na v4, o Tailwind verifica seu projeto automaticamente usando padrões sensatos. Se você tiver arquivos em locais incomuns, poderá incluí-los explicitamente:

@import "tailwindcss";
@source "../scripts/*.ts"; /* Scan additional paths */
@source "../../packages/ui/src/**/*.tsx"; /* Monorepo workspace packages */

---

Atualização de configuração pós-CSS

Para projetos Next.js (e qualquer configuração baseada em PostCSS), atualize sua configuração PostCSS:

// Before: postcss.config.js with v3
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

// After: postcss.config.mjs with v4
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

autoprefixer está incluído em @tailwindcss/postcss por padrão. Remova a dependência autoprefixer separada.

---

Sistema de cores: OKLCH

Tailwind v4 usa OKLCH para sua paleta de cores integrada. OKLCH é um espaço de cores perceptualmente uniforme – ajustar a luminosidade na verdade parece etapas iguais para o olho humano, ao contrário do HSL.

/* v4 colors use OKLCH internally */
/* bg-blue-500 generates: */
background-color: oklch(62.8% 0.258 264.1);

/* Custom colors with OKLCH */
@theme {
  --color-ecosire-amber: oklch(78% 0.18 80);
  --color-ecosire-navy: oklch(22% 0.04 250);
}

Para exibições de gama mais ampla (a maioria dos telefones e Macs modernos), o OKLCH permite cores que o sRGB simplesmente não consegue representar. Os valores oklch() são convertidos automaticamente em rgb() para monitores que não suportam P3.

---

Consultas de contêiner — integradas

As consultas de contêiner agora são de primeira classe na v4. Nenhum plug-in necessário:

/* Define a container */
.card-wrapper {
  container-type: inline-size;
  container-name: card;
}

<!-- Responsive based on parent container, not viewport -->
<div class="card-wrapper">
  <div class="@sm:flex-row @lg:grid-cols-3 flex flex-col">
    <!-- Layout changes based on container width, not screen width -->
  </div>
</div>

Isso permite capacidade de resposta em nível de componente – um cartão de barra lateral e um cartão de largura total podem ter layouts diferentes sem CSS separado.

Os contêineres nomeados permitem que você direcione ancestrais específicos:

<div class="card-wrapper [container-name:card]">
  <div class="@card/sm:text-lg text-base">
    Responsive to the 'card' container
  </div>
</div>

---

Integração de propriedades personalizadas CSS

As propriedades personalizadas definidas em @theme são acessíveis em qualquer lugar — CSS, JavaScript e ferramentas de design que leem variáveis CSS:

@theme {
  --color-primary: oklch(62% 0.18 250);
  --spacing-section: 5rem;
}

// Access in JavaScript/TypeScript
const style = getComputedStyle(document.documentElement);
const primary = style.getPropertyValue('--color-primary');

<!-- Use in inline styles -->
<div style={{ color: 'var(--color-primary)' }}>
  Themed content
</div>

Isso substitui o padrão de manutenção de valores paralelos em tailwind.config.js e um arquivo tokens.ts — agora há uma única fonte de verdade em CSS.

---

Mudanças significativas

1. Alterações na API do plug-in

Plugins v3 usando addBase, addComponents, addUtilities são incompatíveis com v4. Reescreva-os como CSS usando o novo sistema de camadas:

/* v3 plugin equivalent in v4 CSS */
@layer base {
  h1 {
    @apply text-3xl font-bold;
  }
}

@layer components {
  .btn {
    @apply px-4 py-2 rounded-lg font-medium;
  }
}

2. @apply com classes personalizadas

@apply com classes não Tailwind é mais restrito na v4. Use @apply apenas com classes utilitárias reais:

/* This works in v4 */
.btn-primary {
  @apply bg-blue-500 text-white px-4 py-2 rounded-lg;
}

/* This is deprecated — use regular CSS instead */
.btn-primary {
  @apply custom-shadow; /* custom-shadow is not a Tailwind utility */
}

3. tailwind.config.js theme.extend desapareceu

A configuração em JS não é mais o caminho principal. Use @theme em CSS. Se você tiver ambos, a configuração CSS terá precedência.

4. Nomenclatura da paleta de cores padrão

Alguns nomes de cores foram alterados na v4. Execute o codemod oficial para capturá-los:

npx @tailwindcss/upgrade@next --config tailwind.config.js

---

Estratégia de Migração

Para um aplicativo de produção grande, migre de forma incremental:

Fase 1: Instalação da atualização

pnpm remove tailwindcss autoprefixer postcss
pnpm add tailwindcss@^4.0.0 @tailwindcss/postcss

Atualizar postcss.config.mjs:

export default {
  plugins: { '@tailwindcss/postcss': {} },
};

Atualizar globals.css:

/* Replace the three @tailwind directives */
@import "tailwindcss";

Fase 2: Execute o codemod

npx @tailwindcss/upgrade@next

Isso automatiza a maior parte da migração: atualiza nomes de cores, converte configurações em CSS e sinaliza problemas que precisam de atenção manual.

Fase 3: Mover configuração para CSS

Pegue os valores do seu tema tailwind.config.js e mova-os para @theme em seu CSS. Exclua o arquivo de configuração após a verificação.

Fase 4: Adote novos recursos

Substitua pontos de interrupção responsivos baseados em viewport por consultas de contêiner quando apropriado. Adote OKLCH para cores personalizadas para obter suporte à gama P3.

---

Melhorias de desempenho

O mecanismo Oxide do Tailwind v4 (Rust) oferece compilações mensuravelmente mais rápidas:

Para aplicações grandes, isso se traduz em HMR visivelmente mais rápido no desenvolvimento e tempos de construção de CI significativamente mais curtos.

---

Exemplo de migração no mundo real

Aqui está um antes/depois prático para a configuração básica de um sistema de design:

// Before: tailwind.config.js (v3)
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#fef3c7',
          500: '#f59e0b',
          900: '#78350f',
        },
      },
      fontFamily: {
        sans: ['Inter', 'system-ui'],
      },
      boxShadow: {
        card: '0 1px 3px rgba(0,0,0,0.12)',
      },
    },
  },
  plugins: [
    require('@tailwindcss/typography'),
    require('@tailwindcss/forms'),
  ],
};

/* After: globals.css (v4) */
@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";

@theme {
  --color-brand-50: oklch(97% 0.04 85);
  --color-brand-500: oklch(78% 0.18 85);
  --color-brand-900: oklch(33% 0.08 85);

  --font-sans: 'Inter', system-ui, sans-serif;

  --shadow-card: 0 1px 3px oklch(0% 0 0 / 12%);
}

A configuração nativa do CSS é mais concisa e elimina a dependência node_modules para leitura da configuração.

---

Perguntas frequentes

Preciso excluir tailwind.config.js imediatamente?

Não – Tailwind v4 suporta configuração JS e configuração CSS simultaneamente durante a migração. A configuração JS ainda funciona, mas recursos como @theme em CSS só estão disponíveis sem ela. Migre de forma incremental: primeiro crie o aplicativo com a v4, depois mova gradualmente a configuração para CSS e, em seguida, exclua a configuração JS quando estiver confiante.

Minhas classes existentes do Tailwind v3 ainda funcionarão na v4?

A grande maioria das classes de utilidade permanece inalterada. Alguns nomes de cores foram atualizados (cinza → neutro em alguns contextos) e alguns utilitários obsoletos foram removidos. Execute npx @tailwindcss/upgrade@next para detectar a maioria dos problemas automaticamente. As principais incompatibilidades estão nos plugins e na configuração do tema customizado, e não na forma como você usa classes em HTML/JSX.

O OKLCH é compatível com todos os navegadores?

OKLCH é compatível com todos os navegadores modernos (Chrome 111+, Firefox 113+, Safari 15.4+). Tailwind v4 gera substitutos para navegadores mais antigos quando necessário. Para a gama de cores P3 (as cores expandidas), o suporte requer uma exibição de gama ampla e um navegador compatível – o Tailwind gera substitutos rgb() para exibições de gama mais estreita.

Como faço para usar o Tailwind v4 com shadcn/ui?

shadcn/ui 2.0+ suporta Tailwind v4. Atualize seu components.json para usar o formato de variáveis ​​CSS v4. A biblioteca de componentes usa propriedades personalizadas CSS para temas, que mapeiam naturalmente para o sistema @theme do Tailwind v4. Execute npx shadcn@latest init em um projeto existente para obter a configuração compatível com v4.

Existem tipos TypeScript para a nova configuração?

A configuração do Tailwind v4 é CSS, portanto não há tipos TypeScript para a configuração em si. O suporte IDE vem de serviços de linguagem CSS que entendem propriedades personalizadas. Para acessar valores de tema em TypeScript (para gráficos, animações, etc.), use getComputedStyle para ler propriedades personalizadas CSS em tempo de execução ou gere um arquivo de tokens de seu CSS como parte de sua construção.

---

Próximas etapas

Tailwind CSS v4 é uma atualização significativa que vale a pena adotar para novos projetos e planejar os existentes. A pilha de front-end do ECOSIRE executa Tailwind CSS v4.1 em produção em um aplicativo Next.js 16 de 249 páginas com um sistema de design abrangente.

Precisa de ajuda com a migração do Tailwind v4 ou deseja um sistema de design construído do zero? Explore nossos serviços de engenharia de front-end para ver como podemos ajudar.