Guia de Migração Tailwind CSS v4: Tudo que Mudou e Como Atualizar (2026)

O Tailwind CSS v4 não é só mais uma atualização de versão—é uma reescrita completa. O time reconstruiu o motor do zero usando Rust e Oxide, mudou como a configuração funciona, e removeu o plugin do PostCSS completamente. Se você tava adiando o upgrade, esse guia vai te mostrar tudo que mudou e exatamente como migrar.

Depois de atualizar três apps em produção, posso te dizer: a dor vale a pena. Os tempos de build caíram 3-10x, o CSS de saída é menor, e a nova config CSS-first é mais gostosa de usar depois que você se acostuma.

Bora ver o que mudou e como lidar com cada parte da migração.

O que mudou?

Antes dos passos, bora entender as mudanças grandes:

1. Novo Motor Escrito em Rust (Oxide)

O Tailwind v3 usava um motor baseado em JavaScript. O v4 usa o Oxide, um novo motor de alta performance escrito em Rust. Não é só uma reescrita—é fundamentalmente mais rápido:

O motor Rust também significa melhor paralelização e menor uso de memória. O HMR durante desenvolvimento agora parece instantâneo.

2. Configuração agora fica no CSS

Essa é a maior mudança. No v3 você configurava tudo no tailwind.config.js:

// v3: tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#3b82f6',
        secondary: '#10b981',
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
      },
    },
  },
}

No v4, a configuração vai pra dentro do seu arquivo CSS usando @theme:

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

@theme {
  --color-primary: #3b82f6;
  --color-secondary: #10b981;
  --font-sans: "Inter", sans-serif;
}

Por que isso importa:

• A configuração fica junto com seus estilos
• Melhor autocomplete da IDE pra valores custom
• CSS custom properties são nativas—inspeciona no DevTools
• Sem arquivo de config JS separado pra manter

3. Sem Plugin PostCSS

No v3, Tailwind era um plugin do PostCSS:

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

No v4, Tailwind é uma CLI standalone ou plugin do Vite. PostCSS ainda é suportado por compatibilidade, mas não é o padrão:

// v4: vite.config.ts (recomendado)
import tailwindcss from '@tailwindcss/vite'

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

# v4: alternativa CLI
npx @tailwindcss/cli -i input.css -o output.css --watch

4. Detecção Automática de Conteúdo

Lembra de configurar os paths de content no v3?

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

No v4, o Tailwind detecta automaticamente quais arquivos usam classes do Tailwind analisando seu projeto. Sem configuração pra maioria dos projetos. Se precisar customizar:

/* v4: Override da auto-detecção */
@import "tailwindcss";

@source "../node_modules/some-ui-library";

5. CSS Cascade Layers Nativo

O v4 usa CSS @layer nativo (não a implementação custom do Tailwind):

/* v4 gera layers CSS reais */
@layer theme, base, components, utilities;

@layer utilities {
  .text-primary { color: var(--color-primary); }
}

Isso te dá controle de cascade apropriado e melhor integração com outro CSS.

Passos de Migração

Bora pro que interessa. Vou mostrar os passos pra um projeto típico React/Next.js.

Passo 1: Atualizar Dependências

Remove os pacotes antigos do Tailwind e instala o v4:

# Remove pacotes v3
npm uninstall tailwindcss postcss autoprefixer

# Instala v4
npm install tailwindcss@latest

# Se usa Vite, adiciona o plugin
npm install @tailwindcss/vite

# Se usa Next.js, adiciona o pacote de compatibilidade PostCSS
npm install @tailwindcss/postcss

Passo 2: Atualizar Configuração de Build

Pra projetos Vite:

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

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

Pra projetos Next.js:

Next.js 15+ tem suporte nativo pro Tailwind v4. Pra versões anteriores:

// postcss.config.js (compatibilidade Next.js)
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

Pra CLI standalone:

