Melhores Práticas de Linting

Q: O formato deve rodar antes ou depois do lint nos hooks?

Prettier primeiro, depois ESLint --fix - corresponde ao pre-commit e evita conflitos de correções.

Q: O NestJS precisa de regras ESLint diferentes?

Adicione @nestjs/eslint-plugin ou padrões recomendados para classes injetáveis e limites de módulos.

Q: Podemos pular o lint para PRs apenas de documentação?

Filtros de caminho podem pular o lint quando apenas *.md mudam; o padrão deve lintar em qualquer mudança TS.

Q: Quão rigorosos devem ser os overrides de teste?

Relaxe any e console; mantenha no-unused-vars e higiene de importação.

Portões de qualidade que mantêm bases de código TypeScript Node consistentes, rigorosas e aplicadas por CI.

Como Usar Esta Lista

Adote ao inicializar a configuração plana do ESLint em um novo serviço.
Aperte os avisos para erros assim que a base de código estiver limpa.
Execute os mesmos comandos localmente que a CI - sem regras exclusivas para IDE.

A - Configuração do ESLint

Use a configuração plana do ESLint 9 (eslint.config.js). O legado .eslintrc é um caminho depreciado para novos repositórios.
Ative typescript-eslint recomendado ou recommendedTypeChecked. Regras cientes de tipos capturam erros assíncronos.
Confirme ignores para dist/, node_modules/, coverage. Saída gerada nunca deve ser lintada.
Separe overrides para testes e scripts. Relaxe no-explicit-any apenas em testes.
Desative regras estilísticas do ESLint ao usar Prettier. eslint-config-prettier previne conflitos.

B - Formatação e Experiência do Desenvolvedor

Prettier para formato; ESLint para correção. Não debata tabs em revisões de código.
Formatar ao salvar documentado para VS Code/Cursor. Mesma extensão e configurações em toda a equipe.
format:check na CI. Verificação somente leitura em todo PR.
lint-staged em pre-commit opcional; CI é obrigatória. --no-verify não deve contornar a qualidade.
.prettierignore exclui OpenAPI gerado e dist. Evite mudanças de formato sem sentido.

C - Portões de Mesclagem da CI

npm run typecheck (tsc --noEmit) em todo PR. Tipos não são opcionais para backends TS.
npm run lint -- --max-warnings 0 para política de zero avisos. Avisos se tornam dívida rapidamente.
Ordem: install → typecheck → lint → test → build. Falhe rápido nas verificações mais baratas.
Fixe Node 24.18.0 na CI para corresponder aos engines locais. ESLint ciente de tipos usa a mesma versão TS.
Monorepos: turbo run lint typecheck com cache. Tarefas por pacote permanecem na ordem do grafo.

D - Arquitetura e Higiene

Proíba console.log em src/ via no-console. Use logger estruturado (Pino) no código da aplicação.
Forçe limites de importação com eslint-plugin-import-x ou Nx. Aplicações não importam aplicações irmãs.
no-extraneous-dependencies em código de produção. Dependências "phantom hoisted" escondem declarações ausentes.
Execute knip periodicamente para exports e dependências não utilizadas. Reduza a superfície de auditoria em monorepos.
Sem @ts-ignore sem comentário e ticket. Prefira @ts-expect-error com explicação.

E - Política e Propriedade

Documente como adicionar uma nova regra ESLint (RFC ou chat da equipe). Evite guerras de regras "drive-by" em PRs.
Compartilhe packages/eslint-config em monorepos. Uma única fonte de verdade para todos os serviços.
Versão do ESLint travada no lockfile raiz. npm ci garante paridade entre CI e local.
Corrija lint no PR que introduz violações. Não acumule dívida de lint "corrigir depois".
Combine portões de lint com checklist de revisão de código. Automação pega estrutura; humanos pegam design.

FAQs

Por que zero avisos?

Avisos são ignorados em semanas corridas e se tornam milhares de profundidade. --max-warnings 0 mantém a barra limpa.

ESLint ciente de tipos é obrigatório?

Fortemente recomendado para código Node assíncrono. Se for muito lento, escopo a configuração ciente de tipos apenas para src/.

O formato deve rodar antes ou depois do lint nos hooks?

Prettier primeiro, depois ESLint --fix - corresponde ao pre-commit e evita conflitos de correções.

Como adotamos lint em um repositório brownfield?

Um PR habilitando regras em nível de aviso, corrigindo ou suprimindo com tickets, depois mudando para erro por diretório.

O NestJS precisa de regras ESLint diferentes?

Adicione @nestjs/eslint-plugin ou padrões recomendados para classes injetáveis e limites de módulos.

Podemos pular o lint para PRs apenas de documentação?

Filtros de caminho podem pular o lint quando apenas *.md mudam; o padrão deve lintar em qualquer mudança TS.

E os linters SQL ou YAML?

Fora do escopo do ESLint; adicione ferramentas dedicadas, mas mantenha os portões TS inalterados.

Quão rigorosos devem ser os overrides de teste?

Relaxe any e console; mantenha no-unused-vars e higiene de importação.

Quem é o proprietário do pacote compartilhado `eslint-config`?

A equipe de plataforma ou arquitetura revisa as mudanças; os serviços consomem releases versionadas.

Como o lint interage com código gerado por IA?

