ESLint para Scripts Node.js

Configure o ESLint flat config (eslint.config.js) para projetos de scripts Node.js com suporte a TypeScript, regras específicas do Node e linting ciente de tipos.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Inicialize uma nova configuração ESLint interativamente
npm init @eslint/config@latest
 
# Instale a toolchain principal para um projeto de script Node.js TypeScript
npm install --save-dev \
  eslint \
  typescript-eslint \
  eslint-plugin-n \
  globals
 
# Faça o lint dos seus scripts
npx eslint .
 
# Faça o lint e corrija automaticamente
npx eslint . --fix

Quando usar isso: Qualquer projeto Node.js autônomo - CLIs, scripts de build, automação ou pacotes de ferramentas de monorepo - que não faz parte de um aplicativo Next.js/React.

Exemplo Funcional

// eslint.config.js
import js from "@eslint/js";
import tseslint from "typescript-eslint";
import nodePlugin from "eslint-plugin-n";
import globals from "globals";
 
export default tseslint.config(
  // Ignores globais - deve ser a única chave em seu próprio objeto
  {
    ignores: ["dist/", "build/", "coverage/", "node_modules/"],
  },
 
  // Regras JS base
  js.configs.recommended,
 
  // Regras recomendadas do plugin Node.js (preset de flat config)
  nodePlugin.configs["flat/recommended-script"],
 
  // Regras com verificação de tipo TypeScript
  ...tseslint.configs.strictTypeChecked,
  ...tseslint.configs.stylisticTypeChecked,
 
  {
    files: ["**/*.ts", "**/*.mts"],
    languageOptions: {
      globals: globals.nodeBuiltin,
      parserOptions: {
        project: "./tsconfig.json",
        tsconfigRootDir: import.meta.dirname,
      },
    },
    rules: {
      // Força async/await em vez de chains de promise brutas
      "promise/prefer-await-to-then": "off",
      "@typescript-eslint/no-floating-promises": "error",
      "@typescript-eslint/no-misused-promises": "error",
      "@typescript-eslint/return-await": ["error", "always"],
 
      // Regras do plugin Node.js
      "n/no-missing-import": "off", // typescript-eslint resolve imports
      "n/no-unpublished-import": "off",
      "n/no-process-exit": "warn",
    },
  },
);

O que isso demonstra:

• Flat config com o helper tseslint.config() para autoria de config com segurança de tipo
• strictTypeChecked + stylisticTypeChecked para as regras TS mais rigorosas
• eslint-plugin-n (o fork mantido de eslint-plugin-node) fornecendo regras específicas do Node.js
• Linting ciente de tipos habilitado via parserOptions.project
• Ignores globais em um objeto dedicado (exigido pelo flat config)

Mergulho Profundo

Como Funciona

• ESLint 9+ carrega eslint.config.js (flat config) da raiz do projeto por padrão - sem mais arquivos .eslintrc em cascata.
• typescript-eslint é distribuído como um único pacote que reexporta @typescript-eslint/parser, @typescript-eslint/eslint-plugin e um helper config() que concatena e tipa objetos de configuração.
• eslint-plugin-n substitui o eslint-plugin-node abandonado. Ele adiciona regras específicas do Node como n/no-missing-import, n/no-unpublished-bin e n/no-deprecated-api.
• Regras cientes de tipos (qualquer coisa com sufixo TypeChecked) exigem que o parser carregue tsconfig.json via parserOptions.project. Sem isso, essas regras silenciosamente não fazem nada.
• tsconfigRootDir: import.meta.dirname garante que o caminho project seja resolvido em relação ao arquivo de configuração, não ao diretório de trabalho atual.

Variações

Configuração apenas JavaScript (sem TypeScript):

// eslint.config.js
import js from "@eslint/js";
import nodePlugin from "eslint-plugin-n";
import globals from "globals";
 
