Analisando o Tailwind com o ESLint

Erros de digitação nos nomes de classes do Tailwind são erros silenciosos — o navegador simplesmente ignora classes desconhecidas sem emitir avisos no console. Uma letra ausente, como em bg-blue-50O (O maiúsculo em vez de zero), não aplica nenhum plano de fundo, e o problema pode passar despercebido por dias. O ESLint com um plug-in do Tailwind detecta esses problemas durante o desenvolvimento, antes que cheguem à produção.

O eslint-plugin-tailwindcss é o plug-in do ESLint mais usado para o Tailwind. Ele valida nomes de classes em relação à sua configuração do Tailwind, avisa sobre utilitários conflitantes e pode impor as convenções de ordenação de classes da sua equipe. Instale-o junto com o ESLint nas dependências de desenvolvimento do seu projeto.

No formato tradicional .eslintrc, adicione tailwindcss à matriz de plug-ins e amplie a configuração recomendada. O conjunto recomendado ativa as três regras principais: classnames-order, no-custom-classname e no-contradicting-classname.

Para o novo formato de configuração plana do ESLint 9, importe o plug-in e espalhe a configuração recomendada na sua matriz de configuração. Aponte a configuração tailwindConfig para o seu arquivo de configuração, para que o plug-in leia os valores personalizados do tema e os plug-ins ao validar os nomes de classes.

A regra no-contradicting-classname detecta utilitários conflitantes aplicados ao mesmo elemento — por exemplo, usar block e inline na mesma div ou w-full e w-auto juntos sem um prefixo responsivo. Esses conflitos produzem resultados imprevisíveis e difíceis de depurar sem o suporte de uma ferramenta de análise.

A regra no-custom-classname avisa quando você escreve uma classe que não faz parte da saída do Tailwind — nem um utilitário integrado nem um utilitário personalizado definido na sua configuração ou nos seus plug-ins. Isso ajuda a detectar erros de digitação e impede que desenvolvedores escrevam nomes de classes de CSS comum em um projeto Tailwind sem seguir os canais apropriados.

A regra classnames-order impõe a mesma ordem canônica de classes produzida pelo plug-in do Prettier. Ao usar as duas ferramentas, configure uma delas como fonte oficial da ordenação. A maioria das equipes usa o Prettier para a formatação automática e desativa a regra de ordenação do ESLint para evitar conflitos entre as duas ferramentas.

Se o seu projeto usa nomes de classes CSS personalizados junto com utilitários do Tailwind — por exemplo, classes de uma biblioteca de animação de terceiros ou de um CSS legado — adicione-os à configuração whitelist. Isso elimina falsos positivos e ainda detecta erros de digitação reais nos nomes de classes do Tailwind.

Adicione um script lint ao seu package.json que tenha como alvo todos os arquivos de template. Execute-o localmente e no CI para revelar erros nos nomes de classes antes que eles sejam mesclados. A opção --fix corrige automaticamente problemas de ordenação, mas não pode corrigir erros de digitação — eles exigem revisão manual.

Instale a extensão do ESLint para VS Code para ver erros sublinhados diretamente no editor enquanto você digita. Erros nas classes do Tailwind aparecem como avisos amarelos ou erros vermelhos no texto, tornando impossível não perceber um erro de digitação. Combine isso com a extensão Tailwind CSS IntelliSense para obter preenchimento automático, e a análise fechará completamente o ciclo de feedback.

Use o ESLint para validação — detectando erros de digitação, contradições e nomes de classes desconhecidos. Use o Prettier para formatação — ordenando as classes na ordem canônica. Desative a regra classnames-order do ESLint para que o Prettier seja o único responsável pela ordenação. Essa separação de responsabilidades permite aproveitar o melhor das duas ferramentas sem conflitos.

Nesta lição, você aprendeu a: instalar o eslint-plugin-tailwindcss para detectar erros de digitação e contradições, conhecer as três regras principais (no-contradicting-classname, no-custom-classname, classnames-order) e combinar o ESLint com o Prettier para que cada ferramenta seja responsável por sua função. A seguir, definiremos as convenções da equipe e um guia de estilo.