ESLint GitHub Actions Formatter

2.0.1 verified Sat Apr 25 auth: no javascript

ESLint formatter (v2.0.1) that generates GitHub Actions annotations for linting errors and warnings, enabling inline code annotations in pull request diffs and checks. When run outside a GitHub Actions environment, it falls back to ESLint's built-in stylish formatter. Optionally outputs JSON for SonarCloud integration. Includes TypeScript type definitions. Compatible with ESLint 8 and 9 (flat config).

Common errors

error Error: Cannot find module 'eslint-formatter-gha' ↓

cause Package not installed or not in node_modules.

fix

Run npm install --save-dev eslint-formatter-gha.

error Error: Invalid formatter 'eslint-formatter-gha' ↓

cause Using full package name instead of 'gha' in CLI.

fix

Use -f gha instead of -f eslint-formatter-gha.

error Error [ERR_REQUIRE_ESM]: require() of ES Module not supported ↓

cause Using require() in an ESM-only context (Node.js 12+).

fix

Use dynamic import: const ghaFormatter = await import('eslint-formatter-gha') or switch to ESM imports.

Warnings

gotcha Formatter name must be 'gha', not the full package name. ↓

fix Use `-f gha` in CLI or set formatter to 'eslint-formatter-gha' in config.

gotcha The formatter relies on the GITHUB_ACTIONS environment variable. If not set, it silently falls back to stylish formatter, which may cause unexpected output in CI. ↓

fix Ensure GITHUB_ACTIONS=true is set in your GitHub Actions workflow; for other CI, consider a different formatter.

gotcha When SONARSCANNER=true, output is JSON written to GITHUB_WORKSPACE/eslint-report.json. This may overwrite existing files. ↓

fix Set SONARSCANNER only when intended; handle file writes carefully.

Install

npm install eslint-formatter-gha

yarn add eslint-formatter-gha

pnpm add eslint-formatter-gha

Imports

default
wrong
```
const ghaFormatter = require('eslint-formatter-gha')
```
correct
```
import ghaFormatter from 'eslint-formatter-gha'
```
ESM default export. The package provides a single function used as an ESLint formatter.
eslint formatter usage via CLI
wrong
```
eslint . -f eslint-formatter-gha
```
correct
```
eslint . -f gha
```
Use the short formatter name 'gha', not the package name.

module.exports (CJS fallback)

wrong

const { ghaFormatter } = require('eslint-formatter-gha')

correct

const ghaFormatter = require('eslint-formatter-gha')

CommonJS require returns the default export, not a named export.

Quickstart

Shows CLI usage and programmatic usage with ESM import, linting a directory and formatting results.

// Run ESLint with GitHub Actions formatter:
// eslint . -f gha

// Programmatic usage (ESM):
import ghaFormatter from 'eslint-formatter-gha';
import { ESLint } from 'eslint';

const eslint = new ESLint();
const results = await eslint.lintFiles(['./src']);
const formatter = await ghaFormatter(results);
console.log(formatter);