ESLint Flat Config no Node.js

O ESLint Flat Config no Node.js é o formato moderno de configuração do ESLint. Em vez de arquivos .eslintrc espalhados e herança implícita, o projeto usa um arquivo eslint.config.js, .mjs ou .cjs que exporta uma sequência explícita de objetos de configuração.

O modelo flat facilita entender quais regras se aplicam a cada arquivo, importar plugins como módulos JavaScript, configurar ESM e CommonJS no mesmo projeto, separar regras de testes e inspecionar a configuração final. Porém, a ordem dos objetos importa e padrões de files e ignores mal definidos podem aplicar regras em locais inesperados.

Neste guia, você aprenderá a instalar ESLint, criar uma configuração flat para Node.js, configurar arquivos JavaScript e TypeScript, usar plugins, ignores globais, regras por diretório, testes, scripts e integração contínua.

O que é Flat Config?

Flat Config é o sistema atual de configuração do ESLint. A documentação oficial de arquivos de configuração do ESLint indica que o arquivo exporta um array de objetos. Cada objeto pode definir:

• name;
• files e ignores;
• languageOptions;
• plugins;
• rules;
• settings;
• linterOptions;
• extends;
• processor.

Quando vários objetos correspondem ao mesmo arquivo, eles são combinados na ordem declarada. Objetos posteriores sobrescrevem valores conflitantes.

Instalação

npm install --save-dev eslint @eslint/js

Inicialize uma configuração:

npx eslint --init

Para um projeto manual, crie eslint.config.js.

Configuração mínima

import js from '@eslint/js';
import { defineConfig } from 'eslint/config';

export default defineConfig([
  {
    name: 'app/javascript',
    files: ['**/*.js', '**/*.mjs', '**/*.cjs'],
    extends: [js.configs.recommended]
  }
]);

O campo name facilita mensagens de erro e uso do inspetor de configuração.

ESM e CommonJS

O ESLint reconhece por padrão .mjs como ESM e .cjs como CommonJS. Para arquivos .js, o comportamento também depende do projeto. Você pode declarar explicitamente:

export default defineConfig([
  {
    name: 'app/esm',
    files: ['src/**/*.js', 'src/**/*.mjs'],
    languageOptions: {
      ecmaVersion: 'latest',
      sourceType: 'module'
    }
  },
  {
    name: 'app/commonjs',
    files: ['scripts/**/*.cjs'],
    languageOptions: {
      sourceType: 'commonjs'
    }
  }
]);

Para uma arquitetura ESM completa, consulte ES Modules no Node.js.

Globais do Node.js

Instale o pacote globals:

npm install --save-dev globals

import globals from 'globals';
import { defineConfig } from 'eslint/config';

export default defineConfig([
  {
    files: ['src/**/*.js'],
    languageOptions: {
      globals: globals.node
    }
  }
]);

Isso declara objetos como process, Buffer e setImmediate sem desativar no-undef.

Regras recomendadas

import js from '@eslint/js';

export default defineConfig([
  {
    files: ['**/*.js'],
    plugins: { js },
    extends: ['js/recommended'],
    rules: {
      'no-unused-vars': ['error', {
        argsIgnorePattern: '^_',
        caughtErrorsIgnorePattern: '^_'
      }],
      'prefer-const': 'error',
      'no-constant-binary-expression': 'error'
    }
  }
]);

Também é possível inserir js.configs.recommended diretamente. Use a forma compatível com a versão instalada.

Ignores globais

import { defineConfig, globalIgnores } from 'eslint/config';

export default defineConfig([
  globalIgnores([
    'dist/',
    'coverage/',
    '.cache/',
    'generated/'
  ])
]);

Um objeto contendo somente ignores atua globalmente. O helper globalIgnores() deixa a intenção explícita.

Ignorar arquivos dentro de uma configuração

{
  files: ['src/**/*.js'],
  ignores: ['src/generated/**'],
  rules: {
    'no-console': 'error'
  }
}

Nesse caso, o ignore vale apenas para esse objeto. Prefira sempre combinar files e ignores quando a exclusão é local.

Configuração para testes

export default defineConfig([
  {
    name: 'app/source',
    files: ['src/**/*.js'],
    rules: {
      'no-console': 'error'
    }
  },
  {
    name: 'app/tests',
    files: ['test/**/*.test.js', 'test/**/*.spec.js'],
    languageOptions: {
      globals: {
        describe: 'readonly',
        it: 'readonly',
        beforeEach: 'readonly'
      }
    },
    rules: {
      'no-console': 'off'
    }
  }
]);

Se o projeto usa o test runner nativo, muitos globais não são necessários quando as funções são importadas de node:test. Consulte Node Test Runner.

TypeScript

Para TypeScript, use o pacote recomendado pelo projeto typescript-eslint:

npm install --save-dev typescript typescript-eslint

import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';
import { defineConfig } from 'eslint/config';

export default defineConfig([
  eslint.configs.recommended,
  ...tseslint.configs.recommended,
  {
    files: ['src/**/*.ts'],
    rules: {
      '@typescript-eslint/no-unused-vars': ['error', {
        argsIgnorePattern: '^_'
      }]
    }
  }
]);

A API exata dos presets pode mudar entre versões. Use a documentação do typescript-eslint compatível com seu lockfile.

Regras com informação de tipos

Algumas regras precisam do programa TypeScript:

export default tseslint.config(
  ...tseslint.configs.recommendedTypeChecked,
  {
    languageOptions: {
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname
      }
    }
  }
);

Regras tipadas encontram promises não aguardadas, condições incorretas e usos inseguros, mas tornam o lint mais lento. Meça antes de habilitar em monorepos grandes.

