Melhores Práticas de Linting e Formatação

Um resumo condensado das 25 melhores práticas mais importantes, extraídas de todas as páginas desta seção.

Use a Configuração Plana do ESLint 9: Adote eslint.config.mjs e exclua todos os arquivos .eslintrc.* restantes, pois o ESLint volta para o formato legado se ambos existirem e sua configuração plana for ignorada silenciosamente.
Conecte Presets com FlatCompat: Presets do Next.js ainda enviam configurações no estilo legado extends, então envolva-os com FlatCompat({ baseDirectory: __dirname }) e recrie __dirname via fileURLToPath(import.meta.url) em ESM.
Isole Ignora Globais: Na configuração plana, { ignores: [...] } só funciona como um ignore global quando é a única chave em seu objeto; misturá-lo com rules o transforma em um filtro por arquivo.
Comece com next/core-web-vitals: Ele agrupa eslint-plugin-react, react-hooks, next, import e jsx-a11y, então raramente você precisa instalar esses plugins separadamente e pode adicionar apenas o que está faltando.
Escolha a Severidade Intencionalmente: Use "error" para regras que você deseja impor (falhar CI, bloquear builds) e reserve "warn" para regras para as quais você está migrando, pois avisos passam na CI e se acumulam silenciosamente.
Prefira o no-unused-vars do TypeScript: Desative o no-unused-vars base e habilite @typescript-eslint/no-unused-vars com argsIgnorePattern: "^_" para que a sintaxe de interface/type-alias/enum seja entendida e os conflitos desapareçam.
Force consistent-type-imports: Exija import type { … } para imports apenas de tipos para que os bundlers possam apagar completamente os tipos e seu grafo de tipos permaneça claramente separado do seu grafo de valores.
Nunca Desative exhaustive-deps Globalmente: Mantenha react-hooks/exhaustive-deps ativado (geralmente como "warn") e suprima-o por linha com // eslint-disable-next-line apenas para referências comprovadamente estáveis como dispatch ou refs.
Ordene Imports com Separadores de Grupo: Configure import/order com categorias agrupadas (builtin, external, internal, parent/sibling, index, type), "newlines-between": "always" e alphabetização; execute eslint --fix uma vez e adicione quaisquer linhas em branco ausentes manualmente.
Não Re-registre Plugins Agrupados: Instalar um plugin que next/core-web-vitals já inclui (react, react-hooks, next, import, jsx-a11y) causa registro duplicado e comportamento inesperado de regras, então verifique o preset primeiro.
Escopo de Plugins Apenas para Testes com files: Proteja eslint-plugin-testing-library com files: ["**/*.test.{ts,tsx}", "**/*.spec.{ts,tsx}"]; aplicado globalmente, ele produz falsos positivos em código não relacionado a testes.
Profile Regras Lentas: Execute TIMING=1 npx eslint . quando os tempos de lint aumentarem - cinco ou mais plugins ativos podem diminuir significativamente o linting, e as regras @typescript-eslint que entendem tipos são 2-5x mais lentas porque exigem informações de tipo completas.
Coloque eslint-config-prettier por Último: A entrada "prettier" deve ser o último item em seu array extends, pois ela apenas desativa regras de formatação e qualquer configuração listada depois dela reativará conflitos.
Não Use eslint-plugin-prettier: Executar o Prettier dentro do ESLint é lento e inunda o editor com sublinhados vermelhos para diferenças puras de formatação - execute ESLint e Prettier como comandos separados em vez disso.
Sempre Envie um .prettierignore: Sem ele, o Prettier percorre .next/, node_modules/, arquivos de lock e código gerado; um arquivo de ignore explícito mantém as execuções rápidas e evita alterações não intencionais.
Liste o Plugin Tailwind por Último: prettier-plugin-tailwindcss deve estar no final do array plugins do Prettier ou ele entrará em conflito com outros plugins do Prettier e a ordenação de classes falhará.
Fixe endOfLine para lf: Defina "endOfLine": "lf" em .prettierrc e configure git config --global core.autocrlf input para que contribuidores do Windows não enviem arquivos CRLF que falhem no prettier --check no CI do Linux.
Commite Configurações de Equipe do .vscode: Faça commit de .vscode/settings.json e .vscode/extensions.json (não launch.json ou *.code-workspace) para que cada desenvolvedor herde o mesmo comportamento de formatar ao salvar, ESLint e extensões recomendadas.
Defina defaultFormatter por Idioma: Declare editor.defaultFormatter tanto globalmente quanto por idioma ([typescript], [typescriptreact], [json]) para evitar que o VS Code escolha um formatador aleatório quando vários estão instalados.
Use o TypeScript do Workspace: Aponte typescript.tsdk para node_modules/typescript/lib para que a verificação de tipos do editor corresponda à versão que tsc usa em CI, eliminando a derivação de tipos "funciona na minha máquina".
Habilite Strict Mais Flags Extras: Ative "strict": true para as oito verificações agrupadas e adicione noUncheckedIndexedAccess, noImplicitReturns, noFallthroughCasesInSwitch e verbatimModuleSyntax, pois elas não estão incluídas em strict.
Adote Strict Incrementalmente: Em uma base de código legada, mantenha "strict": false e habilite strictNullChecks primeiro, depois noImplicitAny, usando // @ts-expect-error (não @ts-ignore) para que as supressões falhem automaticamente assim que o problema subjacente for corrigido.
Execute tsc --noEmit em CI: O TypeScript captura quebras de tipo entre arquivos que o ESLint não pode (por exemplo, remover um membro de união de um tipo compartilhado); adicione "type-check": "tsc --noEmit" e confie em incremental: true mais um .tsbuildinfo em cache para velocidade.
Instale Husky via prepare: Coloque "prepare": "husky" em package.json para que os hooks de pré-commit sejam instalados automaticamente após npm install, e mantenha os hooks rápidos executando apenas lint-staged (com eslint --fix --no-warn-ignored) - nunca tsc completo.
Faça da CI o Rede de Segurança: Execute lint, prettier --check e tsc --noEmit no GitHub Actions usando npm ci para instalações determinísticas, uma versão do Node fixada correspondente, um grupo concurrency com cancel-in-progress: true e regras de proteção de branch que exigem que o job passe antes do merge.

