Tailwind v4 + Vite: template completo de configuração em 5 minutos e estrutura de pastas

No ano passado, configurei o Tailwind em um projeto novo e, depois de meia hora, ainda estava ajustando os caminhos de content no tailwind.config.js. Naquela época, pensei: será que isso não poderia ser mais simples?

Neste ano, o Tailwind v4 finalmente conseguiu.

Agora, bastam três linhas de código para colocar um projeto Tailwind completo em funcionamento — sem configuração do PostCSS, sem tailwind.config.js e até sem indicar manualmente quais arquivos devem ser analisados. Quando vi essa mudança pela primeira vez, confesso que quase não acreditei.

Este artigo vai poupar aquela meia hora de trabalho. Você encontrará um template completo e uma estrutura de pastas que venho usando há seis meses e considero bastante prática.

1. Por que escolher Tailwind v4 + Vite?

1.1 A v4 é realmente tão rápida?

Segundo o projeto oficial, o build ficou 10 vezes mais rápido. Fiz um teste e um projeto de porte pequeno a médio passou de 8 segundos para menos de 1 segundo. O principal motivo desse ganho é o novo mecanismo Oxide — escrito em Rust, o que já diz bastante.

Mas a simplificação da configuração foi o que mais me agradou. Antes, para criar um projeto Tailwind, eu precisava editar três ou quatro arquivos: tailwind.config.js, postcss.config.js, a configuração do Vite e as diretivas @tailwind no arquivo CSS. Agora? Basta alterar um arquivo.

1.2 A velocidade do Vite é real

O servidor de desenvolvimento do Vite inicia quase instantaneamente. A atualização em tempo real (HMR) também é muito rápida: depois de editar o CSS, a página é atualizada praticamente sem atraso. Isso melhora tanto a experiência cotidiana de desenvolvimento que, depois de se acostumar, é difícil voltar atrás.

1.3 v3 vs. v4: comparação rápida

Antes de continuar, veja esta tabela:

Percebeu? A ideia central da v4 é levar a configuração do JS para o CSS. O que isso significa na prática? Você pode ajustar a configuração enquanto escreve os estilos, sem precisar alternar entre dois arquivos.

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

2. Template de configuração rápida em 5 minutos

Tudo pronto? Vamos começar.

2.1 Inicializar o projeto

Abra o terminal e execute estas linhas:

# Crie um novo projeto Vite usando o template TypeScript
npm create vite@latest my-project -- --template vanilla-ts

# Entre na pasta do projeto
cd my-project

# Instale as dependências
npm install

Essa etapa leva cerca de 30 segundos.

2.2 Instalar o Tailwind v4

# Instale o Tailwind CSS e o plugin oficial do Vite
npm install tailwindcss @tailwindcss/vite

É só essa linha. Não é necessário instalar postcss nem autoprefixer, pois a v4 já inclui esses recursos.

2.3 Configurar o Vite

Abra vite.config.ts e deixe o arquivo assim:

// vite.config.ts
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  // Basta adicionar o plugin do Tailwind
  plugins: [tailwindcss()],
})

Três linhas de código. É realmente simples assim.

2.4 Criar o arquivo CSS

Crie main.css dentro de src/styles/:

/* src/styles/main.css */

/* Importe o Tailwind — uma linha cuida de todos os estilos básicos */
@import "tailwindcss";

/* Configuração personalizada do tema (opcional) */
@theme {
  --color-primary: #3b82f6;
  --color-secondary: #10b981;
}

O bloco @theme é uma nova sintaxe da v4. Nele, você pode definir cores, fontes, espaçamentos e outros valores usando variáveis CSS. É muito mais intuitivo do que escrever um tailwind.config.js.

2.5 Importar o CSS

Abra src/main.ts e adicione uma linha no início:

// src/main.ts
import './styles/main.css'

// Seu código original...

2.6 Fazer um teste

Experimente este trecho em index.html ou em algum componente de página:

<div class="bg-primary text-white p-4 rounded-lg">
  O Tailwind v4 está funcionando!
</div>

Depois, execute:

npm run dev

Abra o navegador. Se aparecer um card com fundo azul, a configuração deu certo. Eu já cronometrei: realmente é possível colocá-la em funcionamento em menos de 5 minutos.

3. Estrutura de pastas recomendada

Depois que o projeto estiver funcionando, recomendo organizar os arquivos desta forma:

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

Ver preços →Anúncio

3.1 Estrutura completa de pastas

my-project/
├── public/
│   └── favicon.ico
├── src/
│   ├── components/
│   │   ├── ui/              # Componentes básicos de UI
│   │   │   ├── Button.ts
│   │   │   └── Input.ts
│   │   └── layout/          # Componentes de layout
│   │       ├── Header.ts
│   │       └── Footer.ts
│   ├── styles/
│   │   ├── main.css         # Ponto de entrada principal (importa o Tailwind)
│   │   ├── components.css   # Estilos relacionados a componentes
│   │   └── utilities.css    # Classes utilitárias personalizadas
│   ├── utils/
│   │   └── helpers.ts
│   ├── pages/               # Arquivos de página (em aplicações com várias páginas)
│   ├── assets/              # Recursos estáticos
│   │   ├── images/
│   │   └── fonts/
│   ├── main.ts
│   └── vite-env.d.ts
├── index.html
├── package.json
├── tsconfig.json
└── vite.config.ts

3.2 Por que separar assim?

