Плагин eslint-plugin-node

ESLint-плагин для Node.js-окружения предназначен для статического анализа JavaScript-кода с учётом особенностей выполнения в среде Node. Он дополняет базовые правила ESLint набором проверок, ориентированных на модули CommonJS и ES Modules, встроенные API Node, управление зависимостями, совместимость версий и корректность использования файловой системы и стандартных библиотек.

Основная цель подобных правил — выявление ошибок, которые не могут быть обнаружены стандартным линтером JavaScript, но приводят к падениям приложения, утечкам зависимостей, несовместимости с версией Node или некорректной сборке пакета.

Плагин эволюционировал: первоначально широко использовался пакет eslint-plugin-node, позднее функциональность была перенесена и продолжена в виде eslint-plugin-n, однако в учебной и исторической практике оба названия часто встречаются как обозначение одного класса правил.

Установка и базовая интеграция

Подключение осуществляется через npm или yarn:

npm install eslint-plugin-node --save-dev

или (в современных конфигурациях):

npm install eslint-plugin-n --save-dev

Подключение в конфигурации ESLint:

{
  "plugins": ["node"]
}

или для нового варианта:

{
  "plugins": ["n"]
}

Расширенная конфигурация через extends:

{
  "extends": ["plugin:node/recommended"]
}

или:

{
  "extends": ["plugin:n/recommended"]
}

Рекомендуемый пресет включает базовые правила, направленные на выявление наиболее частых проблем в Node.js-проектах.

Архитектура правил плагина

Набор правил условно делится на несколько категорий:

  • проверка встроенных API Node;
  • контроль модульной системы;
  • проверка зависимостей пакета;
  • контроль совместимости версий Node;
  • рекомендации по стилю использования Node-специфичных функций.

Каждая категория ориентирована на снижение вероятности ошибок, которые проявляются только в рантайме.

Проверка встроенных API Node.js

Одной из ключевых задач является контроль использования встроенных модулей и глобальных объектов.

Запрещённые устаревшие API

Правило:

  • node/no-deprecated-api

Выявляет использование функций Node.js, помеченных как устаревшие. Это критично для долгоживущих приложений, где обновление версии Node может привести к неожиданным падениям.

Пример:

const domain = require("domain");

domain.create();

Такой код может быть отмечен как небезопасный из-за устаревшего API domain.

Проверка глобальных объектов

Правила:

  • node/prefer-global/buffer
  • node/prefer-global/process
  • node/prefer-global/console

Эти правила обеспечивают консистентность использования глобальных объектов.

Пример нарушения:

const Buffer = require("buffer").Buffer;

const buf = new Buffer("data");

Предпочтительный вариант:

const buf = Buffer.from("data");

Контроль модульной системы

Node.js поддерживает два основных подхода: CommonJS (require) и ES Modules (import). Плагин обеспечивает анализ корректности использования обоих механизмов.

Отсутствующие модули

Правила:

  • node/no-missing-require
  • node/no-missing-import

Эти проверки выявляют ситуации, когда модуль указан, но физически отсутствует в node_modules или указан неверный путь.

Пример:

const utils = require("./utilss");

Если файла utilss.js не существует, линтер фиксирует ошибку до выполнения кода.

Лишние зависимости

Правила:

  • node/no-extraneous-require
  • node/no-extraneous-import

Контролируют соответствие импортируемых пакетов списку зависимостей в package.json.

Пример:

const lodash = require("lodash");

Если lodash не указан в dependencies, будет выдано предупреждение.

Непубличные модули

Правила:

  • node/no-unpublished-require
  • node/no-unpublished-import

Проверяют использование файлов или пакетов, которые не предназначены для публикации (например, находятся в тестовых директориях).

Совместимость с версиями Node.js

Одной из наиболее мощных возможностей является контроль использования функций, недоступных в текущей версии Node.

Проверка поддержки синтаксиса

Правило:

  • node/no-unsupported-features/es-syntax

Оно анализирует использование современных конструкций JavaScript (optional chaining, nullish coalescing и другие) в контексте заданной версии Node.

Пример:

const value = obj?.data?.name;

Если целевая версия Node ниже требуемой, линтер выдаёт ошибку.

Проверка API

Правило:

  • node/no-unsupported-features/node-builtins

Контролирует использование новых встроенных API Node.

Пример:

const { readFile } = require("fs/promises");

