ESLint HTML Parser

6.8.2 · active · verified Sun Apr 19

eslint-html-parser is a custom ESLint parser designed to lint HTML files, including embedded JavaScript within `<script>` tags. It achieves this by parsing HTML into a specific Abstract Syntax Tree (AST) structure, while delegating the parsing of JavaScript code (both in `<script>` tags and standalone `.js`/`.jsx` files) to a configurable ECMAScript parser, defaulting to `espree`. This enables developers to apply standard ESLint rules to their JavaScript within HTML, as well as define custom rules that target the HTML structure itself. The package is currently at version 6.8.2 and appears to be actively maintained, offering a crucial bridge for projects that require robust linting across both HTML and JavaScript within a single ESLint setup. It differentiates itself by providing a comprehensive HTML AST for deep linting, unlike simpler preprocessors that only extract script content.

Common errors

```
ESLint was configured to use the parser "eslint-html-parser" but that parser was not found.
```
cause The `eslint-html-parser` package is not installed or the path to it is incorrect in the ESLint configuration.

fix Ensure `eslint-html-parser` is installed as a dev dependency: `npm install --save-dev eslint-html-parser`. Verify the `parser` setting in `.eslintrc.*` is exactly `"eslint-html-parser"`.
```
Parsing error: The keyword 'await' is reserved (ESLint)
```
cause The `parserOptions.ecmaVersion` is set too low for modern JavaScript features like `await` or `async` functions.

fix Increase `parserOptions.ecmaVersion` in your ESLint config to a version that supports the syntax, e.g., `2021` or `latest`.
```
Definition for rule 'no-console' was not found.
```
cause While `eslint-html-parser` parses HTML and JS, it doesn't provide rules itself. This error means a configured rule is missing.

fix Ensure you have an `extends` configuration (e.g., `"extends": "eslint:recommended"`) or explicitly define the rules or plugins that provide the rules you intend to use.
```
No files were linted. Please ensure that 'files' is set correctly in your configuration.
```
cause ESLint is not configured to process files with `.htm` or `.html` extensions, or the glob patterns/extensions in the CLI command are incorrect.

fix Add `.htm` and `.html` to your ESLint CLI command using `--ext .htm --ext .html` or ensure your `files` array in `eslint.config.js` or `overrides` in `.eslintrc.*` includes patterns like `"**/*.{js,htm,html}"`.

Warnings

breaking ESLint v9.0.0 and above deprecate the legacy `.eslintrc.*` configuration system in favor of flat config (`eslint.config.js`). `eslint-html-parser` examples typically use `.eslintrc.json`, which may require adaptation for newer ESLint versions.
Fix: Migrate your ESLint configuration from `.eslintrc.*` to `eslint.config.js` (flat config) following ESLint's migration guide. Ensure `eslint-html-parser` is correctly specified in the new format, potentially using `languageOptions.parser` for file patterns.
gotcha The parser requires Node.js 6.x or later and ESLint 6.x or later. Using older versions will lead to installation or runtime errors.
Fix: Upgrade Node.js to a supported version (e.g., LTS) and ESLint to version 6.x or newer via `npm install --save-dev eslint@latest`.
gotcha By default, ESLint only lints `.js` files when run on a directory. To lint HTML files, you must explicitly specify the extensions using glob patterns in the CLI or the `--ext` option.
Fix: When running ESLint from the command line, use glob patterns like `eslint "./**/*.{js,htm,html}"` or explicitly list extensions: `eslint --ext .htm --ext .html --ext .js src/`.
gotcha The `parserOptions` for `eslint-html-parser` directly map to the options supported by the underlying JavaScript parser (defaulting to `espree`). Misconfiguring `ecmaVersion`, `sourceType`, or `ecmaFeatures` can lead to parsing errors for JavaScript content.
Fix: Ensure that `parserOptions` in your `.eslintrc.*` or `eslint.config.js` accurately reflect the ECMAScript version and features used in your JavaScript code (e.g., `ecmaVersion: 2021`, `sourceType: 'module'`, `ecmaFeatures: { jsx: true }` for modern JS with JSX).

Install

npm install eslint-html-parser npm
yarn add eslint-html-parser yarn
pnpm add eslint-html-parser pnpm

Imports

parseForESLint
```
import { parseForESLint } from 'eslint-html-parser';
```
Primarily an internal ESLint API. Directly importing and using this is for advanced custom tooling or deep integration, not typical application usage. It's the entry point ESLint calls to parse files.
HTMLElement
```
import type { HTMLElement } from 'eslint-html-parser';
```
Type import for the AST node representing an HTML element. Useful when developing custom ESLint rules that traverse the HTML AST produced by this parser.
HTMLAttribute
```
import type { HTMLAttribute } from 'eslint-html-parser';
```
Type import for the AST node representing an HTML attribute. Useful when developing custom ESLint rules that target HTML attributes.

Quickstart

Demonstrates installation, basic ESLint configuration using eslint-html-parser for both HTML and standalone JavaScript files, and running the linter.

{
  "name": "my-linted-project",
  "version": "1.0.0",
  "description": "Example project using eslint-html-parser",
  "scripts": {
    "lint": "eslint \"./**/*.{js,htm,html}\"
  },
  "devDependencies": {
    "eslint": "^8.0.0",
    "eslint-html-parser": "^6.0.0"
  }
}

// .eslintrc.json
{
  "root": true,
  "parser": "eslint-html-parser",
  "parserOptions": {
    "ecmaVersion": 2021,
    "sourceType": "module",
    "ecmaFeatures": {
      "jsx": true
    }
  },
  "env": {
    "browser": true,
    "es2021": true
  },
  "extends": "eslint:recommended",
  "rules": {
    "no-console": "warn"
  }
}

<!-- src/index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Document</title>
</head>
<body>
  <h1>Hello, HTML Lint!</h1>
  <script>
    console.log("This JS will be linted."); // no-console will warn here
    var unusedVar = 1;
  </script>
  <my-custom-element some-attribute="value"></my-custom-element>
</body>
</html>

// src/app.js
console.log("This standalone JS will also be linted.");

# Terminal commands to set up and run:
npm init -y
npm install --save-dev eslint eslint-html-parser
# Create .eslintrc.json, src/index.html, src/app.js as shown above
npm run lint

view raw JSON →