export default [
  js.configs.recommended,
  nodePlugin.configs["flat/recommended-script"],
  {
    languageOptions: {
      ecmaVersion: "latest",
      sourceType: "module",
      globals: globals.nodeBuiltin,
    },
  },
];

Linting ciente de tipos com um tsconfig dedicado:

{
  files: ["**/*.ts"],
  languageOptions: {
    parserOptions: {
      project: "./tsconfig.eslint.json",
      tsconfigRootDir: import.meta.dirname,
    },
  },
}

Integração com Prettier (desativa regras estilísticas que entram em conflito):

npm install --save-dev eslint-config-prettier

import prettier from "eslint-config-prettier";
 
export default tseslint.config(
  js.configs.recommended,
  ...tseslint.configs.recommended,
  prettier, // deve ser o ÚLTIMO - desabilita regras estilísticas conflitantes
);

Ignores com escopo para arquivos gerados:

{
  ignores: ["**/*.generated.ts", "src/proto/**"],
}

Notas sobre TypeScript

• @typescript-eslint/parser é instalado transitivamente através do meta-pacote typescript-eslint - você raramente precisa importá-lo diretamente.
• Regras cientes de tipos como no-floating-promises e no-misused-promises são essenciais para scripts Node.js onde rejeições não tratadas silenciosas podem corromper o estado.
• Habilite o preset mais rigoroso com ...tseslint.configs.strictTypeChecked - ele captura bugs reais como no-unnecessary-condition e no-unsafe-argument.
• O helper tseslint.config() fornece autocompletar e erros de tipo se você errar o nome de uma regra ou opção.

Armadilhas

Coisas que vão te morder. Cada armadilha inclui o que dá errado, por que acontece e a correção.

• Confusão entre Flat config e .eslintrc legado - ESLint 9+ usa flat config por padrão. Se você ainda tem um .eslintrc.json no projeto, o ESLint o ignora silenciosamente quando eslint.config.js existe. Correção: Exclua todos os arquivos legados ao migrar e verifique com npx eslint --print-config path/to/file.ts.

• parserOptions.project ausente desabilita regras cientes de tipos - Regras de strictTypeChecked ou stylisticTypeChecked exigem que o programa TypeScript seja carregado. Sem project, elas falham em tempo de execução ou passam silenciosamente. Correção: Sempre defina parserOptions.project e tsconfigRootDir no bloco de arquivos TS.

• eslint-plugin-n relata falsos positivos para aliases de caminho TS - Regras como n/no-missing-import não conseguem resolver aliases de caminho @/utils definidos em tsconfig.json. Correção: Desabilite n/no-missing-import (e n/no-unpublished-import) ao usar TypeScript - typescript-eslint já valida imports.

• Arquivo de configuração ESM em um projeto CommonJS - Se package.json tiver "type": "commonjs" (ou nenhum campo type), eslint.config.js com sintaxe import falha ao carregar. Correção: Renomeie para eslint.config.mjs OU adicione "type": "module" a package.json.

• Conflitos de regras Prettier/ESLint - Habilitar regras estilísticas do ESLint junto com o Prettier produz auto-correções conflitantes. Correção: Adicione eslint-config-prettier como o último item no array de configuração para desabilitar regras conflitantes.

• ignores misturado com outras chaves se torna silenciosamente um filtro de arquivo - Em flat config, um objeto com ignores e rules é tratado como um filtro, não como um ignore global. Correção: Coloque ignores globais em seu próprio objeto { ignores: [...] } sem outras chaves.

Alternativas

Outras maneiras de resolver o mesmo problema - e quando cada uma é a melhor escolha.

FAQs

Relacionados

• Padrões de Scripts Utilitários - I/O de arquivos, prompts, spinners e saída colorida
• Configuração ESLint para Next.js - flat config para aplicativos Next.js
• Plugins ESLint - adicione plugins React, a11y, import
• Fundamentos de TypeScript - fundamentos de tsconfig