@angular-eslint/builder

An Angular CLI builder that integrates ESLint with Angular projects, enabling developers to run ESLint through the standard ng lint command. This builder wraps ESLint's programmatic Node.js API to provide seamless integration with Angular CLI's build system, supporting both legacy .eslintrc configurations and modern flat config files.

Package Information

• Package Name: @angular-eslint/builder
• Package Type: npm
• Language: TypeScript
• Installation: npm install @angular-eslint/builder

Core Imports

This package does not export a programmatic API. It functions as an Angular CLI builder and is used declaratively through Angular project configuration.

Basic Usage

Configure in your angular.json file:

{
  "projects": {
    "my-app": {
      "architect": {
        "lint": {
          "builder": "@angular-eslint/builder:lint",
          "options": {
            "lintFilePatterns": ["src/**/*.ts", "src/**/*.html"]
          }
        }
      }
    }
  }
}

Run the linter:

ng lint
ng lint --fix
ng lint --format=json

Architecture

This Angular CLI builder is structured around several key components:

• Builder Implementation: Main builder function that executes ESLint programmatically
• Configuration Schema: JSON schema defining all supported options and their validation rules
• ESLint Utils: Utility functions for resolving and instantiating the correct ESLint class
• Config Detection: Automatic detection of legacy .eslintrc vs modern flat config files
• Workspace Integration: Angular CLI workspace-aware path resolution and project handling

Capabilities

ESLint Builder

The main Angular CLI builder that runs ESLint on TypeScript and Angular projects.

interface BuilderDefinition {
  implementation: string;
  schema: string;
  description: string;
}

// Builder registration in builders.json
{
  "builders": {
    "lint": {
      "implementation": "./dist/lint.impl.js",
      "schema": "./dist/schema.json", 
      "description": "Run ESLint over a TypeScript project"
    }
  }
}

Builder Configuration Schema

Complete configuration options for the ESLint builder.

import type { JsonObject } from '@angular-devkit/core';
import type { BuilderOutput } from '@angular-devkit/architect';

interface Schema extends JsonObject {
  // Required
  lintFilePatterns: string[];

  // Output and formatting
  format: Formatter;
  silent: boolean;
  outputFile: string | null;
  stats: boolean;

  // Error handling  
  force: boolean;
  quiet: boolean;
  maxWarnings: number;

  // Fixing and caching
  fix: boolean;
  cache: boolean;
  cacheLocation: string | null;
  cacheStrategy: 'content' | 'metadata';

  // ESLint configuration
  eslintConfig: string | null;
  ignorePath: string | null;
  noEslintrc: boolean;
  noConfigLookup: boolean;

  // Rules and plugins
  rulesdir: string[];
  resolvePluginsRelativeTo: string | null;
  reportUnusedDisableDirectives: 'off' | 'warn' | 'error';
}

type Formatter = 
  | 'stylish' 
  | 'compact' 
  | 'codeframe' 
  | 'unix' 
  | 'visualstudio' 
  | 'table' 
  | 'checkstyle' 
  | 'html' 
  | 'jslint-xml' 
  | 'json' 
  | 'json-with-metadata' 
  | 'junit' 
  | 'tap';

Configuration Options

Required Options

lintFilePatterns: Array of file patterns to lint

lintFilePatterns: string[]

Specifies which files to lint using glob patterns. Must be provided.

Output Options

format: ESLint output formatter

format: Formatter

Determines how linting results are displayed. Supports standard ESLint formatters like 'stylish', 'json', 'table', etc. Default: 'stylish'.

silent: Hide output text

silent: boolean

When true, suppresses all output except for the final exit code. Default: false.

outputFile: Write results to file

outputFile: string | null

If specified, writes the formatted results to this file instead of the console.

stats: Performance statistics

stats: boolean

Outputs performance statistics for ESLint rules. Requires flat config (eslint.config.js/ts/mjs). Default: false.

Error Handling Options

force: Continue on errors

force: boolean

When true, the build succeeds even if there are linting errors. Default: false.

quiet: Report errors only

quiet: boolean

Suppresses warnings and only reports errors. Default: false.

maxWarnings: Warning threshold

maxWarnings: number

Maximum number of warnings allowed before failing the build. Default: -1 (unlimited).

Fixing and Caching Options

fix: Auto-fix errors

fix: boolean

Automatically fixes linting errors that can be corrected. Default: false.

cache: Enable caching

cache: boolean

Caches lint results to improve performance on subsequent runs. Default: false.

cacheLocation: Cache directory

cacheLocation: string | null

Specifies where to store the cache files.

cacheStrategy: Cache detection method

cacheStrategy: 'content' | 'metadata'

