Repository files navigation

eslint-plugin-html

AESLint plugin to lint and fix inline scripts contained in HTML files.

• Usage
• Disabling ESLint
• Linting HTML
• Multiple scripts tags in a HTML file
  • History
• XML support
• Settings
  • html/html-extensions
  • html/xml-extensions
  • html/indent
  • html/report-bad-indent
  • html/javascript-tag-names
  • html/javascript-mime-types
  • html/ignore-tags-without-type
• Troubleshooting
  • No file linted when runningeslint on a directory
  • Linting templates (or PHP)
  • Linting VUE files
• Migration from older versions
  • To v4
  • To v3
• Credits

Simply install vianpm install --save-dev eslint-plugin-html and add the plugin to your ESLintconfiguration. SeeESLint documentation.

importhtmlfrom"eslint-plugin-html"exportdefault[{files:["**/*.html"],plugins:{ html},},]

{"plugins": ["html"]}

To temporarily disable ESLint, use the<!-- eslint-disable --> HTML comment. Re-enable it with<!-- eslint enable -->. Example:

<!-- eslint-disable --><script>varfoo=1</script><!-- eslint-enable -->

To disable ESLint for the next script tag only, use the<!-- eslint-disable-next-script --> HTMLcomment. Example:

<!-- eslint-disable-next-script --><script>varfoo=1</script>

Disabled script tags are completely ignored: their content will not be parsed as JavaScript. You canuse this to disable script tags containing template syntax.

This plugin focuses on applying ESLint rules on inline scripts contained in HTML. It does notprovide any rule related to HTML. For that, you can use other plugins like@eslint-html or@angular-eslint.eslint-plugin-html iscompatible with those plugins and can be used along them.

When linting a HTML with multiple script tags, this plugin tries to emulate the browser behavior bysharing the global scope between scripts by default. This behavior doesn't apply to "module"scripts (ie:<script type="module"> and most transpiled code), whereeach script tag gets its owntop-level scope.

ESLint has alreadyanoption to tell the parserif the script are modules.eslint-plugin-html will use this option as well to know if the scopesshould be shared (the default) or not. To change this, just set it in your ESLint configuration:

