ESLint config

Configs compartilhados de ESLint, em flat config, para Node, React e Next.js.

O que vem junto

• Base neostandard (sucessor do eslint-config-standard);
• TypeScript via typescript-eslint;
• React, React Hooks e JSX a11y;
• Prettier, acoplado — a formatação vem junto, sem .prettierrc no projeto;
• Ordenação de imports (simple-import-sort) e higiene de import (import-x);
• Guarda-corpos de complexidade e clean code — ver a seção abaixo.

Requisitos

• ESLint ^9 — este pacote não roda em ESLint 10 ainda, ver ADR-0001;
• Node ^18.18 || ^20.9 || >=21.1.

Setup

npm i -D eslint @thasmorato/eslint-config

O ESLint procura por eslint.config.js na raiz. Não use mais .eslintrc.json.

Node.js

// eslint.config.js
import node from '@thasmorato/eslint-config/node'

export default node

React (sem Next.js)

// eslint.config.js
import react from '@thasmorato/eslint-config/react'

export default react

React (com Next.js)

O preset next é um fragmento: ele precisa ser composto com next/core-web-vitals. Sozinho ele falha, e isso é de propósito.

// eslint.config.js
import coreWebVitals from 'eslint-config-next/core-web-vitals'
import next from '@thasmorato/eslint-config/next'

export default [...next, ...coreWebVitals]

O eslint-config-next (v15+) já exporta flat config — não precisa de FlatCompat.

Ele registra os plugins react, react-hooks e jsx-a11y, e o flat config lança Cannot redefine plugin se dois blocos registram o mesmo plugin. Por isso o preset next não registra nenhum dos três: ele só ajusta as regras deles e deixa o Next ser o dono. Ver ADR-0005.

Ajustando no projeto

Flat config é um array; para sobrescrever, acrescente um bloco no fim:

import node from '@thasmorato/eslint-config/node'

export default [
  ...node,
  {
    rules: {
      'max-lines-per-function': ['warn', { max: 80 }],
    },
  },
]

Guarda-corpos de clean code

A severidade segue uma linha só: defeito é error, cheiro é warn. Um cheiro aparece no editor sem quebrar um build que já estava verde.

| Intenção | Regra | Sev | Valor | |---|---|---|---| | Funções pequenas | max-lines-per-function | warn | 50 | | Arquivo não vira God object | max-lines | warn | 300 | | Uma coisa só | max-statements | warn | 20 | | Poucos argumentos | max-params | warn | 4 | | Complexidade ciclomática | complexity | warn | 10 | | Complexidade cognitiva | sonarjs/cognitive-complexity | warn | 15 | | Aninhamento | max-depth | warn | 3 | | Callback hell | max-nested-callbacks | warn | 3 | | Níveis de abstração | sonarjs/no-nested-functions | warn | 3 | | I/O serializado em loop | no-await-in-loop | warn | — | | Sem efeito colateral escondido | no-param-reassign | error | props | | Nunca engolir erro | no-empty, sonarjs/no-ignored-exceptions | error | — | | DRY | sonarjs/no-identical-functions | warn | — |

Em arquivos de teste (*.spec.*, *.test.*, tests/, __tests__/) os limites de tamanho e de duplicação ficam desligados: um describe é uma função longa por natureza e fixture repete de propósito.

Sobre "validação de O notation"

Não existe. Complexidade assintótica é estaticamente indecidível — nenhum linter a calcula, e o eslint-plugin-complexity que aparece nas buscas está sem manutenção desde 2022.

O que este config entrega são os proxies tratáveis: max-depth e max-nested-callbacks pegam o aninhamento que costuma indicar custo polinomial, no-await-in-loop pega I/O serializado, e sonarjs/cognitive-complexity pega o que é caro de segurar na cabeça. É honesto chamar isso de guarda-corpo de complexidade, não de análise de Big-O.

Migrando da v1

A v2 é breaking em todos os eixos:

| v1 | v2 | |---|---| | .eslintrc.json com extends | eslint.config.js com import | | eslint@^8 | eslint@^9 | | eslint-config-standard | neostandard | | regras import/* | regras import-x/* | | CommonJS | ESM ("type": "module") |

Se você tem // eslint-disable-next-line import/no-duplicates espalhado, o prefixo virou import-x/.

Decisões

Os porquês estão em docs/adr/:

• ADR-0001 — por que ESLint 9 e não 10
• ADR-0002 — por que neostandard
• ADR-0003 — por que import-x sem as regras de resolução
• ADR-0004 — por que o Prettier segue acoplado
• ADR-0005 — por que o preset next não roda sozinho

Desenvolvimento

npm test           # node:test — linta fixtures via API do ESLint e afirma os ruleId
npm run lint       # o pacote se linta com o preset que publica (dogfood)
npm run test:consumer  # empacota, instala num projeto temporário e linta de lá

Release

Publicação automática no push pra main, a partir do tipo do commit (Conventional Commits):

| Commit | Bump | Use quando | |---|---|---| | fix: refactor: perf: | patch | corrige o config sem fazer regra nova disparar | | feat: | minor | regra nova entrando como warn | | feat!: / BREAKING CHANGE: | major | regra nova como error, warn→error, preset muda de forma | | chore: docs: ci: test: style: | — | sem release |

A convenção do meio é o que mantém o ^ seguro: regra nova nasce warn; promover pra error é major. Num config compartilhado, uma regra nova que dá error quebra o build de quem não mudou uma linha de código — por isso ela não pode entrar numa minor.

O bump vem de scripts/bump.js, que é função pura e tem teste (tests/bump.spec.js). O workflow roda testes, lint e o smoke test de consumidor antes de publicar, e só empurra a tag depois do publish dar certo — assim uma falha nunca deixa tag apontando pra versão que não foi ao ar.

Setup, uma vez

1. Trusted publishing no npm — em npmjs.com, na página do pacote → Settings → Trusted Publishers, adicione: repositório ThaSMorato/eslint-config, workflow release.yml. Não é preciso criar nem guardar NPM_TOKEN.

2. Tag inicial — o repo não tem tags. Sem uma, o primeiro run olha o histórico inteiro, encontra feat: antigos e publicaria 2.1.0. Marque o ponto de partida:

   git tag v2.0.0 && git push origin v2.0.0

   A partir daí a automação conta só o que vier depois.