Como configurar ESLint e Prettier integrados em projetos TypeScript

1. Entendendo a função de cada ferramenta no ecossistema TypeScript

No desenvolvimento moderno com TypeScript, duas ferramentas se destacam para manter a qualidade e consistência do código: ESLint e Prettier. Embora ambas atuem na melhoria do código, suas funções são distintas e complementares.

ESLint é um linter — uma ferramenta de análise estática que identifica padrões problemáticos no código. Ele verifica erros lógicos, variáveis não utilizadas, práticas inseguras e violações de boas práticas. Para TypeScript, o ESLint utiliza parsers e plugins específicos que entendem a sintaxe avançada da linguagem, como tipos, interfaces e decorators.

Prettier é um formatador de código opinativo. Ele reescreve automaticamente o código seguindo regras predefinidas de estilo — indentação, uso de aspas simples ou duplas, ponto e vírgula, comprimento de linha, entre outros. Sua principal vantagem é eliminar discussões sobre formatação dentro da equipe.

Por que não usar apenas uma delas? Simples: ESLint não foi projetado para formatação de código, e Prettier não realiza análise semântica. Tentar usar ESLint para formatação exige regras conflitantes e manutenção complexa. A abordagem recomendada é usar ESLint para qualidade e Prettier para estilo, com integração adequada para evitar conflitos.

2. Pré-requisitos e estrutura inicial do projeto

Antes de configurar as ferramentas, precisamos de um projeto TypeScript básico. Inicie com:

mkdir meu-projeto-typescript
cd meu-projeto-typescript
npm init -y

Crie um arquivo tsconfig.json básico:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Agora instale as dependências necessárias. Todas devem ser dependências de desenvolvimento (--save-dev), pois não são necessárias em produção:

npm install --save-dev typescript
npm install --save-dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin
npm install --save-dev prettier eslint-config-prettier eslint-plugin-prettier

Detalhando cada pacote:
- typescript: O compilador TypeScript.
- eslint: O linter principal.
- @typescript-eslint/parser: Permite que o ESLint entenda sintaxe TypeScript.
- @typescript-eslint/eslint-plugin: Fornece regras específicas para TypeScript.
- prettier: O formatador de código.
- eslint-config-prettier: Desativa regras do ESLint que conflitam com o Prettier.
- eslint-plugin-prettier: Opcional — executa o Prettier como uma regra do ESLint.

3. Configuração do ESLint para TypeScript

Crie o arquivo eslint.config.js (formato moderno de configuração plana — flat config):

import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';
import prettierConfig from 'eslint-config-prettier';

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.recommended,
  prettierConfig,
  {
    rules: {
      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
      '@typescript-eslint/explicit-function-return-type': 'warn',
      '@typescript-eslint/no-explicit-any': 'warn',
      'no-console': 'warn',
    },
  },
  {
    ignores: ['dist/', 'node_modules/', '*.js'],
  }
);

Se preferir o formato tradicional .eslintrc.json:

{
  "parser": "@typescript-eslint/parser",
  "plugins": ["@typescript-eslint"],
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "prettier"
  ],
  "rules": {
    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
    "@typescript-eslint/explicit-function-return-type": "warn",
    "@typescript-eslint/no-explicit-any": "warn",
    "no-console": "warn"
  },
  "ignorePatterns": ["dist/", "node_modules/"]
}

Regras importantes explicadas:
- @typescript-eslint/no-unused-vars: Erro para variáveis não utilizadas, ignorando parâmetros começando com _.
- @typescript-eslint/explicit-function-return-type: Aviso para funções sem tipo de retorno explícito.
- @typescript-eslint/no-explicit-any: Aviso para uso de any.
- no-console: Aviso para console.log em produção.

4. Configuração do Prettier e alinhamento com ESLint

Crie o arquivo .prettierrc na raiz do projeto:

{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "all",
  "printWidth": 100,
  "bracketSpacing": true,
  "arrowParens": "always",
  "endOfLine": "lf"
}

Essas opções definem:
- semi: Ponto e vírgula obrigatório.
- singleQuote: Aspas simples preferidas.
- tabWidth: 2 espaços por indentação.
- trailingComma: Vírgula final em objetos e arrays.
- printWidth: Máximo de 100 caracteres por linha.
- arrowParens: Parênteses sempre em arrow functions.