Os mesmos portões se aplicam. O código gerado deve passar por lint, typecheck e test antes de mesclar.

Relacionados

Noções Básicas de Linting - guia de configuração plana
Integração com Prettier - configuração de formatar ao salvar
Typecheck na CI - portão tsc --noEmit

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.

Melhores Práticas de Linting

Portões de qualidade que mantêm bases de código TypeScript Node consistentes, rigorosas e aplicadas por CI.

Como Usar Esta Lista

Adote ao inicializar a configuração plana do ESLint em um novo serviço.
Aperte os avisos para erros assim que a base de código estiver limpa.
Execute os mesmos comandos localmente que a CI - sem regras exclusivas para IDE.

A - Configuração do ESLint

Use a configuração plana do ESLint 9 (eslint.config.js). O legado .eslintrc é um caminho depreciado para novos repositórios.
Ative typescript-eslint recomendado ou recommendedTypeChecked. Regras cientes de tipos capturam erros assíncronos.
Confirme ignores para dist/, node_modules/, coverage. Saída gerada nunca deve ser lintada.
Separe overrides para testes e scripts. Relaxe no-explicit-any apenas em testes.
Desative regras estilísticas do ESLint ao usar Prettier. eslint-config-prettier previne conflitos.

B - Formatação e Experiência do Desenvolvedor

Prettier para formato; ESLint para correção. Não debata tabs em revisões de código.
Formatar ao salvar documentado para VS Code/Cursor. Mesma extensão e configurações em toda a equipe.
format:check na CI. Verificação somente leitura em todo PR.
lint-staged em pre-commit opcional; CI é obrigatória. --no-verify não deve contornar a qualidade.
.prettierignore exclui OpenAPI gerado e dist. Evite mudanças de formato sem sentido.

C - Portões de Mesclagem da CI

npm run typecheck (tsc --noEmit) em todo PR. Tipos não são opcionais para backends TS.
npm run lint -- --max-warnings 0 para política de zero avisos. Avisos se tornam dívida rapidamente.
Ordem: install → typecheck → lint → test → build. Falhe rápido nas verificações mais baratas.
Fixe Node 24.18.0 na CI para corresponder aos engines locais. ESLint ciente de tipos usa a mesma versão TS.
Monorepos: turbo run lint typecheck com cache. Tarefas por pacote permanecem na ordem do grafo.

D - Arquitetura e Higiene

Proíba console.log em src/ via no-console. Use logger estruturado (Pino) no código da aplicação.
Forçe limites de importação com eslint-plugin-import-x ou Nx. Aplicações não importam aplicações irmãs.
no-extraneous-dependencies em código de produção. Dependências "phantom hoisted" escondem declarações ausentes.
Execute knip periodicamente para exports e dependências não utilizadas. Reduza a superfície de auditoria em monorepos.
Sem @ts-ignore sem comentário e ticket. Prefira @ts-expect-error com explicação.

E - Política e Propriedade

Documente como adicionar uma nova regra ESLint (RFC ou chat da equipe). Evite guerras de regras "drive-by" em PRs.
Compartilhe packages/eslint-config em monorepos. Uma única fonte de verdade para todos os serviços.
Versão do ESLint travada no lockfile raiz. npm ci garante paridade entre CI e local.
Corrija lint no PR que introduz violações. Não acumule dívida de lint "corrigir depois".
Combine portões de lint com checklist de revisão de código. Automação pega estrutura; humanos pegam design.

FAQs

Por que zero avisos?

Avisos são ignorados em semanas corridas e se tornam milhares de profundidade. --max-warnings 0 mantém a barra limpa.

ESLint ciente de tipos é obrigatório?

Fortemente recomendado para código Node assíncrono. Se for muito lento, escopo a configuração ciente de tipos apenas para src/.

O formato deve rodar antes ou depois do lint nos hooks?

Prettier primeiro, depois ESLint --fix - corresponde ao pre-commit e evita conflitos de correções.

Como adotamos lint em um repositório brownfield?

Um PR habilitando regras em nível de aviso, corrigindo ou suprimindo com tickets, depois mudando para erro por diretório.

O NestJS precisa de regras ESLint diferentes?

Adicione @nestjs/eslint-plugin ou padrões recomendados para classes injetáveis e limites de módulos.

Podemos pular o lint para PRs apenas de documentação?

Filtros de caminho podem pular o lint quando apenas *.md mudam; o padrão deve lintar em qualquer mudança TS.

E os linters SQL ou YAML?

Fora do escopo do ESLint; adicione ferramentas dedicadas, mas mantenha os portões TS inalterados.

Quão rigorosos devem ser os overrides de teste?

Relaxe any e console; mantenha no-unused-vars e higiene de importação.

Quem é o proprietário do pacote compartilhado `eslint-config`?

A equipe de plataforma ou arquitetura revisa as mudanças; os serviços consomem releases versionadas.

Como o lint interage com código gerado por IA?

Os mesmos portões se aplicam. O código gerado deve passar por lint, typecheck e test antes de mesclar.

Relacionados

Noções Básicas de Linting - guia de configuração plana
Integração com Prettier - configuração de formatar ao salvar
Typecheck na CI - portão tsc --noEmit

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.

Melhores Práticas de Linting

Buscar na documentação

Melhores Práticas de Linting