Если версия Node не поддерживает fs/promises, код считается несовместимым.

Работа с файловой системой и пакетами

Shebang в исполняемых файлах

Правило:

  • node/shebang

Контролирует корректность использования shebang-строки:

#!/usr/bin/env node

console.log("CLI tool");

Ошибки возникают при некорректной позиции или отсутствии строки в CLI-скриптах.

Контроль бинарных файлов пакета

Правило:

  • node/no-unpublished-bin

Проверяет, что бинарные файлы, указанные в package.json, действительно существуют и не исключены из публикации.

Управление процессом и завершением выполнения

Некоторые правила касаются поведения процесса Node.js.

Использование process.exit

В ряде конфигураций может активироваться правило:

  • node/no-process-exit

Оно ограничивает использование:

process.exit(1);

Причина — неконтролируемое завершение процесса может нарушать работу серверов и асинхронных задач.

Рекомендации по использованию промисов

DNS и файловая система

Правила:

  • node/prefer-promises/dns
  • node/prefer-promises/fs

Они стимулируют использование промис-версий API вместо callback-ориентированных функций.

Пример:

const fs = require("fs");

fs.readFile("file.txt", (err, data) => {
  if (err) throw err;
});

Рекомендуемая форма:

const fs = require("fs/promises");

const data = await fs.readFile("file.txt");

Настройка версии Node в конфигурации

Для корректной работы многих правил требуется указание целевой версии среды.

Пример конфигурации:

{
  "settings": {
    "node": {
      "version": ">=18.0.0"
    }
  }
}

Также может использоваться автоматическое определение через .nvmrc или engines в package.json.

Интеграция с ESLint-конфигурациями

Типовой пример .eslintrc:

{
  "env": {
    "node": true
  },
  "plugins": ["node"],
  "extends": ["plugin:node/recommended"],
  "rules": {
    "node/no-missing-require": "error",
    "node/no-extraneous-require": "warn",
    "node/no-deprecated-api": "error"
  }
}

В более строгих конфигурациях уровень проверки повышается до error для всех правил, связанных с совместимостью и зависимостями.

Типовые сценарии использования

Серверные приложения

В Express- и Fastify-проектах плагин используется для предотвращения ошибок импорта модулей и контроля версии Node, особенно при деплое в контейнеры.

CLI-инструменты

Для CLI-приложений критично правило shebang, а также контроль бинарных файлов и корректной публикации пакета.

Библиотеки

При разработке npm-пакетов важны правила:

  • no-unpublished-*
  • no-extraneous-*

Они предотвращают попадание в продакшен зависимостей, используемых только в разработке.

Конфигурационные пресеты и уровни строгости

Рекомендуемый пресет:

  • plugin:node/recommended

Строгий режим может включать:

  • запрет устаревших API;
  • полный контроль зависимостей;
  • строгую проверку совместимости Node;
  • ограничение синхронных API.

Лёгкий режим обычно оставляет только критические ошибки:

  • отсутствующие модули;
  • несовместимый синтаксис;
  • базовые проверки API.

Эволюция и современное состояние

Переход от eslint-plugin-node к eslint-plugin-n связан с расширением поддержки современных версий Node.js и упрощением архитектуры правил. При этом концептуальная модель осталась прежней: анализ окружения Node как специфической платформы с отдельными ограничениями по сравнению с браузером.

Современные конфигурации ESLint всё чаще используют комбинированные наборы правил, где Node-плагин работает совместно с TypeScript-линтерами и правилами безопасности зависимостей.

Взаимодействие с другими плагинами ESLint

Часто используется совместно с:

  • eslint-plugin-import — контроль импортов и модульной структуры;
  • eslint-plugin-security — проверка уязвимостей;
  • @typescript-eslint/eslint-plugin — анализ TypeScript-кода;
  • eslint-plugin-promise — контроль асинхронной логики.

В такой связке Node-плагин отвечает за платформенную корректность, тогда как остальные инструменты покрывают архитектуру и безопасность.

Ограничения анализа

Статический анализ имеет ограничения:

  • невозможность определить динамические require с вычисляемыми путями;
  • сложность анализа монорепозиториев без корректной настройки settings;
  • частичная поддержка нестандартных загрузчиков модулей.

Несмотря на это, плагин существенно снижает количество runtime-ошибок, связанных с окружением Node.js.

Оглавление