Como instalar o Tailwind CSS v4: CLI, Vite e PostCSS

No Tailwind v4, a instalação mínima é um pacote de integração e uma linha @import "tailwindcss". Você escolhe CLI, Vite ou PostCSS conforme a ferramenta que já constrói o projeto; não escolhe três ao mesmo tempo.

Todos os comandos abaixo foram executados num diretório criado com mktemp, no Node 26.3.0. O projeto da demonstração é uma página solta da clínica. Se a ideia utility-first ainda não está clara, leia primeiro o que é Tailwind.

O que a versão 4 removeu do primeiro passo

Tutoriais da versão 3 normalmente começam com tailwindcss init e criam um arquivo JavaScript de configuração. Esse não é o fluxo da v4. O tema e as fontes de conteúdo podem morar no próprio CSS.

@import "tailwindcss";

Não execute o comando abaixo seguindo material antigo:

npx tailwindcss init -p

No pacote atual, o binário fica em @tailwindcss/cli, e a configuração é CSS-first. Misturar as instruções deixa o aluno com dependências certas e arquivos errados — um dos casos tratados em Tailwind não aplica classes.

Caminho 1: CLI para HTML sem bundler

Crie uma pasta vazia e instale os dois pacotes com versão fixada se você quiser reproduzir esta saída.

npm install --save-exact tailwindcss@4.3.3 @tailwindcss/cli@4.3.3

Crie src.css e um index.html. O import traz tema, Preflight e utilitários; o scanner encontra o HTML automaticamente quando o comando roda na raiz.

@import "tailwindcss";

<button class="rounded-lg bg-cyan-600 px-4 py-2 font-bold text-white">
  Marcar consulta
</button>

Compile uma vez para confirmar a instalação:

npx @tailwindcss/cli -i src.css -o public/app.css --minify

O arquivo medido tinha 12.164 bytes porque a fonte de teste reunia classes de layout, tema, estados e responsividade. Um projeto menor gera outra quantidade; o número serve para provar que houve compilação, não como promessa de bundle.

Watch mantém o arquivo sincronizado

Durante o desenvolvimento, acrescente --watch. O processo fica aberto e recompila quando uma origem muda.

npx @tailwindcss/cli -i src.css -o public/app.css --watch

Mantenha o CSS gerado ligado no HTML:

<link rel="stylesheet" href="/app.css">

Se o navegador não muda, confirme três pontos nesta ordem: o processo continua rodando, o href aponta para o arquivo de saída e a classe completa existe no fonte. Procurar a classe com grep separa falha de geração de falha de cascata.

grep -F '.bg-cyan-600' public/app.css

Uma linha encontrada prova que o compilador fez sua parte. Resultado vazio significa que você precisa corrigir a fonte ou o build antes de abrir o DevTools.

Caminho 2: Vite com o plugin oficial

Para React, Vue ou um projeto web já construído por Vite, instale o plugin. A medição usou Vite 8.2.2 e @tailwindcss/vite 4.3.3.

npm install --save-exact tailwindcss@4.3.3 @tailwindcss/vite@4.3.3

No arquivo de configuração, acrescente o plugin ao array existente:

import { defineConfig } from 'vite';
import tailwindcss from '@tailwindcss/vite';

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

O CSS continua com o mesmo import e deve ser importado pelo ponto de entrada da aplicação. O servidor do Vite cuida do hot reload; você não abre um segundo processo tailwindcss --watch.

import './src.css';

Esse detalhe evita compilação duplicada e resultados diferentes entre o CSS servido pelo Vite e um arquivo solto esquecido em public.

Caminho 3: PostCSS quando o pipeline já usa plugins

Use PostCSS quando o seu bundler já expõe essa etapa ou quando a infraestrutura do projeto exige uma cadeia de transformações CSS.

npm install --save-exact tailwindcss@4.3.3 @tailwindcss/postcss@4.3.3

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

Não instale autoprefixer só por hábito de um tutorial antigo. A v4 usa sua própria pipeline moderna. Se o projeto já depende do plugin por outra razão, avalie separadamente; instalação mínima é uma ferramenta de diagnóstico.

@source resolve monorepo e biblioteca ignorada

O v4 detecta fontes automaticamente, ignorando binários, arquivos no .gitignore e dependências. Quando as classes ficam num pacote compartilhado, registre o caminho explicitamente:

@import "tailwindcss" source("../src");
@source "../node_modules/@empresa/ui";

Para uma medição isolada, desative a detecção automática e declare somente o arquivo desejado. Foi assim que os bundles desta trilha foram reproduzidos sem capturar classes de outros exemplos:

@import "tailwindcss" source(none);
@source "./pagina.html";

Essa forma é especialmente útil quando um monorepo roda o build a partir de uma raiz diferente. O caminho é relativo à folha de estilo, não à imaginação do comando.

Erro reproduzido: o build funciona, mas a utility não existe

Uma instalação válida também precisa falhar de modo legível. O CLI 4.3.3 recebeu um @apply com o token de produto ainda não configurado:

@import "tailwindcss";
.qa { @apply bg-produto; }

printf '@import "tailwindcss"; .qa { @apply bg-produto; }\n' | npx @tailwindcss/cli@4.3.3 -i - -o /dev/null

O código de saída foi 1. Isso confirma que o executável está rodando; a correção é declarar o token ou usar uma cor disponível, não reinstalar o pacote.

O teste de dez segundos

Coloque bg-cyan-600 num botão, compile e procure a regra no arquivo final. Depois troque para bg-rose-600 e confirme que a nova regra aparece. Se as duas mudanças ocorrerem, instalação e detecção estão funcionando. Continue pelo sistema de espaçamento e volte a personalizar @theme apenas quando a base já estiver estável.

Deixe a instalação reproduzível para outra pessoa

Fixe versões no lockfile e registre um script em package.json. O comando precisa funcionar a partir da raiz documentada, sem depender de um diretório que só existe na sua máquina. Num monorepo, declare a base de fontes em vez de pedir que cada pessoa execute o build de um lugar diferente.

Separe saída de desenvolvimento e produção. Watch privilegia feedback rápido; o build final usa minificação e deve falhar quando a compilação falha. Não versione dois arquivos gerados por pipelines concorrentes. Escolha quem possui o artefato: CLI, Vite ou PostCSS.

Faça ainda um teste limpo. Remova o diretório de saída temporário, instale pelas dependências registradas e rode o script de produção. Se só funciona depois de um comando manual não documentado, a instalação não terminou. O curso de Tailwind usa esse mesmo critério antes de começar a página final, e o guia da trilha ajuda a decidir se o custo de build faz sentido para o tipo de projeto.