# Adiciona nos scripts do package.json
"scripts": {
  "css:build": "npx @tailwindcss/cli -i src/input.css -o dist/output.css",
  "css:watch": "npx @tailwindcss/cli -i src/input.css -o dist/output.css --watch"
}

Passo 3: Converter seu Ponto de Entrada CSS

Aqui é onde a maior parte do trabalho acontece. Seu arquivo CSS principal precisa ser reescrito.

Antes (v3):

/* globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* Estilos custom abaixo */
.btn-primary {
  @apply bg-blue-500 text-white px-4 py-2 rounded;
}

Depois (v4):

/* globals.css */
@import "tailwindcss";

/* Estilos custom - agora usa @layer direitinho */
@layer components {
  .btn-primary {
    @apply bg-blue-500 text-white px-4 py-2 rounded;
  }
}

Mudanças principais:

• @tailwind base/components/utilities → @import "tailwindcss"
• Classes de componente custom devem ficar em @layer components
• Overrides de utilities vão em @layer utilities

Passo 4: Migrar tailwind.config.js pro @theme

Essa é a parte mais tricky. Você precisa converter a configuração JavaScript pra CSS custom properties.

Antes (config v3):

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          50: '#eff6ff',
          100: '#dbeafe',
          500: '#3b82f6',
          600: '#2563eb',
          700: '#1d4ed8',
        },
        accent: '#f59e0b',
      },
      spacing: {
        '18': '4.5rem',
        '88': '22rem',
      },
      fontSize: {
        'xxs': '0.625rem',
      },
      borderRadius: {
        '4xl': '2rem',
      },
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif'],
        mono: ['JetBrains Mono', 'monospace'],
      },
      screens: {
        'xs': '475px',
        '3xl': '1920px',
      },
    },
  },
}

Depois (v4 @theme):

/* globals.css */
@import "tailwindcss";

@theme {
  /* Cores usam prefixo --color-* */
  --color-primary-50: #eff6ff;
  --color-primary-100: #dbeafe;
  --color-primary-500: #3b82f6;
  --color-primary-600: #2563eb;
  --color-primary-700: #1d4ed8;
  --color-accent: #f59e0b;

  /* Spacing usa prefixo --spacing-* */
  --spacing-18: 4.5rem;
  --spacing-88: 22rem;

  /* Font size usa prefixo --text-* */
  --text-xxs: 0.625rem;

  /* Border radius usa prefixo --radius-* */
  --radius-4xl: 2rem;

  /* Font family usa prefixo --font-* */
  --font-sans: "Inter", system-ui, sans-serif;
  --font-mono: "JetBrains Mono", monospace;

  /* Breakpoints usam prefixo --breakpoint-* */
  --breakpoint-xs: 475px;
  --breakpoint-3xl: 1920px;
}

Cheat Sheet de Nomes de Variáveis

Passo 5: Lidar com Plugins

A maioria dos plugins v3 precisa de updates ou foi absorvida no core.

Plugin Typography:

npm install @tailwindcss/typography@latest

/* v4: Importa o plugin no CSS */
@import "tailwindcss";
@plugin "@tailwindcss/typography";

Plugin Forms:

npm install @tailwindcss/forms@latest

@import "tailwindcss";
@plugin "@tailwindcss/forms";

Plugin Container Queries:

Agora tá no core! Não precisa de plugin:

<!-- Funciona nativamente no v4 -->
<div class="@container">
  <div class="@md:grid-cols-2">...</div>
</div>

Passo 6: Atualizar Utilities Deprecadas

Algumas utilities foram renomeadas ou mudaram:

Modificadores de opacidade agora são o padrão:

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

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

Passo 7: Atualizar Dark Mode

Dark mode ainda funciona do mesmo jeito, mas a configuração mudou de lugar:

/* v4: Habilita dark mode baseado em classe */
@import "tailwindcss";

@variant dark (&:where(.dark, .dark *));

Ou usa o padrão (prefers-color-scheme):