Strategy for detecting changed files. Default: 'metadata'.

ESLint Configuration Options

eslintConfig: Config file path

eslintConfig: string | null

Path to a specific ESLint configuration file to use.

ignorePath: Ignore file path

ignorePath: string | null

Path to a file containing patterns to ignore (legacy config only).

noEslintrc: Disable .eslintrc lookup

noEslintrc: boolean

Disables use of .eslintrc files (legacy config only). Default: false.

noConfigLookup: Disable config lookup

noConfigLookup: boolean

Disables automatic configuration file lookup (flat config only). Default: false.

Rules and Plugin Options

rulesdir: Additional rules directories

rulesdir: string[]

Additional directories to load ESLint rules from. Default: [].

resolvePluginsRelativeTo: Plugin resolution base

resolvePluginsRelativeTo: string | null

Base directory for resolving ESLint plugins (legacy config only).

reportUnusedDisableDirectives: Report unused disables

reportUnusedDisableDirectives: 'off' | 'warn' | 'error'

Reports unused eslint-disable directives. Values: 'off', 'warn', 'error' (legacy config only).

ESLint Utility Functions

Internal utility functions for resolving and configuring ESLint instances.

/**
 * Resolves and instantiates the correct ESLint class based on configuration type
 * @param eslintConfigPath - Path to ESLint config file
 * @param options - Builder options
 * @param useFlatConfig - Whether to use flat config (default: false)
 * @returns ESLint class and instance
 */
function resolveAndInstantiateESLint(
  eslintConfigPath: string | undefined,
  options: Schema,
  useFlatConfig?: boolean
): Promise<{
  ESLint: typeof ESLint;
  eslint: ESLint;
}>;

/**
 * Supported flat config file names
 */
const supportedFlatConfigNames: string[];

Builder Output

The builder returns a standard Angular CLI builder output.

interface BuilderOutput {
  success: boolean;
  error?: string;
}

The success field indicates whether linting passed (no errors and within warning limits). The optional error field contains error messages if the build failed.

Usage Examples

Basic Configuration

{
  "projects": {
    "my-app": {
      "architect": {
        "lint": {
          "builder": "@angular-eslint/builder:lint",
          "options": {
            "lintFilePatterns": [
              "src/**/*.ts",
              "src/**/*.html"
            ]
          }
        }
      }
    }
  }
}

Advanced Configuration

{
  "projects": {
    "my-app": {
      "architect": {
        "lint": {
          "builder": "@angular-eslint/builder:lint", 
          "options": {
            "lintFilePatterns": ["src/**/*.ts", "src/**/*.html"],
            "format": "json",
            "fix": true,
            "cache": true,
            "cacheLocation": ".eslintcache",
            "maxWarnings": 0,
            "outputFile": "lint-results.json"
          }
        }
      }
    }
  }
}

Command Line Usage

# Basic linting
ng lint

# Fix auto-fixable issues
ng lint --fix

# Use specific formatter
ng lint --format=table

# Fail on any warnings
ng lint --maxWarnings=0

# Output to file
ng lint --outputFile=results.json

# Show performance stats (requires flat config)
ng lint --stats

# Quiet mode (errors only)
ng lint --quiet

# Force success even with errors
ng lint --force

Dependencies

Peer Dependencies

• eslint: ^8.57.0 || ^9.0.0 - The ESLint engine
• typescript: * - TypeScript compiler (for TypeScript projects)

Framework Dependencies

• @angular-devkit/architect: >= 0.2000.0 < 0.2100.0 - Angular CLI builder framework
• @angular-devkit/core: >= 20.0.0 < 21.0.0 - Angular DevKit core utilities

Error Handling

The builder handles several specific error scenarios:

TypeScript Parser Configuration Error

When TypeScript-aware ESLint rules are used without proper parserOptions.project configuration:

Error: You have attempted to use a lint rule which requires the full TypeScript type-checker to be available, but you do not have `parserOptions.project` configured to point at your project tsconfig.json files in the relevant TypeScript file "overrides" block of your project ESLint config

ESLint Version Error

When using an unsupported ESLint version:

Error: ESLint must be version 7.6 or higher.

Configuration Mismatch Errors

When using incompatible options with flat config:

• resolvePluginsRelativeTo removed in flat config
• ignorePath removed in flat config
• reportUnusedDisableDirectives removed in flat config

No Files Found Error

When lint patterns don't match any files:

Error: Invalid lint configuration. Nothing to lint. Please check your lint target pattern(s).

Ignored Files Error

When all matching files are ignored by .eslintignore:

Error: All files matching the following patterns are ignored:
- 'pattern1'
- 'pattern2'

Please check your '.eslintignore' file.