Em components/ui/ ficam os componentes básicos — botões, campos de entrada, modais e assim por diante. Eles são altamente reutilizáveis e não dependem de uma lógica de negócio específica.

Em components/layout/ ficam os componentes de layout — Header, Footer e Sidebar. Eles definem a estrutura das páginas e têm uma função diferente da dos componentes de UI.

A pasta styles/ concentra os arquivos CSS. Depois do Tailwind v4, passei a preferir a gestão centralizada dos estilos, porque toda a configuração fica no CSS e é mais prático editar tudo no mesmo lugar.

A pasta utils/ reúne funções utilitárias, como funções puras para formatar datas ou processar strings.

3.3 Como organizar os arquivos CSS

/* src/styles/main.css — arquivo de entrada */

/* Importe o Tailwind */
@import "tailwindcss";

/* Importe os demais arquivos de estilo */
@import "./components.css";
@import "./utilities.css";

/* Estilos básicos globais */
@layer base {
  body {
    @apply bg-gray-50 text-gray-900;
  }

  /* Estilo padrão dos links */
  a {
    @apply text-primary hover:underline;
  }
}

@layer base é o mecanismo de camadas do Tailwind, usado para definir os estilos mais fundamentais. Ele é melhor do que escrever diretamente body { ... } porque o Tailwind cuida da prioridade dos estilos para você.

4. Checklist de migração da v3

Se você tem um projeto na v3 e quer fazer o upgrade, basta seguir este checklist. Migrei vários projetos há pouco tempo e marquei aqui os problemas que encontrei pelo caminho.

4.1 Migrar os arquivos de configuração

• Exclua tailwind.config.js (se ele contiver apenas configurações do Tailwind)
• Exclua postcss.config.js (se ele for usado apenas pelo Tailwind)
• Adicione @import "tailwindcss" ao arquivo CSS
• Atualize vite.config.ts para usar o plugin @tailwindcss/vite

4.2 Atualizar as dependências

# Remova as dependências antigas
npm uninstall postcss autoprefixer tailwindcss

# Instale as novas dependências
npm install tailwindcss @tailwindcss/vite

• Execute o comando de desinstalação
• Execute o comando de instalação
• Confira os números de versão no package.json

4.3 Ajustar os estilos

• Substitua @tailwind base; @tailwind components; @tailwind utilities; por @import "tailwindcss";
• Migre a configuração de tema do tailwind.config.js para o bloco @theme no CSS
• Confirme que as classes utilitárias personalizadas continuam funcionando

Exemplo de migração da configuração do tema:

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

/* main.css na v4 */
@theme {
  --color-primary: #3b82f6;
}

4.4 Testar e validar

• Execute npm run dev para verificar o ambiente de desenvolvimento
• Execute npm run build para confirmar que o build de produção termina com sucesso
• Abra a página e confirme que nenhum estilo desapareceu
• Edite um arquivo CSS e verifique se a atualização em tempo real está funcionando

5. Problemas comuns e soluções

Durante a configuração e o upgrade, estes foram os problemas que mais encontrei.

5.1 Os estilos não funcionam

Você escreveu class="bg-primary", mas a página continua toda branca. O que aconteceu?

Etapas de diagnóstico:

1. Abra as ferramentas de desenvolvedor do navegador e veja se o arquivo CSS foi carregado
2. Confirme se o arquivo CSS foi realmente importado em main.ts
3. Verifique se o plugin está configurado corretamente em vite.config.ts

Uma vez, isso aconteceu comigo porque esqueci de adicionar import './styles/main.css' em main.ts. É um erro básico, mas fácil de cometer.

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

Começar →Anúncio

5.2 A atualização em tempo real não funciona

Você altera o CSS, mas nada muda na página.

Etapas de diagnóstico:

1. Confirme se a versão do Vite é >= 5.0 (versões antigas têm problemas de compatibilidade)
2. Tente reiniciar o servidor de desenvolvimento
3. Limpe o cache do navegador ou abra uma janela anônima

Se ainda não funcionar, procure erros no console. Às vezes, o problema é causado por um conflito com outro plugin.

5.3 O CSS fica grande demais depois do build

Depois do build de produção, o arquivo CSS chega facilmente a centenas de KB.

Etapas de diagnóstico:

1. Confirme se você está usando uma versão recente da v4; o tree-shaking das versões antigas não era tão eficiente
2. Verifique se uma biblioteca de ícones inteira ou outra dependência grande foi importada
3. Use @layer para organizar os estilos em camadas; assim, o Tailwind consegue lidar melhor com prioridade e deduplicação

Na maioria dos casos, a saída da v4 já é bastante enxuta. Se ainda estiver grande demais, é bem provável que haja CSS personalizado em excesso.

Conclusão

Depois de todos esses detalhes, o essencial se resume a quatro pontos:

1. Instalação: npm install tailwindcss @tailwindcss/vite
2. Configuração do Vite: adicione o plugin tailwindcss()
3. CSS: use @import "tailwindcss" e configure o tema com @theme
4. Execução: npm run dev

A maior mudança da v4 em relação à v3 é a transferência da configuração do JS para o CSS. Pode parecer estranho no começo, mas, depois de algum tempo, achei a abordagem mais intuitiva: enquanto ajusto os estilos, também posso alterar a configuração, sem ficar alternando entre arquivos.

Se você estiver migrando da v3, lembre-se de converter a configuração de tema do tailwind.config.js para a sintaxe CSS do @theme. Isso pode levar algum tempo, mas o build mais rápido e a estrutura de projeto mais simples compensam o esforço.