O eslint-config-prettier já foi incluído na configuração do ESLint. Ele desativa todas as regras do ESLint relacionadas a formatação que poderiam conflitar com o Prettier.

Se você instalou eslint-plugin-prettier, pode integrar o Prettier como regra do ESLint. No arquivo de configuração do ESLint, adicione:

{
  "plugins": ["prettier"],
  "rules": {
    "prettier/prettier": "error"
  }
}

Isso faz com que qualquer diferença de formatação seja reportada como erro pelo ESLint.

5. Scripts no `package.json` e automação

Adicione os seguintes scripts ao package.json:

"scripts": {
  "lint": "eslint src/",
  "lint:fix": "eslint src/ --fix",
  "format": "prettier --write \"src/**/*.ts\"",
  "format:check": "prettier --check \"src/**/*.ts\"",
  "check": "npm run lint && npm run format:check",
  "fix": "npm run lint:fix && npm run format"
}

Para automação com husky e lint-staged (pré-commit):

npm install --save-dev husky lint-staged

Configure no package.json:

"lint-staged": {
  "*.ts": [
    "eslint --fix",
    "prettier --write"
  ]
}

Inicialize o Husky:

npx husky init
echo "npx lint-staged" > .husky/pre-commit

6. Integração com editores de código (VS Code)

Instale as extensões:
- ESLint (dbaeumer.vscode-eslint)
- Prettier (esbenp.prettier-vscode)

Configure o settings.json do VS Code (Ctrl+Shift+P → Preferences: Open Settings JSON):

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "eslint.validate": ["typescript", "javascript"],
  "prettier.requireConfig": true
}

Isso garante que:
- Ao salvar, o código seja formatado pelo Prettier.
- O ESLint corrija problemas automaticamente.
- O Prettier só atue se houver arquivo .prettierrc no projeto.

7. Boas práticas e resolução de problemas comuns

Ignorando arquivos: Crie .eslintignore e .prettierignore:

# .eslintignore
dist/
node_modules/
*.js

# .prettierignore
dist/
node_modules/
package.json
package-lock.json

Conflitos comuns: Se você encontrar conflitos entre ESLint e Prettier (ex: indentação ou aspas), a ordem de extensão no ESLint é crucial. O eslint-config-prettier deve ser o último na lista extends para sobrescrever regras conflitantes.

Verificação final: Crie um arquivo de teste src/index.ts:

const greeting: string = "Olá, TypeScript!";
console.log(greeting);

Execute:

npm run check

Se tudo estiver configurado corretamente, nenhum erro deve aparecer. O comando npm run fix deve formatar e corrigir automaticamente.

Configuração completa para um projeto real:

// .prettierrc
{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "all",
  "printWidth": 100,
  "bracketSpacing": true,
  "arrowParens": "always",
  "endOfLine": "lf"
}

// eslint.config.js
import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';
import prettierConfig from 'eslint-config-prettier';
import prettierPlugin from 'eslint-plugin-prettier';

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.recommended,
  prettierConfig,
  {
    plugins: {
      prettier: prettierPlugin,
    },
    rules: {
      'prettier/prettier': 'error',
      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
      '@typescript-eslint/explicit-function-return-type': 'warn',
      '@typescript-eslint/no-explicit-any': 'warn',
      'no-console': 'warn',
    },
  },
  {
    ignores: ['dist/', 'node_modules/', '*.js'],
  }
);

Com essa configuração, seu projeto TypeScript terá análise estática rigorosa e formatação consistente, eliminando discussões de estilo e prevenindo erros comuns antes mesmo do commit.

Referências

ESLint User Guide — Documentação oficial do ESLint com guias de configuração e regras.
TypeScript ESLint Getting Started — Guia oficial para configurar ESLint com TypeScript usando o parser e plugin recomendados.
Prettier Installation — Instruções oficiais de instalação e configuração do Prettier.
eslint-config-prettier — Repositório oficial do pacote que desativa regras conflitantes entre ESLint e Prettier.
Husky Documentation — Guia oficial do Husky para automação de hooks Git, incluindo integração com lint-staged.
lint-staged — Repositório oficial do lint-staged para executar linters em arquivos staged no Git.