Skip to content
Linter for polymer web components
JavaScript HTML
Branch: master
Clone or download
jrunning Merge pull request #23 from Banno/update-readme-v0.9.0
Update README; bump version to 0.9.0
Latest commit cf4ffdc Dec 4, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
example
lib build Sep 7, 2016
spec Add missing semicolon Dec 4, 2018
src adding an no-unused-import exception for polymer-element Dec 4, 2018
.eslintrc.json ESLint Jun 21, 2016
.gitignore Add lib (compiled source) to repo Jun 29, 2016
LICENSE Add README.md, LICENSE; update package.json Jun 22, 2016
README.md Update README; bump version to 0.9.0 Dec 4, 2018
gulp.js gulp-polymer-lint Jun 28, 2016
jsdoc.json
package.json Update README; bump version to 0.9.0 Dec 4, 2018

README.md

polymer-lint

A linter for Polymer components

Table of Contents

Installation

$ npm install -g polymer-lint

Usage

Command line

polymer-lint [options] file.html [file.html] [dir]

  --ext [String]       File extension(s) to lint - default: .html
  --rules [String]     Names of rules to enable; defaults to all rules
  --color, --no-color  Force enabling/disabling of color
  -h, --help           Show help
  -v, --version        Output the version number

Rules

component-name-matches-filename

Ensures that the component defined in a file matches its filename.

OK

In a file named foo-component.html:

<dom-module id="foo-component">...</dom-module>
Error

In a file named foo-component.html:

<dom-module id="other-component">...</dom-module>

no-auto-binding

Ensures that only one-way bindings ([[val]]) are used.

OK
<a href="[[val]]">Hello</a>
<p>[[val]]</p>
Error
<a href="{{val}}">Hello</a>
<p>{{val}}</p>

no-missing-import

Ensures that all components that are used have been imported.

Note: This rule does not analyze imported files; it only analyzes <link/> tags and assumes that e.g. <link rel="import" href="foo-component.html"/> will define foo-component.

OK
<link rel="import" href="foo-component.html"/>
<dom-module id="my-component">
  <template>
    <foo-component/>
  </template>
</dom-module>
Error
<dom-module id="my-component">
  <template>
    <foo-component/>
  </template>
</dom-module>
Error
<dom-module id="my-component">
  <template>
    <button is="foo-component">Submit</button>
  </template>
</dom-module>
Error
<dom-module id="my-component">
  <template>
    <style include="my-styles"></style>
  </template>
</dom-module>

no-unused-import

Ensures that all components that are imported are used.

This rule assumes that imported filenames match the names of the elements they define, and ignores imports for names that don't end with .html or aren't valid custom element names. It also ignores the filename polymer-element.html.

OK
<link rel="import" href="@polymer/polymer/polymer-element.html"/>
<link rel="import" href="foo-component.html"/>
<dom-module id="my-component">
  <template>
    <foo-component/>
  </template>
</dom-module>
OK
<link rel="import" href="foo-component.html"/>
<dom-module id="my-component">
  <template>
    <button is="foo-component">Submit</button>
  </template>
</dom-module>
OK
<link rel="import" href="my-styles.html"/>
<dom-module id="my-component">
  <template>
    <style include="my-styles"></style>
  </template>
</dom-module>
Error
<link rel="import" href="foo-component.html"/>
<dom-module id="my-component">
  <template>
    <other-component/>
  </template>
</dom-module>

one-component

Ensures that a file defines no more than one component.

OK
<dom-module id="my-component">...</dom-module>
Error
<dom-module id="my-component">...</dom-module>
<dom-module id="another-component">...</dom-module>

style-inside-template

Ensures that no <style> tags appear outside of <template> tags.

OK
<dom-module id="my-component">
  <template>
    <style>/* ... */<style>
    ...
  </template>
</dom-module>
Error
<dom-module id="my-component">
  <style>/* ... */</style>
  <template>...</template>
</dom-module>

Linter directives

Component code can give instructions to the Linter via directives, which are HTML comments of the form:

<!-- bplint-directive-name arg1, arg2, ... -->

bplint-disable

The bplint-disable directive tells the linter to ignore errors reported by the given rules from this point on, within the current scope. For example:

<dom-module id="my-component">
  <article>
    <mystery-component-1/>
    <!-- bplint-disable no-missing-import -->
    <mystery-component-2/>
  </article>
  <mystery-component-3/>
</dom-module>

None of the three <mystery-component-*/> elements has been imported, but the bplint-disable directive ensures that errors will only be reported for <mystery-component-1/> (because it's before the directive) and <mystery-component-3/> (because it's outside the scope in which the bplint-disable directive was used.

The polymer-lint output for the above would be:

$ polymer-lint my-component.html
my-component.html
  3:5  Custom element 'mystery-component-1' used but not imported  no-missing-import
  7:3  Custom element 'mystery-component-3' used but not imported  no-missing-import

✖ 2 errors

bplint-enable

The bplint-enable directive negates the action of the bplint-disable directive from this point on, within the current scope. For example:

<dom-module id="my-component">
  <!-- bplint-disable no-missing-import -->
  <mystery-component-1/>
  <!-- bplint-enable no-missing-import -->
  <mystery-component-2/>
</dom-module>

Neither mystery-component-1 nor mystery-component-2 has been imported, but an error will be reported only for mystery-component-2. The polymer-lint output for the above would be:

$ polymer-lint my-component.html
my-component.html
  5:3  Custom element 'mystery-component-2' used but not imported  no-missing-import

✖ 2 errors

Gulp task

See gulp-task/README.md.

Node.js API

API documentation can be generated with JSDoc:

$ npm install -g jsdoc
$ jsdoc -c ./jsdoc.json
$ open doc/index.html

Configuration

At present configuration is only possible via command-line arguments or the Node.js API.

Development

Note: At present, development requires Node.js v6.0.0 or greater.

Install

$ git clone git@github.com:Banno/polymer-lint.git
$ cd polymer-lint
$ npm install

Build

To transpile the code:

$ npm run build

Transpiled code will be written to ./lib.

Run with examples

$ ./polymer-lint.js example

Jasmine specs

To run all of the specs:

$ npm test

To run a specific spec file:

$ npm test spec/lib/mySpec.js

By default the specs will run tests against the pre-transpiler code in ./src. To run the tests against the transpiled code (i.e. after npm run build), set the NODE_PATH environment variable:

$ NODE_PATH=./lib npm test

ESLint

$ npm run lint

Notes

Limitations

polymer-lint currently has the following limitations:

  • Only HTML code is linted. JavaScript code is not analyzed.
  • The polymer-lint command cannot read from STDIN.
  • The polymer-lint command can only be configured via command line arguments; it cannot read from a configuration file.

TODO

  • Windows support
  • Read configuration from file
  • Grunt task
  • Put API docs online
  • Editor integrations
You can’t perform that action at this time.