- ➤ Installation
- ➤ Features
- ✅ Attribute/property type checking
- 🔍 Automatically pick up on custom elements
- 🌎 Support for dependencies that extend the global HTMLElementTagNameMap
- 📣 Report missing imports of custom elements
- ⚡️Event checking
- 📬 Slot checking
- 🚶Goto definition
- ✏️ Code completions for css and html
- 📖 Quick info on hover for html tags and attributes
- 🙈 Support for @ts-ignore comments inside html
⚠️ Warning if required attributes are not included- 💅 Reformat html
- 🚪 Auto close tags
- ➤ Feature comparison
- ➤ Configuring the plugin
- ➤ Contributors
- ➤ License
If you use Visual Studio Code you can simply install the lit-plugin extension.
code --install-extension runem.lit-plugin
This approach requires that you use Typescript.
First, install the plugin:
npm install ts-lit-plugin -D
Then add a plugins
section to your tsconfig.json
:
{
"compilerOptions": {
"plugins": [
{
"name": "ts-lit-plugin"
}
]
}
}
See Configuring the plugin for more information regarding how to configure the plugin.
lit-plugin
type checks all attributes and property assignment, both on your own elements, library elements and built in elements. You will also get the following warnings:
- Warning if you assign a complex type without using the
.
modifier. - Warning if you use the
?
modifier on a non-boolean type.
If the plugin doesn't pick up on your properties and attributes you can specify them using jsdoc on your element.
/**
* This is my element
* @attr size
* @attr {red|blue} color - The color of my element
* @prop {String} value
* @prop {Boolean} myProp - This is my property
*/
@customElement("my-element")
class MyElement extends LitElement {
}
If you define a custom element somewhere in your code lit-plugin
will automatically pick up on it. Then it will provide auto-import functionality, type checking and code completion out of the box by analyzing the element. web-component-analyzer is the tool that takes care of analyzing components.
If a dependency extends the global HTMLElementTagNameMap
this plugin will pick up on the map between the tag name and the 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.
declare global {
interface HTMLElementTagNameMap {
"my-element": MyElement;
}
}
Two limitations using this approach as of now
- By using this approach the plugin wont see detailed information about a given element as (e.g @property decorators and initializers) because it can only read public fields and their corresponding types. Therefore all properties on custom elements imported from libraries are optional and wont respect meta information in @property decorators.
lit-plugin
will only be able two find your elements if you somewhere in the code imports the file. Before your import the file it will complain that the element is unknown not that it can be imported. This due to the constraint that Typescript only adds library files to the array of program files once the file has been imported.
This plugin already supports custom vscode html data format (see the configuration section) and I will of course work on supporting more methods of shipping metadata alongside custom elements.
When using custom elements lit-plugin
checks if the element has been imported and is available in the current context. It's considered imported if any file in the path of imports defines the custom element. You can disable this check by setting skipMissingImports
to true in the configuration (see Configuring the plugin). Be aware that dependencies need to extend the global HTMLElementTagNameMap
in order for this plugin to pick up on them.
This plugin will check and suggest event names if you declare them in the jsdoc of the custom element class.
/**
* This is my element
* @event change
* @event commit - This event is dispatched when the user pressed 'commit'
*/
@customElement("my-element")
class MyElement extends LitElement {
}
This plugin will check and suggest slot names if you declare them in the jsdoc of the custom element class. A @slot
jsdoc tag without a name is the unnamed slot.
/**
* This is my element
* @slot - Default content placed in the middle
* @slot header - Content placed above the main content
* @slot footer - Content placed below the main content
*/
@customElement("my-element")
class MyElement extends LitElement {
}
Cmd+Click (Mac)
/ Ctrl+Click (Windows)
on a tag, attribute, property or event name and goto the definition.
Press Ctrl+Space
in an html or css context and to get code completions.
Hover above a tag, attribute, property or event and see more information about the identifier such as type and jsdoc.
Add "@ts-ignore" comments to make lit-plugin
quiet.
In front of html template tags:
This will make lit-plugin
opt out of any checking inside the html template tag, but not the nested html template tags.
// @ts-ignore
html`this is not checked ${html`this is checked`} `;
Inside HTML:
This will make lit-plugin
opt out of any checking inside the div tag.
return html`
<h1>Foo</h1>
<!-- @ts-ignore -->
<div>
<my-element></my-element>
</div>
<h1>Bar</h1>
`;
Note: This functionality has been temporarily disabled
lit-plugin
will warn you if you forget to set any required attributes on a given html tag. Right now this is based on the assumption that the property is required if it doesn't have an initializer and isn't assignable to undefined
or null
. Be aware that right now the plugin doesn't check if you assign it else where (for example in the constructor).
lit-plugin will think that the following is a required property:
@customElement("my-element")
export class MyElement extends LitElement {
@property({ type: String }) text!: string;
}
Note: This functionality has been temporarliy disabled. Please look into using prettier for reformating your html.
lit-plugin
will reformat html when you reformat code using your IDE. Keep in mind that right now there is an issue where the plugin does not take the current indentation of the html template tag into account. This means that the especially nested html template tags will look weird.
For example:
return html`<div>${html`<h1>Foo</h1> <h2>Bar</h2>`}</div>`;
Will become:
return html`
<div>
${html`<h1>Foo</h1>
<h2>Bar</h2>`}
</div>`;
And not::
return html`
<div>
${html`
<h1>Foo</h1>
<h2>Bar</h2>
`}
</div>`;
When typing html inside a template tag lit-plugin
auto-closes tags as you would expect.
This plugin is similar to vscode-lit-html on many points. The power of vscode-lit-html
is that it covers all the basic functionality of HTML in tagged templates so it's a plugin that can be easily used with other libraries than lit-html
. However ts-lit-plugin
aims to be a specialized plugin for working with lit-element
so for example it supports css
and discovers web components out of the box.
Below is a comparison table of the two plugins.
Feature | vscode-lit-html | vscode-lit-plugin |
---|---|---|
CSS support | ❌ | ✅ |
Goto definition | ❌ | ✅ |
Check missing imports | ❌ | ✅ |
Auto discover web components | ❌ | ✅ |
Template type checking | ❌ | ✅ |
Report unknown tag names | ❌ | ✅ |
Report unknown attrs | ❌ | ✅ |
Report unknown props | ❌ | ✅ |
Report unknown events | ❌ | ✅ |
Report unknown slots | ❌ | ✅ |
Support for vscode custom data format | ❌ | ✅ |
Auto close tags | ✅ | ✅ |
Syntax Highlighting | ✅ | ✅ |
Completions | ✅ | ✅ |
Quick info on hover | ✅ | ✅ |
Code folding | ✅ | |
Formatting | ✅ |
If you are using the vscode plugin you can configure these options directly from extension settings. If not you can add the options directly to the compilerOptions.plugins
section of your ts-config.json
file.
- Type: boolean
- Default: false
- Description: Completely disable this plugin.
- Type: string[]
- Default: ["html", "raw"]
- Description: List of template tags to enable html support in.
- Type: string[]
- Default: ["css"]
- Description: List of template tags to enable css support in.
- Type: boolean
- Default: false
- Description: Disable formatting the HTML on code reformat.
- Type: boolean
- Default: false
- Description: Activating this setting will make the plugin emit errors on unknown events.
- Type: boolean
- Default: false
- Description: Skip reporting missing imports of custom elements.
- Type: boolean
- Default: false
- Description: Don't attach suggestions alongside warnings and errors.
- Type: boolean
- Default: false
- Description: Skip reporting unknown html tags.
- Type: boolean
- Default: false
- Description: Skip reporting unknown html attributes.
- Type: boolean
- Default: false
- Description: Skip reporting unknown properties on elements.
- Type: boolean
- Default: false
- Description: Skip reporting unknown slot names.
- Type: boolean
- Default: false
- Description: Skip type checking of attributes and properties.
- Type: string[]
- Description: List of html tag names that you expect to be present at all times.
- Type: string[]
- Description: List of html attributes names that you expect to be present at all times.
- Type: string[]
- Description: List of event names that you expect to be present at all times.
- Type: Vscode custom HTML data format you can both specify a relative file paths or an entire objects with the data here. This value can both be an array and an object.
- Description: This plugin support the custom vscode html data format through this setting.
Rune Mehlsen | Andreas Mehlsen | You? |
Licensed under MIT.