Linter e formatter: guia de configuração passo a passo

Configurar linter e formatter no seu projeto é um dos passos que mais economiza tempo no médio prazo. O linter analisa o código em busca de erros, más práticas e padrões inconsistentes. O formatter, por sua vez, reescreve a formatação para seguir um estilo único. Juntos, eles eliminam discussões sobre espaços e vírgulas, e ainda pegam bugs antes do commit. Este guia mostra o caminho para integrar essas ferramentas, usando exemplos com JavaScript, mas os conceitos servem para qualquer linguagem.

Pré-requisitos

Antes de começar, você precisa de um projeto com um gerenciador de pacotes ativo (npm, yarn ou pnpm) e um editor de código, como VS Code. Não é necessário configurar nada manualmente no editor, pois as ferramentas funcionam por linha de comando. O resultado esperado é que, ao rodar um comando, o código seja verificado e formatado automaticamente.

Passo 1: Instale o linter e o formatter

No terminal, dentro da pasta do projeto, instale as duas ferramentas como dependências de desenvolvimento. Para JavaScript, os nomes mais comuns são ESLint e Prettier. O comando abaixo instala ambos:

npm install --save-dev eslint prettier

O ESLint cuida da análise estática, enquanto o Prettier cuida da formatação. Eles trabalham juntos, mas cada um tem uma função. O erro comum aqui é instalar apenas um e esperar que ele faça tudo. Linter não formata bem, e formatter não encontra erros de lógica.

Passo 2: Crie os arquivos de configuração

O ESLint precisa de um arquivo de configuração, que pode ser criado com o comando:

npx eslint --init

Esse comando faz perguntas sobre o estilo do projeto e gera um arquivo .eslintrc. O Prettier, por sua vez, usa um arquivo .prettierrc, que pode ser criado manualmente com regras simples, como aspas simples e sem ponto e vírgula:

{ "singleQuote": true, "semi": false }

Dica: mantenha as regras de formatação no Prettier e as regras de qualidade no ESLint. Misturar os dois arquivos causa conflitos e confusão.

Passo 3: Integre o formatter ao linter

Para que o ESLint não reclame de regras que o Prettier já resolve, instale o plugin de compatibilidade:

npm install --save-dev eslint-config-prettier

Depois, adicione "prettier" à lista de extends no arquivo de configuração do ESLint. Isso desativa regras de formatação que conflitam com o Prettier. O erro comum é pular esse passo e depois ver o ESLint marcando erros que o Prettier formata de forma diferente.

Passo 4: Rode os comandos no projeto

Com tudo configurado, teste os comandos no terminal:

npx eslint . --fix npx prettier --write .

O primeiro comando analisa e corrige erros que podem ser resolvidos automaticamente. O segundo reescreve todos os arquivos com a formatação padrão. O ideal é rodar os dois na ordem: primeiro o linter, depois o formatter.

Dica: adicione esses comandos ao package.json, na seção scripts, para não precisar digitar tudo toda vez. Por exemplo, "lint": "eslint . --fix" e "format": "prettier --write .".

Passo 5: Automatize no editor e no commit

Para que o linter e o formatter rodem sem você pensar nisso, configure o editor para formatar ao salvar. No VS Code, basta adicionar ao settings.json:

{ "editor.formatOnSave": true, "editor.defaultFormatter": "esbenp.prettier-vscode" }

Outra camada de automação é usar um hook de pré-commit, como o Husky, para rodar o linter antes de cada commit. Isso impede que código fora do padrão entre no histórico. O erro comum é confiar apenas no editor, que não roda em ambientes CI.

Checklist do que você fez

• Instalou ESLint e Prettier como dependências de desenvolvimento.
• Criou o arquivo de configuração do ESLint.
• Criou o arquivo de configuração do Prettier.
• Integrou o Prettier ao ESLint com eslint-config-prettier.
• Rodou os comandos de lint e format no projeto.
• Configurou o editor para formatar ao salvar.
• Automatizou a verificação com um hook de pré-commit (opcional).

FAQ

Qual a diferença entre linter e formatter?

O linter analisa o código em busca de erros de lógica, variáveis não utilizadas e más práticas. O formatter apenas reescreve a formatação, como espaços, aspas e quebras de linha, para seguir um padrão consistente. Um não substitui o outro.

Preciso configurar linter e formatter para cada projeto?

Sim, cada projeto tem suas próprias dependências e arquivos de configuração. Você pode copiar os arquivos de um projeto antigo, mas é recomendável revisar as regras para o contexto atual.

Linter e formatter funcionam com qualquer linguagem?

Sim, a maioria das linguagens tem ferramentas equivalentes. Para Python, por exemplo, o Ruff ou o Black cuidam da formatação, e o Flake8 ou o Pylint fazem a análise estática.

O que fazer quando o linter e o formatter entram em conflito?

Instale a configuração de compatibilidade, como eslint-config-prettier, e defina claramente quais regras pertencem a cada ferramenta. Em geral, o formatter cuida do estilo e o linter cuida da qualidade.

Devo rodar o linter antes ou depois do formatter?

Rode o linter primeiro, para corrigir erros que podem afetar a formatação, e depois o formatter para padronizar o resultado. Em muitos casos, o --fix do linter já ajusta parte da formatação.