lit-plugin2

Type checking, code completion and syntax highlighting for lit-html templates in Visual Studio Code.

What this extension does

This extension reads the html and css tagged template literals in your JavaScript and TypeScript files. It then gives you the same help inside a template that you get in ordinary code:

• It reports errors in a template while you type.
• It completes tag names, attribute names, property names and event names.
• It shows type information and documentation when you point at a name.
• It finds the custom elements in your project automatically.

Installation

Install the packaged extension from a .vsix file:

code --install-extension lit-plugin.vsix

To build that file from this repository, run pnpm run package in packages/vscode-lit-plugin.

Features

Diagnostics

The extension applies a set of rules to each template. A rule can report an error, report a warning, or stay off. The Rules section lists all of them.

Code completion

Push Ctrl+Space in an html or a css template to get completions. The extension completes tag names, attributes, properties, events, CSS properties and CSS parts.

Quick info

Point at a tag, an attribute, a property or an event. The extension shows the type of the identifier and its JSDoc comment.

Go to definition

Push Cmd+Click on macOS, or Ctrl+Click on Windows and Linux, on a tag, an attribute, a property or an event. The editor opens the declaration.

Automatic tag close

The extension closes an html tag for you when you type it inside a template.

Custom element discovery

The extension finds a custom element that you declare anywhere in your project. It then gives you completion, type checking and an automatic import for that element. It uses web-component-analyzer to read the element.

Elements from a dependency

A dependency can add its elements to the global HTMLElementTagNameMap interface. The extension reads that map and applies the same checks to those elements.

declare global {
	interface HTMLElementTagNameMap {
		'my-element': MyElement;
	}
}

Two limits apply to an element that you get this way:

• The extension reads only the public fields and their types. It does not read a @property decorator or a field initializer. Each property is therefore optional.
• The extension finds the element only after some file in your project imports it. TypeScript adds a library file to the program at the point of the import, and not before it.

Rules

The default severity of a rule depends on the strict option. Strict mode is off by default. Set the severity of any rule to off, warning or error with the rules option.

Custom elements

Binding names

Binding types

LitElement

CSS

Configuration

Open Settings > Extensions > lit-plugin2 to set an option.

Documenting an element

The extension reads your code to find the properties, the attributes and the events of an element. Some of them are not visible in the code. Document those with JSDoc:

/**
 * This is my element.
 * @attr size
 * @attr {red|blue} color - The color of the element
 * @prop {String} value
 * @prop {Boolean} myProp - This is my property
 * @fires change
 * @fires my-event - This is my own event
 * @slot - This is the unnamed slot
 * @slot right - The right content
 * @slot left
 * @cssprop {Color} --border-color
 * @csspart header
 */
class MyElement extends HTMLElement {
}

customElements.define('my-element', MyElement);

How this extension works

The language server and two libraries give the extension its features:

• lit-language-server provides diagnostics, completions, and type information.
• vscode-lit-html highlights the html template tag.
• vscode-styled-components highlights the css template tag.

This extension starts the language server and sends it the relevant VS Code settings.

Report a problem with syntax highlighting to the highlighting library. Report all other problems to this repository.

Contributing

See CONTRIBUTING.md.

License

MIT. See LICENSE.md.

This extension is a fork of lit-analyzer by Rune Mehlsen and Andreas Mehlsen. The original copyright notice stays in the license file.