Linter e Formatter: como configurar no seu projeto

Manter o código limpo e padronizado é uma daquelas tarefas que ninguém gosta de fazer, mas todo mundo percebe quando não é feita. Configurar linter e formatter no seu projeto resolve esse problema antes que ele vire discussão em code review. O resultado: menos erros banais, menos retrabalho e uma base de código que qualquer pessoa da equipe consegue ler sem sustos.

Antes de começar, você vai precisar de um projeto Node.js já iniciado (com package.json) e de um editor como VS Code, Sublime Text ou WebStorm. Se ainda não tem um projeto, rode npm init -y na pasta desejada. O guia usa ESLint como linter e Prettier como formatter, a combinação mais comum no ecossistema JavaScript, mas os princípios se aplicam a outras linguagens.

Passo 1: Instalar ESLint e Prettier como dependências de desenvolvimento

O primeiro passo é instalar os pacotes. Use o npm ou yarn para adicionar ESLint e Prettier como dependências de desenvolvimento, já que eles só são necessários durante o desenvolvimento, não em produção.

npm install --save-dev eslint prettier

Se o seu projeto usa React, TypeScript ou Vue, instale também os plugins específicos:

npm install --save-dev eslint-plugin-react @typescript-eslint/eslint-plugin @typescript-eslint/parser

Dica: evite instalar globalmente. Cada projeto deve ter sua própria configuração para evitar conflitos entre versões e regras diferentes.

Erro comum: esquecer o --save-dev e instalar como dependência de produção, o que aumenta o tamanho do bundle em projetos front-end. Verifique o package.json depois da instalação.

Passo 2: Inicializar a configuração do ESLint

Com os pacotes instalados, execute o comando de inicialização interativa do ESLint:

npx eslint --init

O assistente vai fazer perguntas sobre o tipo de projeto (módulos ES6 ou CommonJS), framework (React, Vue, nenhum) e se o código usa TypeScript. Responda de acordo com o seu projeto. Ao final, ele cria um arquivo .eslintrc.json (ou .js ou .yaml, dependendo da escolha) na raiz do projeto.

Se preferir configurar manualmente, crie o arquivo .eslintrc.json com o conteúdo mínimo:

{ "env": { "browser": true, "es2021": true, "node": true }, "extends": "eslint:recommended", "parserOptions": { "ecmaVersion": "latest", "sourceType": "module" }, "rules": { "no-unused-vars": "warn", "no-console": "off" } }

Dica: comece com o preset eslint:recommended e só adicione regras próprias quando sentir necessidade. Regras demais no início podem gerar centenas de erros e desanimar a equipe.

Erro comum: pular a etapa de configuração e usar o ESLint com as regras padrão, que são muito permissivas. Sem um arquivo de configuração, o ESLint não analisa nada.

Passo 3: Criar o arquivo de configuração do Prettier

Diferente do ESLint, o Prettier não precisa de um comando de inicialização. Basta criar o arquivo .prettierrc na raiz do projeto. Ele pode ser JSON, YAML ou TOML. Um exemplo mínimo:

{ "semi": true, "singleQuote": true, "tabWidth": 2, "trailingComma": "es5", "printWidth": 80 }

Cada opção define um aspecto da formatação: ponto e vírgula no final das linhas, aspas simples em vez de duplas, indentação de 2 espaços, vírgula no último item de objetos/arrays (ES5) e largura máxima de 80 caracteres por linha.

Dica: defina printWidth entre 80 e 100 caracteres. Linhas muito longas dificultam a leitura em monitores widescreen e em pull requests no GitHub.

Erro comum: criar o arquivo com extensão .prettierrc.js e esquecer de exportar o objeto. O Prettier não lê arquivos JS sem module.exports.

Passo 4: Integrar ESLint e Prettier para evitar conflitos

ESLint e Prettier podem entrar em conflito porque ambos tentam controlar formatação (espaços, aspas, ponto e vírgula). Para evitar isso, instale o pacote eslint-config-prettier, que desativa todas as regras de formatação do ESLint que conflitam com o Prettier:

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

Depois, adicione "prettier" ao final da lista extends no .eslintrc.json:

{ "extends": [ "eslint:recommended", "prettier" ] }

Dica: coloque o "prettier" sempre por último no extends. A ordem importa: o último preset sobrescreve os anteriores.

