lit-analyzer

lit-analyzer is a standalone command-line tool that statically analyzes lit-html and LitElement templates written in JavaScript or TypeScript. Rather than waiting for a runtime error, it parses tagged template literals, cross-references them against your custom element definitions and TypeScript types, and reports problems like unknown tag names, mismatched attribute/property bindings, invalid CSS, and unclosed HTML tags.

The project is the analysis engine behind the popular vscode-lit-plugin and ts-lit-plugin editor integrations, but it also ships as its own npm-installable CLI (lit-analyzer src) for running in CI pipelines independent of any editor. Under the hood it composes the TypeScript compiler API, a vendored HTML/CSS language service, and web-component-analyzer to build a model of every custom element in a project, then runs a configurable set of rules against each template.

Because each rule can be toggled between off/warn/error and the whole ruleset can be switched into a stricter default mode with a single flag, teams can adopt lit-html type checking incrementally rather than fixing every violation on day one.

What You Get

• A lit-analyzer CLI binary that accepts a file, directory, or glob and reports diagnostics in code, list, or markdown format
• Type checking of lit-html attribute, property, and event bindings against the actual TypeScript types of the bound custom elements
• Over 20 individually toggleable rules covering unknown tags, missing imports, unclosed tags, invalid CSS, and LitElement @property type mismatches
• A --strict mode that flips the default severities of every rule at once for teams that want maximal coverage
• CI-friendly exit codes and a --maxWarnings threshold so builds can fail only past a configured warning count
• A reusable LitAnalyzer class and typed diagnostic/completion/definition APIs that power the VS Code and TypeScript-server plugins in the same monorepo

Common Use Cases

• Running lit-analyzer as a CI step to fail pull requests that introduce invalid lit-html bindings
• Catching typos in custom element tag names or attribute bindings before they reach the browser
• Enforcing that @property decorator types match the declared TypeScript property type on LitElement components
• Validating CSS written inside tagged css template literals for syntax errors
• Powering IDE type checking and autocompletion for lit-html templates via the companion vscode-lit-plugin and ts-lit-plugin packages

Under The Hood

Architecture The CLI entry point (src/lib/cli/cli.ts) parses arguments, builds a LitAnalyzerCliConfig, and delegates to analyzeCommand, which globs the target files and drives a LitAnalyzer instance (src/lib/analyze/lit-analyzer.ts) built on a LitAnalyzerContext. The LitAnalyzer dispatches each source file to a LitHtmlDocumentAnalyzer or LitCssDocumentAnalyzer depending on document type, which in turn parse tagged template literals into an internal HTML/CSS document model. Diagnostics are produced by a RuleCollection that iterates a prioritized, sorted list of independent RuleModule implementations, each visiting the parsed document tree and calling a shared report/break context API. This is a clean layered design — CLI, orchestration, document parsing, and rule evaluation are separated into distinct directories — and the same LitAnalyzer core is reused unmodified by the sibling ts-lit-plugin and vscode-lit-plugin packages in the monorepo, showing the abstraction genuinely holds up under multiple consumers.

Tech Stack The package is TypeScript-only, built with wireit-orchestrated tsc --build, and depends on vscode-html-languageservice and vscode-css-languageservice (vendored VS Code language services) for HTML/CSS parsing, parse5 for HTML tokenizing, ts-simple-type for structural TypeScript type comparison, and the author’s own web-component-analyzer for extracting custom element definitions from arbitrary source. The monorepo is managed with lerna, and the CLI itself has zero runtime framework dependencies beyond these analysis libraries plus chalk for terminal coloring and fast-glob for file matching.

Code Quality The project has an extensive test suite under src/test, with a dedicated test file per rule (20+ files covering rules like no-unknown-tag-name, no-invalid-boolean-binding, no-property-visibility-mismatch) plus parser and indexer test suites, all run through ava with custom tsTest/hasDiagnostic assertion helpers. Code is fully typed with strict TypeScript, uses ESLint and Prettier configs, and runs CI via GitHub Actions. Comment density is moderate — inline comments explain non-obvious control flow (e.g. why setTypescriptModule exists) rather than restating the code — which is typical of a mature, self-documenting codebase rather than a sparse one.

API Design The CLI surface is minimal and well-documented: a single positional glob argument, a handful of long-form flags, and a uniform --rules.<rule-name> <severity> pattern for per-rule configuration that scales to dozens of rules without flag sprawl. The exported LitAnalyzer class and its associated typed diagnostic/completion/definition interfaces form a stable public API that two other packages in the same repo build directly on top of, which is a strong practical signal of good API design — external consumers didn’t need to fork or route around it to build an editor integration.