Arquivos de configuração

Scripts e arquivos de configuração podem precisar de regras diferentes:

{
  name: 'app/config-files',
  files: ['*.config.js', 'scripts/**/*.js'],
  rules: {
    'no-console': 'off'
  }
}

Plugins

import security from 'eslint-plugin-security';

export default defineConfig([
  {
    files: ['src/**/*.js'],
    plugins: {
      security
    },
    rules: {
      ...security.configs.recommended.rules
    }
  }
]);

Revise cada preset. Plugins de segurança podem gerar falsos positivos e não substituem análise de dependências ou revisão.

Importações

Plugins de importação ajudam a detectar módulos ausentes e ciclos. Em ESM, configure resolvers compatíveis com TypeScript e exports do pacote. Evite duplicar verificações já feitas pelo compilador sem necessidade.

linterOptions

{
  linterOptions: {
    reportUnusedDisableDirectives: 'error',
    reportUnusedInlineConfigs: 'error'
  }
}

Isso impede comentários eslint-disable esquecidos após o código mudar.

Bloquear configuração inline

{
  linterOptions: {
    noInlineConfig: true
  }
}

Use apenas quando a organização quer proibir exceções locais. Em muitos projetos, comentários acompanhados de justificativa são úteis.

Config Inspector

Quando uma regra parece inesperada:

npx eslint --inspect-config src/server.js

O inspetor mostra quais objetos se aplicam ao arquivo. Também use:

npx eslint --print-config src/server.js

A disponibilidade dos comandos depende da versão.

Script package.json

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint . --fix"
  }
}

Não execute --fix no CI. O pipeline deve falhar e solicitar que o desenvolvedor confirme mudanças.

Cache do ESLint

eslint . --cache --cache-location .cache/eslint

O cache acelera execução local. No CI, avalie se restaurar o arquivo compensa e inclua versão do ESLint e lockfile na chave.

Integração com GitHub Actions

- name: Lint
  run: npm run lint

O artigo CI para Node.js com GitHub Actions mostra uma pipeline completa com npm ci, cache, testes e build.

Prettier e ESLint

ESLint deve focar problemas de código e regras de qualidade. Prettier deve cuidar da formatação. Evite dezenas de regras estilísticas conflitantes. O próximo artigo apresenta a integração.

Migração de .eslintrc

Durante a migração:

1. registre a saída atual;
2. crie eslint.config.js;
3. importe presets equivalentes;
4. converta env em languageOptions.globals;
5. converta overrides em objetos separados;
6. revise ignores;
7. compare erros arquivo por arquivo;
8. remova a configuração antiga.

Use o guia oficial de migração da versão instalada.

Monorepos

Flat Config pode usar basePath ou objetos por pacote:

{
  name: 'packages/api',
  basePath: 'packages/api',
  files: ['src/**/*.ts'],
  rules: {
    'no-console': 'error'
  }
}

Mantenha uma base compartilhada e exceções pequenas. Configurações duplicadas ficam difíceis de atualizar.

Regras importantes para Node.js

• no-undef;
• no-unused-vars;
• no-unreachable;
• no-constant-condition;
• no-promise-executor-return;
• require-atomic-updates, avaliada com contexto;
• regras tipadas para promises;
• regras de imports quando configuradas corretamente.

Não transforme lint em burocracia

Uma regra deve prevenir bug, padronizar decisão relevante ou melhorar manutenção. Se gera centenas de exceções sem benefício, ajuste ou remova. Warnings ignorados perdem valor; prefira resolver ou transformar em erro.

Desempenho

Para investigar lentidão:

npx eslint . --debug

Regras tipadas, plugins de importação e padrões amplos são fontes comuns. Exclua dist, cobertura, arquivos gerados e snapshots.

Erros comuns

• Ordem errada: objeto posterior sobrescreve regra.
• Ignore local tratado como global: arquivo continua lintado.
• Sem files: preset se aplica além do esperado.
• TypeScript sem parser: sintaxe falha.
• Preset incompatível: plugin não suporta flat config.
• Regras de estilo duplicadas: conflito com Prettier.
• Desabilitações esquecidas: exceções permanecem.
• Lint sem CI: padrão não é aplicado.

Configuração completa

import js from '@eslint/js';
import globals from 'globals';
import { defineConfig, globalIgnores } from 'eslint/config';

export default defineConfig([
  globalIgnores(['dist/', 'coverage/', '.cache/']),
  {
    name: 'app/javascript',
    files: ['src/**/*.js'],
    extends: [js.configs.recommended],
    languageOptions: {
      ecmaVersion: 'latest',
      sourceType: 'module',
      globals: globals.node
    },
    linterOptions: {
      reportUnusedDisableDirectives: 'error'
    },
    rules: {
      'no-console': 'error',
      'no-unused-vars': ['error', {
        argsIgnorePattern: '^_'
      }],
      'prefer-const': 'error'
    }
  },
  {
    name: 'app/tests',
    files: ['test/**/*.test.js'],
    rules: {
      'no-console': 'off'
    }
  }
]);

Conclusão

O ESLint Flat Config no Node.js torna a configuração explícita e programável. Objetos com nomes, padrões e ordem clara facilitam separar código-fonte, testes, scripts, ESM, CommonJS e TypeScript.

Comece com regras recomendadas, ignores globais e poucos overrides. Use o inspetor quando houver dúvida, reporte comentários de desativação não utilizados e execute o lint no CI. Assim, ESLint encontra problemas reais sem transformar o projeto em uma coleção de regras difíceis de compreender.