Erro comum: esquecer de instalar o pacote e só colocar no extends. Isso faz o ESLint procurar por um módulo que não existe e lançar erro.

Passo 5: Configurar scripts no package.json

Para rodar o linter e o formatter via terminal, adicione scripts no package.json:

"scripts": { "lint": "eslint .", "lint:fix": "eslint . --fix", "format": "prettier --write ." }

• npm run lint verifica todos os arquivos sem modificar.
• npm run lint:fix corrige automaticamente erros que o ESLint consegue consertar.
• npm run format aplica o Prettier em todos os arquivos do projeto.

Dica: execute npm run format antes de cada commit para garantir que o código está formatado. Ferramentas como Husky podem automatizar isso com hooks de pre-commit.

Erro comum: rodar prettier --write . sem ter um arquivo .prettierignore para excluir node_modules e dist. Isso pode travar o terminal ou modificar arquivos que não deveriam ser tocados.

Passo 6: Configurar o editor para formatar ao salvar

A etapa final é fazer o editor aplicar o formatter automaticamente ao salvar o arquivo. No VS Code, instale as extensões ESLint e Prettier. Depois, adicione ao settings.json do usuário ou do workspace:

{ "editor.defaultFormatter": "esbenp.prettier-vscode", "editor.formatOnSave": true, "editor.codeActionsOnSave": { "source.fixAll.eslint": true } }

Isso faz o Prettier formatar ao salvar e o ESLint corrigir erros automaticamente. No WebStorm, a configuração é feita nas settings em "Tools > Actions on Save".

Dica: teste com um arquivo bagunçado (espaços extras, aspas duplas) e veja se ele é corrigido ao salvar. Se não funcionar, verifique se a extensão está ativada para o projeto.

Erro comum: configurar formatOnSave sem definir defaultFormatter, o que faz o editor usar o formatador padrão (que pode ser o TypeScript ou HTML), ignorando o Prettier.

Checklist do que foi configurado

• [ ] ESLint e Prettier instalados como dependências de desenvolvimento
• [ ] Arquivo .eslintrc.json criado (manual ou via --init)
• [ ] Arquivo .prettierrc criado com opções básicas
• [ ] eslint-config-prettier instalado e adicionado ao extends
• [ ] Scripts lint, lint:fix e format no package.json
• [ ] Editor configurado para formatar ao salvar
• [ ] .prettierignore criado (pelo menos com node_modules e dist)

Perguntas Frequentes

Qual a diferença entre linter e formatter?

Linter (como ESLint) analisa o código em busca de erros lógicos, variáveis não usadas, más práticas e problemas de segurança. Formatter (como Prettier) cuida apenas da aparência: espaçamento, aspas, ponto e vírgula, quebra de linha. Um complementa o outro.

Preciso dos dois ou um só basta?

Usar apenas o linter resolve problemas de qualidade, mas deixa a formatação por conta de cada desenvolvedor. Usar apenas o formatter padroniza a aparência, mas não captura erros. A combinação dos dois é o padrão recomendado em projetos profissionais.

Como evitar conflitos entre ESLint e Prettier?

Instale o pacote eslint-config-prettier e adicione "prettier" ao final da lista extends no .eslintrc.json. Isso desativa as regras de formatação do ESLint que competem com o Prettier. Para regras específicas, use eslint-plugin-prettier (roda Prettier como regra do ESLint), mas isso pode deixar o lint mais lento.

O que colocar no .prettierignore?

Pastas e arquivos que não precisam de formatação: node_modules, dist, build, coverage, *.min.js, *.json (se preferir), e arquivos gerados automaticamente. O Prettier respeita o .gitignore se nenhum .prettierignore existir, mas é mais seguro criar um próprio.

Como configurar linter e formatter em projetos TypeScript?

Instale @typescript-eslint/eslint-plugin e @typescript-eslint/parser, e configure o parser no .eslintrc.json para "@typescript-eslint/parser". O Prettier funciona com TypeScript sem configuração extra. O resto do processo é idêntico ao JavaScript.

Vale a pena usar linter e formatter em projetos pequenos?

Sim, especialmente se o projeto pode crescer ou ser mantido por outras pessoas. A configuração leva 15 minutos e evita retrabalho futuro. Em projetos pessoais, ajuda a manter o hábito de escrever código limpo sem esforço consciente.