DOCSEARCHbyAlgolia
Submit Docs

ESLint Config Inspector

repository·main·Indexed 23 days ago

https://github.com/eslint/config-inspector

A visual tool for inspecting and understanding ESLint flat configurations through an interactive web interface. It allows developers to run a local server via npx, build static Single-Page Applications (SPA) of their configuration, and utilize a CLI for configuration path resolution and rule extraction. The tool supports modern flat config filenames (e.g., eslint.config.js, .ts) and provides a set of UI components for visualizing rules, files, and configuration items.

Tokens
2.7K
Snippets
3
Records
22
Agent score
79%

What's inside @eslint/config-inspector

  1. Overview of ESLint Config Inspector components

    main
    The ESLint Config Inspector is composed of several UI building blocks used to visualize ESLint configurations. These components are categorized into Chrome (navigation and badges), Configs (configuration details), Rules (rule listings and states), Files (file-specific information), and Primitives (low-level UI elements).

  2. Use ESLint Config Inspector Config components

    main

    Config components are used to display information about the ESLint configuration itself:

    • ConfigItem: Displays configuration items, including scoped versions.
    • ColorizedConfigName: Displays configuration names with colorization.
    • SummarizeItem: Used to summarize items, such as rules.
    • GlobItem: Displays glob patterns used in configurations.

  4. Use ESLint Config Inspector Rule components

    main

    Rule components are used to visualize the status and details of ESLint rules:

    • RuleList: A collection of rules.
    • RuleItem: An individual rule in a list view.
    • RuleStateItem: Displays the state of a rule, including options.
    • ColorizedRuleName: Displays rule names with colorization (e.g., for plugin rules).
    • RuleLevelIcon: Displays an icon representing the rule's error level.
    • RuleDeprecatedInfo: Displays information regarding deprecated rules.

  7. Build a static web app of your ESLint config

    main

    You can generate a static Single-Page Application (SPA) that contains a snapshot of your current ESLint configuration. This is useful for deploying the configuration view to a web server or using it for comparisons. The output will be generated in the dist/__eslint-config-inspector directory.

    npx @eslint/config-inspector build

  8. Run ESLint Config Inspector locally

    main

    To visually inspect and understand your ESLint flat configs, navigate to your project root (the directory containing eslint.config.js) and run the inspector using npx. The tool will start a local server, typically at http://localhost:7777, where you can interact with your configuration. Changes made to your configuration files will be automatically reflected in the inspector.

    npx @eslint/config-inspector@latest

  9. Understand the ESLintConfig return type

    main

    When calling readConfig, the returned object contains three primary properties:

    • configs: An array of FlatConfigItem objects representing the raw configuration items (including ESLint defaults).
    • dependencies: An array of file paths representing all local files transitively imported by the configuration. These are the files the inspector should watch.
    • payload: A processed object containing:
      • configs: Transformed configuration items (e.g., with simplified plugin/parser references).
      • rules: A flattened map of all available rules (including name, plugin, and metadata).
      • files: (Optional) A list of MatchedFile objects if globMatchedFiles was enabled, mapping file paths to the specific configs that apply to them.
      • meta: Metadata including lastUpdate, basePath, and configPath.

  11. Troubleshoot ESLint config path errors

    main

    If you encounter errors related to finding or loading ESLint configuration files, the @eslint/config-inspector uses specific error types to provide diagnostic information:

    1. ConfigPathError: Occurs when the inspector cannot find any valid ESLint configuration file. The error message will list the directory it searched (basePath) and the specific filenames it was looking for (configFilenames).
    2. ConfigPathLegacyError: Occurs when the inspector encounters an unsupported legacy configuration file instead of the new flat config format. The inspector only supports the new flat config format as described in the ESLint documentation.

  12. Read and process ESLint configuration

    main

    Use readConfig to load an ESLint configuration file and transform it into a processed payload suitable for the Config Inspector.

    readConfig performs several complex tasks:

    1. Loads the config: Uses jiti to ensure compatibility with various module formats (ESM, CJS, TS).
    2. Cache Busting: Appends mtime query parameters to URLs to ensure that changes to the config or its transitive imports are reflected during hot-reloads. On Node.js ≥ 22.15, it uses module.registerHooks to propagate this cache-busting to all imported files.
    3. Dependency Tracking: Automatically discovers all local files imported by the configuration so the inspector can watch them for changes.
    4. Rule Extraction: Merges built-in ESLint rules with rules defined in your configuration and plugins.
    5. Default Injection: Includes ESLint's default configurations (languages, ignores, and file patterns).

    Options

    OptionTypeDefaultDescription
    chdirbooleantrueIf true, changes the current process working directory to the configuration's basePath.
    globMatchedFilesbooleantrueIf true, performs a file system walk to find all files that match the provided configuration.