lit-analyzer

CLI that type checks bindings in lit-html templates

[![-----------------------------------------------------](https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png)](#installation) ## ➤ Installation ```bash npm install lit-analyzer -g ``` **Note:** - If you use Visual Studio Code you can also install the [lit-plugin](https://marketplace.visualstudio.com/items?itemName=runem.lit-plugin) extension. - If you use Typescript you can also install [ts-lit-plugin](https://github.com/runem/lit-analyzer/blob/master/packages/ts-lit-plugin). [![-----------------------------------------------------](https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png)](#usage) ## ➤ Usage `lit-analyzer` analyzes an optional `input glob` and emits the output to the console as default. When the `input glob` is omitted it will analyze all components in `src`. ```bash lit-analyzer src lit-analyzer "src/**/*.{js,ts}" lit-analyzer my-element.js lit-analyzer --format markdown --outFile result.md ``` [![-----------------------------------------------------](https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png)](#configuration) ## ➤ Configuration You can configure the CLI with arguments: ```bash lit-analyzer --strict --rules.no-unknown-tag-name off --format markdown ``` **Note:** You can also configure the CLI using a `tsconfig.json` file (see [ts-lit-plugin](https://github.com/runem/lit-analyzer/blob/master/packages/ts-lit-plugin)). ### Available arguments | Option | Description | Type | Default | | :----- | ----------- | ---- | ------- | | `--help` | Print help message | `boolean` | | | `--rules.rule-name` | Enable or disable rules (example: --rules.no-unknown-tag-name off). Severity can be "off" \| "warn" \| "error". See a list of rules [here](https://github.com/runem/lit-analyzer/blob/master/docs/readme/rules.md). | `{"rule-name": "off" \| "warn" \| "error"}` | | | `--strict` | Enable strict mode. This changes the default ruleset | `boolean` | | | `--format` | Change the format of how diagnostics are reported | `code` \| `list` \| `markdown` | code | | `--maxWarnings` | Fail only when the number of warnings is larger than this number | `number` | -1 | | `--outFile` | Emit all output to a single file | `filePath` | | | `--quiet` | Report only errors and not warnings | `boolean` | | | `--failFast` | Exit the process right after the first problem has been found | `boolean` | | | `--debug` | Enable CLI debug mode | `boolean` | | [![-----------------------------------------------------](https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png)](#rules) ## ➤ Rules The default severity of each rule depend on the `strict` [configuration option](#-configuration). Strict mode is disabled as default. Each rule can have severity of `off`, `warning` or `error`. You can toggle rules as you like. **Validating custom elements** | Rule | Description | Severity normal | Severity strict | | :------ | ----------- | --------------- | --------------- | | [no-unknown-tag-name](#-no-unknown-tag-name) | The existence of tag names are checked. Be aware that not all custom elements from libraries will be found out of the box. | off | warning | | [no-missing-import](#-no-missing-import) | When using custom elements in HTML it is checked if the element has been imported and is available in the current context. | off | warning | | [no-unclosed-tag](#-no-unclosed-tag) | Unclosed tags, and invalid self closing tags like custom elements tags, are checked. | warning | error | | [no-missing-element-type-definition](#no-missing-element-type-definition) | This rule will ensure that custom elements are registered on the `HTMLElementTagNameMap` Typescript interface. | off | off | **Validating binding names** | Rule | Description | Severity normal | Severity strict | | :------ | ----------- | --------------- | --------------- | | [no-unknown-attribute](#-no-unknown-attribute-no-unknown-property)
[no-unknown-property](#-no-unknown-attribute-no-unknown-property) | You will get a warning whenever you use an unknown attribute or property within your `lit-html` template. | off | warning | | [no-unknown-event](#-no-unknown-event) | When using event bindings it's checked that the event names are fired. | off | off | | [no-unknown-slot](#-no-unknown-slot) | Using the "@slot" jsdoc tag on your custom element class, you can tell which slots are accepted for a particular element. | off | warning | | [no-legacy-attribute](#no-legacy-attribute) | Disallows use of legacy Polymer binding syntax (e.g. `foo$=`). | off | warning | **Validating binding types** | Rule | Description | Severity normal | Severity strict | | :------ | ----------- | --------------- | --------------- | | [no-invalid-boolean-binding](#-no-invalid-boolean-binding) | Disallow boolean attribute bindings on non-boolean types. | error | error | | [no-expressionless-property-binding](#-no-expressionless-property-binding) | Disallow property bindings without an expression. | error | error | | [no-noncallable-event-binding](#-no-noncallable-event-binding) | Disallow event listener bindings with a noncallable type. | error | error | | [no-boolean-in-attribute-binding](#-no-boolean-in-attribute-binding) | Disallow attribute bindings with a boolean type. | error | error | | [no-complex-attribute-binding](#-no-complex-attribute-binding) | Disallow attribute bindings with a complex type. | error | error | | [no-nullable-attribute-binding](#-no-nullable-attribute-binding) | Disallow attribute bindings with nullable types such as "null" or "undefined". | error | error | | [no-incompatible-type-binding](#-no-incompatible-type-binding) | Disallow incompatible type in bindings. | error | error | | [no-invalid-directive-binding](#-no-invalid-directive-binding) | Disallow using built-in directives in unsupported bindings. | error | error | | [no-unintended-mixed-binding](#-no-unintended-mixed-binding) | Disallow mixed value bindings where a character `'`, `"`, `}` or `/` is unintentionally included in the binding. | warning | warning | **Validating LitElement** | Rule | Description | Severity normal | Severity strict | | :------ | ----------- | --------------- | --------------- | | [no-incompatible-property-type](#-no-incompatible-property-type) | When using the @property decorator in Typescript, the property option `type` is checked against the declared property Typescript type | warn | error | | [no-invalid-attribute-name](#-no-invalid-attribute-name) | When using the property option `attribute`, the value is checked to make sure it's a valid attribute name. | error | error | | [no-invalid-tag-name](#-no-invalid-tag-name) | When defining a custom element the tag name is checked to make sure it's valid. | error | error | | [no-property-visibility-mismatch](#no-property-visibility-mismatch) | This rule will ensure public properties use `@property` and non-public properties use `@internalProperty`. | off | warn | **Validating CSS** | Rule | Description | Severity normal | Severity strict | | :------ | ----------- | --------------- | --------------- | | [💅 no-invalid-css](#-no-invalid-css) | CSS within the tagged template literal `css` will be validated. | warning | error | ### Validating custom elements All web components in your code are analyzed using [web-component-analyzer](https://github.com/runem/web-component-analyzer) which supports native custom elements and web components built with LitElement. #### 🤷‍ no-unknown-tag-name Web components defined in libraries need to either extend the global `HTMLElementTagNameMap` (typescript definition file) or include the "@customElement tag-name" jsdoc on the custom element class. Below you will see an example of what to add to your library typescript definition files if you want type checking support for a given html tag name. ```typescript declare global { interface HTMLElementTagNameMap { "my-element": MyElement; } } ``` #### 📣 no-missing-import When using custom elements in HTML it is checked if the element has been imported and is available in the current context. It's considered imported if any imported module (or their imports) defines the custom element. The following example is considered a warning: ```js // No import of "my-element" html`` ``` The following example is not considered a warning: ```js import "my-element.js"; html`` ``` #### ☯ no-unclosed-tag Unclosed tags, and invalid self closing tags like custom elements tags, are checked. The following examples are considered warnings: ```js html`

` html`