exportdefault[{// ...languageOptions:{sourceType:"module",},},]

{"parserOptions": {"sourceType":"module"  }}

To illustrate this behavior, consider this HTML extract:

<script>varfoo=1</script><script>alert(foo)</script>

This is perfectly valid by default, and the ESLint rulesno-unused-vars andno-undef shouldn'tcomplain. But if those scripts are considerated as ES modules,no-unused-vars should report anerror in the first script, andno-undef should report an error in the second script.

Ineslint-plugin-html v1 and v2, script code were concatenated and linted in a single pass, sothe scope were always shared. This causedsome issues, so in v3 all scriptswere linted separately, and scopes were never shared. In v4, the plugin still lint scriptsseparately, but makes sure global variables are declared and used correctly in the non-module case.

This plugin parses HTML and XML markup slightly differently, mainly when consideringCDATAsections:

• in XML, any data inside aCDATA section will be considered as raw text (not XML) and theCDATAdelimiter will be droped ;
• in HTML, there is no such thing for<script> tags: theCDATA delimiter is considered as normaltext and thus, part of the script.

Note: all settings can be written either as"html/key": value or in a nested object"html": { "key": value }

By default, this plugin will only consider files ending with those extensions as HTML:.erb,.handlebars,.hbs,.htm,.html,.mustache,.nunjucks,.php,.tag,.twig,.we.You can set your own list of HTML extensions by using this setting. Example:

exportdefault[{files:["**/*.html","**/*.we"],plugins:{ html},settings:{"html/html-extensions":[".html",".we"],// consider .html and .we files as HTML},},]

{"plugins": ["html"],"settings": {"html/html-extensions": [".html",".we"]// consider .html and .we files as HTML  }}

By default, this plugin will only consider files ending with those extensions as XML:.xhtml,.xml. You can set your own list of XML extensions by using this setting. Example:

exportdefault[{files:["**/*.html"],plugins:{ html},settings:{"html/xml-extensions":[".html"],// consider .html files as XML},},]

{"plugins": ["html"],"settings": {"html/xml-extensions": [".html"]// consider .html files as XML  }}

By default, the code between<script> tags is dedented according to the first non-empty line. Thesettinghtml/indent allows to ensure that every script tags follow an uniform indentation. Liketheindent rule, you can pass a number of spaces, or"tab" to indent with one tab. Prefix thisvalue with a+ to be relative to the<script> tag indentation. Example:

exportdefault[{files:["**/*.html"],plugins:{ html},settings:{"html/indent":"0",// code should start at the beginning of the line (no initial indentation)."html/indent":"+2",// indentation is the <script> indentation plus two spaces."html/indent":"tab",// indentation is one tab at the beginning of the line.},},]

{"plugins": ["html"],"settings": {"html/indent":"0",// code should start at the beginning of the line (no initial indentation)."html/indent":"+2",// indentation is the <script> indentation plus two spaces."html/indent":"tab"// indentation is one tab at the beginning of the line.  }}

By default, this plugin won't warn if it encounters a problematic indentation (ex: a line is underindented). If you want to make sure the indentation is correct, use thehtml/report-bad-indent inconjunction with theindent rule. Pass"warn" or1 to display warnings,"error" or2 todisplay errors. Example:

exportdefault[{files:["**/*.html"],plugins:{ html},settings:{"html/report-bad-indent":"error",},},]

{"plugins": ["html"],"settings": {"html/report-bad-indent":"error"  }}

By default, the code between<script> tags is considered as JavaScript. You can customize whichtags should be considered JavaScript by providing one or multiple tag names.

Example:

exportdefault[{files:["**/*.html"],plugins:{ html},settings:{"html/javascript-tag-names":["script","customscript"],},},]

{"plugins": ["html"],"settings": {"html/javascript-tag-names": ["script","customscript"]  }}

By default, the code between<script> tags is considered as JavaScript code only if there is notype attribute or if its value matches the pattern(application|text)/(x-)?(javascript|babel|ecmascript-6) ormodule (case insensitive). You cancustomize the types that should be considered as JavaScript by providing one or multiple MIME types.If a MIME type starts with a/, it will be considered as a regular expression. Example:

exportdefault[{files:["**/*.html"],plugins:{ html},settings:{"html/javascript-mime-types":["text/javascript","text/jsx"],// also use script tags with a "text/jsx" type attribute"html/javascript-mime-types":"/^text\\/(javascript|jsx)$/",// same thing},},]

{"plugins": ["html"],"settings": {"html/javascript-mime-types": ["text/javascript","text/jsx"],// also use script tags with a "text/jsx" type attribute"html/javascript-mime-types":"/^text\\/(javascript|jsx)$/"// same thing  }}

By default, the code between<script> tags is considered JavaScript if there is notypeattribute. You can set this setting totrue to ignore script tags without atype attribute.Example:

exportdefault[{files:["**/*.html"],plugins:{ html},settings:{"html/ignore-tags-without-type":true,},},]

{"plugins": ["html"],"settings": {"html/ignore-tags-without-type":true  }}

By default, when executing theeslint command on a directory, only.js files will be linted. Youwill have to specify extra extensions with the--ext option. Example:eslint --ext .html,.js srcwill lint both.html and.js files in thesrc directory. SeeESLintdocumentation.

eslint-plugin-html won't evaluate or remove your template markup. If you have template markup inyour script tags, the resulting script may not be valid JavaScript, soESLint will fail to parseit. Here are some workarounds:

• You can useHTML comments to disable ESLint for specific script tags.

• For PHP, you can useeslint-plugin-php-markup to lint phpfiles, it use a same way to process php markup likeeslint-plugin-html.

• Another possible hacky workaround to make sure the code is valid JavaScript is to put yourtemplate markup inside a comment. When the template is rendered, the generated JS code must startwith a new line, so it will be written below the comment. PHP example:

<script>varmydata// <?= "\n mydata = " . json_encode($var) . ";" ?>console.log(mydata)</script>

Initially,eslint-plugin-vue was usingeslint-plugin-html to lint code inside script tags. Since v3,eslint-plugin-vue is using itsown parser, so it isincompatible witheslint-plugin-html. You should useeslint-plugin-vueexclusively and removeeslint-plugin-html from your dependencies if you still have it.

eslint-plugin-html v4 requires at least ESLint v4.7. This is because a lot of internal changesoccured in ESLint v4.7, including anew API to support autofixing inpreprocessors.If you are still using an older version of ESLint, please consider upgrading, or keep usingeslint-plugin-html v3.

The big feature (and breaking change) ineslint-plugin-html v4 is the ability to choose howscopesare shared between script tags in the same HTML file.

If you are considering upgrading to v3, please readthis guide.

A big thank you to@kuceb for the logo image!