Руководство по интеграции с API Node.js

В этом руководстве показано, как использовать класс ESLint для проверки файлов и получения результатов. Это может пригодиться при создании интеграций с другими проектами.

Зачем создавать интеграцию?

Интеграция с ESLint может понадобиться при разработке инструментов для разработчиков, например:

• Редакторы кода и IDE: интеграция ESLint с редакторами кода и IDE позволяет получать обратную связь о качестве кода в реальном времени и автоматически подсвечивать возможные проблемы по мере ввода. Во многих редакторах уже есть плагины ESLint, но может потребоваться создать собственную интеграцию, если существующие плагины не отвечают вашим требованиям.

• Пользовательские инструменты для проверки кода: если вы создаёте собственный инструмент, который объединяет несколько средств проверки или добавляет определённые функции, можно интегрировать ESLint, чтобы обеспечить проверку JavaScript.

• Инструменты для проверки кода: интеграция ESLint с инструментами для проверки кода помогает автоматизировать поиск возможных проблем в кодовой базе.

• Образовательные платформы: если вы разрабатываете образовательную платформу или учебное пособие по программированию, интеграция ESLint позволит предоставлять пользователям обратную связь в реальном времени во время изучения JavaScript, помогая им совершенствовать навыки программирования и осваивать лучшие практики.

• Интеграция с инструментами разработчика: если вы создаёте или расширяете инструмент для разработчиков, например сборщик или среду тестирования, можно интегрировать ESLint для проверки кода. ESLint можно встроить непосредственно в инструмент или подключить в качестве плагина.

Что вы создадите

В этом руководстве вы создадите простой проект Node.js, который использует класс ESLint для проверки файлов и получения результатов.

Требования

Предполагается, что вы знакомы с JavaScript и Node.js.

Для выполнения этого руководства вам понадобятся:

• Node.js (^20.19.0, ^22.13.0 или >=24)
• npm
• Текстовый редактор

Шаг 1. Настройка

Сначала создайте каталог для нового проекта:

mkdir eslint-integration
cd eslint-integration

Инициализируйте проект с помощью файла package.json:

npm init -y

yarn init -y

pnpm init -y

bun init -y

Установите пакет eslint как зависимость (не как dev-зависимость):

npm install eslint

yarn add eslint

pnpm add eslint

bun add eslint

Создайте в корневом каталоге проекта файл example-eslint-integration.js:

touch example-eslint-integration.js

Шаг 2. Импорт и настройка экземпляра ESLint

Импортируйте класс ESLint из пакета eslint и создайте его экземпляр.

Настроить ESLint можно, передав объект параметров конструктору ESLint:

// example-eslint-integration.js

const { ESLint } = require("eslint");

// Create an instance of ESLint with the configuration passed to the function
function createESLintInstance(overrideConfig) {
	return new ESLint({
		overrideConfigFile: true,
		overrideConfig,
		fix: true,
	});
}

Шаг 3. Проверка и исправление файлов

Для проверки файла используйте метод lintFiles экземпляра ESLint. Аргумент filePaths, передаваемый в ESLint#lintFiles(), может быть строкой или массивом строк с путём (путями) к файлу, который нужно проверить. Пути к файлам могут быть шаблонами glob или именами файлов.

Статический метод ESLint.outputFixes() принимает результаты проверки, полученные при вызове ESLint#lintFiles(), а затем записывает исправленный код обратно в исходные файлы.

// example-eslint-integration.js

// ... previous step's code to instantiate the ESLint instance

// Lint the specified files and return the results
async function lintAndFix(eslint, filePaths) {
	const results = await eslint.lintFiles(filePaths);

	// Apply automatic fixes and output fixed code
	await ESLint.outputFixes(results);

	return results;
}

Шаг 4. Вывод результатов

Создайте функцию для вывода результатов проверки в консоль. Она должна соответствовать потребностям вашей интеграции. Например, результаты проверки можно отображать в пользовательском интерфейсе.

В этом примере мы просто выведем результаты в консоль:

// example-eslint-integration.js

// ... previous step's code to instantiate the ESLint instance
// and get linting results.

// Log results to console if there are any problems
function outputLintingResults(results) {
	// Identify the number of problems found
	const problems = results.reduce(
		(acc, result) => acc + result.errorCount + result.warningCount,
		0,
	);

	if (problems > 0) {
		console.log("Linting errors found!");
		console.log(results);
	} else {
		console.log("No linting errors found.");
	}
	return results;
}

Шаг 5. Объединение всех частей

Объедините приведённые выше функции в новую функцию под названием lintFiles. Эта функция станет главной точкой входа вашей интеграции:

// example-eslint-integration.js

// Put previous functions all together
async function lintFiles(filePaths) {
	// The ESLint configuration. Alternatively, you could load the configuration
	// from a .eslintrc file or just use the default config.
	const overrideConfig = {
		languageOptions: {
			ecmaVersion: 2018,
			sourceType: "commonjs",
		},
		rules: {
			"no-console": "error",
			"no-unused-vars": "warn",
		},
	};

	const eslint = createESLintInstance(overrideConfig);
	const results = await lintAndFix(eslint, filePaths);
	return outputLintingResults(results);
}

// Export integration
module.exports = { lintFiles };

Ниже приведён полный пример кода для example-eslint-integration.js:

const { ESLint } = require("eslint");

// Create an instance of ESLint with the configuration passed to the function
function createESLintInstance(overrideConfig) {
	return new ESLint({
		overrideConfigFile: true,
		overrideConfig,
		fix: true,
	});
}

// Lint the specified files and return the results
async function lintAndFix(eslint, filePaths) {
	const results = await eslint.lintFiles(filePaths);

	// Apply automatic fixes and output fixed code
	await ESLint.outputFixes(results);

	return results;
}

// Log results to console if there are any problems
function outputLintingResults(results) {
	// Identify the number of problems found
	const problems = results.reduce(
		(acc, result) => acc + result.errorCount + result.warningCount,
		0,
	);

	if (problems > 0) {
		console.log("Linting errors found!");
		console.log(results);
	} else {
		console.log("No linting errors found.");
	}
	return results;
}

// Put previous functions all together
async function lintFiles(filePaths) {
	// The ESLint configuration. Alternatively, you could load the configuration
	// from an eslint.config.js file or just use the default config.
	const overrideConfig = {
		languageOptions: {
			ecmaVersion: 2018,
			sourceType: "commonjs",
		},
		rules: {
			"no-console": "error",
			"no-unused-vars": "warn",
		},
	};

	const eslint = createESLintInstance(overrideConfig);
	const results = await lintAndFix(eslint, filePaths);
	return outputLintingResults(results);
}

// Export integration
module.exports = { lintFiles };

Заключение

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

Просмотр кода руководства

Вы можете ознакомиться с исходным кодом руководства с комментариями.