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.
npm install @angular-eslint/builderThis package does not export a programmatic API. It functions as an Angular CLI builder and is used declaratively through Angular project configuration.
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=jsonThis Angular CLI builder is structured around several key components:
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"
}
}
}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';lintFilePatterns: Array of file patterns to lint
lintFilePatterns: string[]Specifies which files to lint using glob patterns. Must be provided.
format: ESLint output formatter
format: FormatterDetermines how linting results are displayed. Supports standard ESLint formatters like 'stylish', 'json', 'table', etc. Default: 'stylish'.
silent: Hide output text
silent: booleanWhen true, suppresses all output except for the final exit code. Default: false.
outputFile: Write results to file
outputFile: string | nullIf specified, writes the formatted results to this file instead of the console.
stats: Performance statistics
stats: booleanOutputs performance statistics for ESLint rules. Requires flat config (eslint.config.js/ts/mjs). Default: false.
force: Continue on errors
force: booleanWhen true, the build succeeds even if there are linting errors. Default: false.
quiet: Report errors only
quiet: booleanSuppresses warnings and only reports errors. Default: false.
maxWarnings: Warning threshold
maxWarnings: numberMaximum number of warnings allowed before failing the build. Default: -1 (unlimited).
fix: Auto-fix errors
fix: booleanAutomatically fixes linting errors that can be corrected. Default: false.
cache: Enable caching
cache: booleanCaches lint results to improve performance on subsequent runs. Default: false.
cacheLocation: Cache directory
cacheLocation: string | nullSpecifies where to store the cache files.
cacheStrategy: Cache detection method
cacheStrategy: 'content' | 'metadata'Strategy for detecting changed files. Default: 'metadata'.
eslintConfig: Config file path
eslintConfig: string | nullPath to a specific ESLint configuration file to use.
ignorePath: Ignore file path
ignorePath: string | nullPath to a file containing patterns to ignore (legacy config only).
noEslintrc: Disable .eslintrc lookup
noEslintrc: booleanDisables use of .eslintrc files (legacy config only). Default: false.
noConfigLookup: Disable config lookup
noConfigLookup: booleanDisables automatic configuration file lookup (flat config only). Default: false.
rulesdir: Additional rules directories
rulesdir: string[]Additional directories to load ESLint rules from. Default: [].
resolvePluginsRelativeTo: Plugin resolution base
resolvePluginsRelativeTo: string | nullBase 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).
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[];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.
{
"projects": {
"my-app": {
"architect": {
"lint": {
"builder": "@angular-eslint/builder:lint",
"options": {
"lintFilePatterns": [
"src/**/*.ts",
"src/**/*.html"
]
}
}
}
}
}
}{
"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"
}
}
}
}
}
}# 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 --forceThe builder handles several specific error scenarios:
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 configWhen using an unsupported ESLint version:
Error: ESLint must be version 7.6 or higher.When using incompatible options with flat config:
resolvePluginsRelativeTo removed in flat configignorePath removed in flat configreportUnusedDisableDirectives removed in flat configWhen lint patterns don't match any files:
Error: Invalid lint configuration. Nothing to lint. Please check your lint target pattern(s).When all matching files are ignored by .eslintignore:
Error: All files matching the following patterns are ignored:
- 'pattern1'
- 'pattern2'
Please check your '.eslintignore' file.