Use a Configuração Plana do ESLint 9: Adote eslint.config.mjs e exclua todos os arquivos .eslintrc.* restantes, pois o ESLint volta para o formato legado se ambos existirem e sua configuração plana for ignorada silenciosamente.
Conecte Presets com FlatCompat: Presets do Next.js ainda enviam configurações no estilo legado extends, então envolva-os com FlatCompat({ baseDirectory: __dirname }) e recrie __dirname via fileURLToPath(import.meta.url) em ESM.
Isole Ignora Globais: Na configuração plana, { ignores: [...] } só funciona como um ignore global quando é a única chave em seu objeto; misturá-lo com rules o transforma em um filtro por arquivo.
Comece com next/core-web-vitals: Ele agrupa eslint-plugin-react, react-hooks, next, import e jsx-a11y, então raramente você precisa instalar esses plugins separadamente e pode adicionar apenas o que está faltando.
Escolha a Severidade Intencionalmente: Use "error" para regras que você deseja impor (falhar CI, bloquear builds) e reserve "warn" para regras para as quais você está migrando, pois avisos passam na CI e se acumulam silenciosamente.
Prefira o no-unused-vars do TypeScript: Desative o no-unused-vars base e habilite @typescript-eslint/no-unused-vars com argsIgnorePattern: "^_" para que a sintaxe de interface/type-alias/enum seja entendida e os conflitos desapareçam.
Force consistent-type-imports: Exija import type { … } para imports apenas de tipos para que os bundlers possam apagar completamente os tipos e seu grafo de tipos permaneça claramente separado do seu grafo de valores.
Nunca Desative exhaustive-deps Globalmente: Mantenha react-hooks/exhaustive-deps ativado (geralmente como "warn") e suprima-o por linha com // eslint-disable-next-line apenas para referências comprovadamente estáveis como dispatch ou refs.
Ordene Imports com Separadores de Grupo: Configure import/order com categorias agrupadas (builtin, external, internal, parent/sibling, index, type), "newlines-between": "always" e alphabetização; execute eslint --fix uma vez e adicione quaisquer linhas em branco ausentes manualmente.
Não Re-registre Plugins Agrupados: Instalar um plugin que next/core-web-vitals já inclui (react, react-hooks, next, import, jsx-a11y) causa registro duplicado e comportamento inesperado de regras, então verifique o preset primeiro.
Escopo de Plugins Apenas para Testes com files: Proteja eslint-plugin-testing-library com files: ["**/*.test.{ts,tsx}", "**/*.spec.{ts,tsx}"]; aplicado globalmente, ele produz falsos positivos em código não relacionado a testes.
Profile Regras Lentas: Execute TIMING=1 npx eslint . quando os tempos de lint aumentarem - cinco ou mais plugins ativos podem diminuir significativamente o linting, e as regras @typescript-eslint que entendem tipos são 2-5x mais lentas porque exigem informações de tipo completas.
Coloque eslint-config-prettier por Último: A entrada "prettier" deve ser o último item em seu array extends, pois ela apenas desativa regras de formatação e qualquer configuração listada depois dela reativará conflitos.
Não Use eslint-plugin-prettier: Executar o Prettier dentro do ESLint é lento e inunda o editor com sublinhados vermelhos para diferenças puras de formatação - execute ESLint e Prettier como comandos separados em vez disso.
Sempre Envie um .prettierignore: Sem ele, o Prettier percorre .next/, node_modules/, arquivos de lock e código gerado; um arquivo de ignore explícito mantém as execuções rápidas e evita alterações não intencionais.
Liste o Plugin Tailwind por Último: prettier-plugin-tailwindcss deve estar no final do array plugins do Prettier ou ele entrará em conflito com outros plugins do Prettier e a ordenação de classes falhará.
Fixe endOfLine para lf: Defina "endOfLine": "lf" em .prettierrc e configure git config --global core.autocrlf input para que contribuidores do Windows não enviem arquivos CRLF que falhem no prettier --check no CI do Linux.
Commite Configurações de Equipe do .vscode: Faça commit de .vscode/settings.json e .vscode/extensions.json (não launch.json ou *.code-workspace) para que cada desenvolvedor herde o mesmo comportamento de formatar ao salvar, ESLint e extensões recomendadas.
Defina defaultFormatter por Idioma: Declare editor.defaultFormatter tanto globalmente quanto por idioma ([typescript], [typescriptreact], [json]) para evitar que o VS Code escolha um formatador aleatório quando vários estão instalados.
Use o TypeScript do Workspace: Aponte typescript.tsdk para node_modules/typescript/lib para que a verificação de tipos do editor corresponda à versão que tsc usa em CI, eliminando a derivação de tipos "funciona na minha máquina".
Habilite Strict Mais Flags Extras: Ative "strict": true para as oito verificações agrupadas e adicione noUncheckedIndexedAccess, noImplicitReturns, noFallthroughCasesInSwitch e verbatimModuleSyntax, pois elas não estão incluídas em strict.
Adote Strict Incrementalmente: Em uma base de código legada, mantenha "strict": false e habilite strictNullChecks primeiro, depois noImplicitAny, usando // @ts-expect-error (não @ts-ignore) para que as supressões falhem automaticamente assim que o problema subjacente for corrigido.
Execute tsc --noEmit em CI: O TypeScript captura quebras de tipo entre arquivos que o ESLint não pode (por exemplo, remover um membro de união de um tipo compartilhado); adicione "type-check": "tsc --noEmit" e confie em incremental: true mais um .tsbuildinfo em cache para velocidade.
Instale Husky via prepare: Coloque "prepare": "husky" em package.json para que os hooks de pré-commit sejam instalados automaticamente após npm install, e mantenha os hooks rápidos executando apenas lint-staged (com eslint --fix --no-warn-ignored) - nunca tsc completo.
Faça da CI o Rede de Segurança: Execute lint, prettier --check e tsc --noEmit no GitHub Actions usando npm ci para instalações determinísticas, uma versão do Node fixada correspondente, um grupo concurrency com cancel-in-progress: true e regras de proteção de branch que exigem que o job passe antes do merge.

Melhores Práticas de Linting e Formatação

Buscar na documentação

Melhores Práticas de Linting e Formatação