Registry / testing / lit-analyzer

lit-analyzer

JSON →
library2.0.3jsnpmunverified

Lit Analyzer is a command-line interface (CLI) tool designed to provide static analysis and type checking for Lit templates within JavaScript and TypeScript projects. It enhances the developer experience by catching common errors related to Lit element properties, events, and slots before runtime. The current stable version is 2.0.3, with regular updates to support new Lit features and address community feedback. Key differentiators include its deep integration with TypeScript for template-bound expressions, offering autocompletion suggestions, and enforcing best practices through configurable rules, such as ensuring proper property visibility (`@property`, `@internalProperty`) and correct custom element registration in `HTMLElementTagNameMap`. Its development is active, with significant improvements introduced in the transition to v2.

testing
npm install lit-analyzer
github ↗package ↗
INSTALL
IMPORT
SIG · LIT-ANALYZER
L
lit-analyzer
testingjavascriptv2.0.3
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

This quickstart demonstrates how to install and run `lit-analyzer` on a basic Lit component to catch common template-related type errors and best practice violations.

{ "name": "lit-analyzer-example", "version": "1.0.0", "scripts": { "analyze": "lit-analyzer --strict" }, "devDependencies": { "lit": "^2.0.0", "lit-analyzer": "^2.0.0", "typescript": "^4.0.0" } } // my-element.ts import { LitElement, html, property } from 'lit'; import { customElement } from 'lit/decorators.js'; interface MyData { value: string; } @customElement('my-element') export class MyElement extends LitElement { @property({ type: String }) name: string = 'World'; @property({ type: Number }) count: number = 0; @property({ attribute: false }) data?: MyData; render() { return html` <h1>Hello, ${this.name}!</h1> <p>Count: ${this.count}</p> ${this.data ? html`<p>Data value: ${this.data.value}</p>` : ''} <button @click="${this._increment}">Increment</button> <!-- Lit Analyzer will warn about invalid event name 'my-event' --> <button @my-event="${() => console.log('This will error')}">Custom Event</button> <!-- Lit Analyzer will warn about undefined property 'undefinedProp' --> <p>${(this as any).undefinedProp}</p> <!-- Cast to any to prevent TS error in editor --> `; } private _increment() { this.count++; } } declare global { interface HTMLElementTagNameMap { 'my-element': MyElement; } } // To run: // 1. npm install // 2. npm run analyze
lit-analyzer --version
Debug
Known issues
breakingUpgrading to version 2.0.0 from a 1.x.x release may introduce stricter type checking and require adjustments to your Lit component definitions or template usage. While no major API surface changes were explicitly documented as 'breaking' for users, internal architectural shifts and tightened rule defaults are common in major version bumps for static analysis tools.
fix
Review `lit-analyzer`'s output carefully after upgrading. Address any new warnings or errors by adjusting component properties, event listeners, or template expressions to comply with stricter type definitions or new rule enforcements.
affects: >=2.0.0
gotchaFor `lit-analyzer` to perform comprehensive analysis, especially type checking, a `tsconfig.json` file must be present and correctly configured in your project root or specified via the `--config` flag. Without it, the analyzer operates in a more limited mode.
fix
Ensure a valid `tsconfig.json` exists in your project. If your Lit files are not directly within the `include` paths, adjust the `tsconfig.json` or specify `files` explicitly. Example: `{ "compilerOptions": { "target": "es2020", "module": "esnext" }, "include": ["src/**/*.ts", "./my-element.ts"] }`.
affects: >=1.0.0
gotchaThe `no-missing-element-type-definition` rule, introduced in v1.2.0, ensures that all custom elements are properly registered in the `HTMLElementTagNameMap` TypeScript interface. Failing to do so will result in a warning.
fix
Add a `declare global` block to one of your TypeScript definition files (e.g., `global.d.ts` or directly in the component file) to extend `HTMLElementTagNameMap` with your custom element. Example: `declare global { interface HTMLElementTagNameMap { 'my-element': MyElement; } }`.
affects: >=1.2.0
gotchaThe `no-property-visibility-mismatch` rule, added in v1.2.0, enforces the use of `@property` decorator for public properties and `@internalProperty` (or no decorator) for non-public ones. This helps maintain a clear API surface for your Lit components.
fix
Explicitly decorate public properties that should be exposed with `@property()`. Ensure internal-only properties either use `@internalProperty()` or are not decorated with `@property()` if they are not meant to be reactive or exposed to the outside.
affects: >=1.2.0
Errors
Common errors & fixes
Error: Could not find a tsconfig.json in the current working directory or any of its parent directories.
`lit-analyzer` requires a `tsconfig.json` for type checking, but none was found in the project's hierarchy.
fix
Create a `tsconfig.json` file in your project root. A minimal configuration will suffice for `lit-analyzer` to operate, e.g., `{ "compilerOptions": { "target": "es2020", "module": "esnext", "moduleResolution": "node" }, "include": ["src/**/*.ts"] }`.
Property 'someProperty' does not exist on type 'MyElement'. Did you mean 'someOtherProperty'?
A property or attribute used in a Lit template expression (e.g., `${this.someProperty}`) is not defined on the corresponding LitElement class, or its type definition is incorrect.
fix
Define the property explicitly on your LitElement class, ensuring it has the correct name and type, and is potentially decorated with `@property()` if it's a reactive property. Double-check for typos.
Custom element 'my-component' is not defined in 'HTMLElementTagNameMap'.
The custom element tag name is used in a template, but the element's type definition is not registered in the global `HTMLElementTagNameMap` interface, which `lit-analyzer` uses for type checking.
fix
Add a `declare global` block in a TypeScript file to extend `HTMLElementTagNameMap` with your custom element's tag and class type: `declare global { interface HTMLElementTagNameMap { 'my-component': MyComponentClass; } }`.
Event 'some-invalid-event' does not exist on element 'button'.
An event listener is specified in a template for an event that is not a standard DOM event or is not explicitly declared as a custom event by the element.
fix
Ensure that the event name is a valid DOM event (e.g., `click`, `input`) or a correctly dispatched custom event from the component. If it's a custom event, ensure the component itself dispatches it correctly and consider adding JSDoc `@fires` tags for better documentation and tooling.
Upgrade
Version history
2.0.3latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
2 hits · last 30 days
node
2
Resources
githubhttps://github.com/runem/lit-analyzer ↗
packagehttps://www.npmjs.com/package/lit-analyzer ↗
lit-analyzer — npm install lit-analyzer · libregistry