Skip to main content

​
Extending ESLint

ESLint is designed to be completely extensible, allowing you to create custom rules, parsers, processors, formatters, and plugins to meet your project’s unique needs.

​
Prerequisites

To extend ESLint, you should have:
  • Knowledge of JavaScript, since ESLint is written in JavaScript
  • Familiarity with Node.js, since ESLint runs on it
  • Comfort with command-line programs
  • Understanding of Abstract Syntax Trees (ASTs)
Use ESLint Code Explorer to visualize AST structures and scope information for any JavaScript code.

​
Ways to Extend ESLint

ESLint provides multiple extension points, each serving different purposes:

Custom Rules

Create rules to enforce code standards specific to your project or organization.

Custom Parsers

Enable ESLint to understand non-standard JavaScript syntax or new language features.

Custom Processors

Process non-JavaScript files to extract and lint JavaScript code.

Custom Formatters

Control how ESLint displays linting results.

Plugins

Bundle rules, processors, and configs into reusable packages.

Shareable Configs

Share ESLint configurations across multiple projects.

​
Extension Architecture

Understanding how these extensions work together:

​
Parser

Transforms source code into an Abstract Syntax Tree (AST) that ESLint can analyze. Custom parsers enable support for TypeScript, JSX, or experimental syntax.

​
Rules

Analyze the AST and report problems. Rules are the core of ESLint’s functionality.

​
Processor

Extracts JavaScript from non-JavaScript files (like Markdown or HTML) before parsing.

​
Formatter

Formats linting results for display or integration with other tools.

​
Plugin

Packages multiple extensions together for distribution.

​
Common Use Cases

Create custom rules to enforce patterns unique to your codebase:
  • Specific naming conventions
  • Custom API usage patterns
  • Architecture constraints
  • Security requirements
Build custom parsers for:
  • Domain-specific languages
  • Experimental JavaScript features
  • TypeScript or Flow type annotations
  • Template languages
Use processors to lint:
  • Markdown code blocks
  • HTML script tags
  • Vue single-file components
  • Svelte components
Create formatters for:
  • CI/CD pipelines
  • IDE integrations
  • Code review systems
  • Custom reporting dashboards

​
Development Workflow

1

Understand the AST

Use the ESLint Code Explorer to visualize how your code is represented as an AST.
// Example code
const x = 5;

// Produces AST nodes:
// - Program
//   - VariableDeclaration (kind: "const")
//     - VariableDeclarator
//       - Identifier (name: "x")
//       - Literal (value: 5)
2

Implement Your Extension

Create your rule, parser, processor, or formatter following the appropriate guide.
3

Test Thoroughly

Use RuleTester for rules and write comprehensive test cases.
const { RuleTester } = require("eslint");
const ruleTester = new RuleTester();

ruleTester.run("my-rule", rule, {
  valid: ["const x = 1;"],
  invalid: [{
    code: "var x = 1;",
    errors: [{ message: "Use const instead" }]
  }]
});
4

Package and Publish

Bundle as a plugin or shareable config and publish to npm.

​
Performance Considerations

Extensions run for every file linted. Follow these best practices:
  • Minimize AST traversal: Only visit necessary node types
  • Cache expensive computations: Store results when possible
  • Avoid synchronous I/O: Never read files synchronously in rules
  • Use efficient algorithms: O(n²) operations can severely impact performance

​
Profiling Rules

Measure rule performance using the TIMING environment variable: 
TIMING=1 eslint lib
Output shows the slowest rules: 
Rule                    | Time (ms) | Relative
:-----------------------|----------:|--------:
no-unused-vars          |    52.472 |     6.1%
no-shadow               |    48.684 |     5.7%

​
Core APIs

Key APIs you’ll use when extending ESLint:

SourceCode

Access tokens, comments, and AST navigation methods

RuleTester

Test framework for validating rule behavior

context

Provides rule metadata, reporting, and configuration

Scope

Track variable declarations and references

fixer

Apply automatic fixes to code

CodePath

Analyze code execution paths

​
Best Practices

​
Documentation

  • Provide clear descriptions of what your extension does
  • Include examples of valid and invalid code patterns
  • Document all configuration options
  • Link to relevant resources

​
Testing

  • Test edge cases and error conditions
  • Include tests for all options and configurations
  • Verify fixes don’t introduce new problems
  • Test performance with large files

​
Versioning

  • Follow semantic versioning (semver)
  • Document breaking changes clearly
  • Maintain changelog
  • Test against multiple ESLint versions

​
Distribution

  • Use clear naming conventions (e.g., eslint-plugin-*)
  • Add appropriate npm keywords
  • Include comprehensive README
  • Specify peer dependencies correctly

​
Next Steps

Create Custom Rules

Start with the most common extension type

Build a Plugin

Package your extensions for distribution

​
Additional Resources