/* Esse é o padrão - não precisa de config */
@import "tailwindcss";

Problemas Comuns de Migração e Soluções

Depois de migrar vários projetos, esses são os problemas que você provavelmente vai encontrar:

Problema 1: "Unknown at-rule @tailwind"

Seu editor/linter ainda tá esperando sintaxe v3.

Solução: Atualiza seu arquivo CSS pra usar @import "tailwindcss" em vez das diretivas antigas.

Problema 2: Cores Custom Não Funcionando

Sintoma: bg-primary-500 não funciona depois da migração.

Solução: Garante que suas variáveis de cor usem a convenção exata de nomes:

/* Errado */
--primary-500: #3b82f6;

/* Certo */
--color-primary-500: #3b82f6;

Problema 3: Erros de PostCSS no Next.js

Sintoma: Build falha com erros relacionados ao PostCSS.

Solução: Garante que tá usando o pacote de compatibilidade:

npm install @tailwindcss/postcss

// postcss.config.js
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

Problema 4: Plugins Não Carregando

Sintoma: Classes do plugin typography ou forms não funcionam.

Solução: Plugins agora carregam via CSS, não config:

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

Problema 5: Detecção de Conteúdo Perdendo Arquivos

Sintoma: Classes em certos arquivos não geram CSS.

Solução: Usa @source pra incluir paths explicitamente:

@import "tailwindcss";

@source "../node_modules/@your-company/ui-kit/src";
@source "./content/**/*.mdx";

Problema 6: IDE Não Reconhece Nova Sintaxe

Solução: Atualiza a extensão Tailwind CSS IntelliSense do VS Code pra versão mais recente. Ela suporta totalmente a sintaxe v4 incluindo @theme e @plugin.

Comparação de Performance: Números Reais

Isso é o que medimos numa app Next.js em produção (500+ componentes):

O motor Oxide é realmente tão rápido assim. Se você tá num codebase grande, o upgrade vale a pena só pela performance.

Checklist de Migração

Usa esse checklist pra sua migração:

• Atualizar dependências (tailwindcss@latest, remover pacotes antigos)
• Escolher integração: plugin Vite, PostCSS, ou CLI
• Converter diretivas @tailwind pra @import "tailwindcss"
• Mover tema do tailwind.config.js pro @theme no CSS
• Atualizar plugins pra usar sintaxe @plugin
• Converter classes de opacidade pra sintaxe de modificador (/50)
• Atualizar utilities renomeadas
• Configurar dark mode se usa estratégia de classe
• Adicionar @source pra paths de conteúdo não padrão
• Testar todas as páginas/componentes pra regressões visuais
• Atualizar extensão VS Code
• Remover arquivos de config antigos depois de confirmar que tudo funciona

Você Deveria Atualizar?

Atualiza agora se:

• Os tempos de build são sofridos (v4 é 5-10x mais rápido)
• Você quer bundles CSS menores
• Tá começando um projeto novo
• Curte a abordagem de configuração CSS-first

Espera se:

• Depende muito de plugins que ainda não foram atualizados
• Tá no meio de um release crítico
• Seu tailwind.config.js tem lógica programática complexa

Pra maioria dos projetos, o upgrade leva 1-4 horas dependendo da complexidade do config. Os ganhos de performance são reais—o Tailwind v4 é o upgrade de framework CSS mais suave que fiz nos últimos anos.

Conclusão

Tailwind v4 é um upgrade importante—novo motor, novo paradigma de config, novos defaults. A abordagem CSS-first com @theme parece estranha no começo mas faz sentido quanto mais você usa. A config fica visível no DevTools, a IDE funciona melhor, e seu CSS vira a fonte da verdade.

O motor Oxide é genuinamente rápido. Hot reloads instantâneos. Builds 5-10x mais rápidos. Se você tá num projeto grande, só isso justifica migrar.

Começa com algo simples pra se acostumar, depois ataca seu codebase principal. Não é complicado—só diferente.

Bom styling pra você.