lit-best-practices

name	lit-best-practices
description	Lit web components best practices and performance optimization guidelines. Use when writing, reviewing, or refactoring Lit web components. Triggers on tasks involving Lit components, custom elements, shadow DOM, reactive properties, or web component performance.
license	MIT
author	community
version	1.0.0

Lit Web Components Best Practices

Best practices for building Lit web components, optimized for AI-assisted code generation and review.

When to Use

Reference these guidelines when:

• Writing new Lit web components
• Implementing reactive properties and state
• Reviewing code for performance or accessibility issues
• Refactoring existing Lit components
• Optimizing rendering and update cycles

Rule Categories

Category	Rules	Focus
1. Component Structure	4 rules	Properties, state, TypeScript
2. Rendering	5 rules	Templates, directives, derived state
3. Styling	4 rules	Static styles, theming, CSS parts
4. Events	3 rules	Custom events, naming, cleanup
5. Lifecycle	4 rules	Callbacks, timing, async
6. Accessibility	3 rules	ARIA, focus, forms
7. Performance	4 rules	Updates, caching, lazy loading

Priority Levels

Priority	Description	Action
CRITICAL	Major correctness or accessibility issues	Fix immediately
HIGH	Significant maintainability/performance impact	Address in current PR
MEDIUM	Best practice violations	Address when touching related code
LOW	Style preferences, micro-optimizations	Consider during refactoring

Rules Index

1. Component Structure

• rules/1-1-use-decorators.md - Use TypeScript Decorators (HIGH)
• rules/1-2-separate-state.md - Separate Public Properties from Internal State (HIGH)
• rules/1-3-reflect-sparingly.md - Reflect Properties Sparingly (MEDIUM)
• rules/1-4-default-values.md - Always Provide Default Values (HIGH)

2. Rendering

• rules/2-1-pure-render.md - Keep render() Pure (CRITICAL)
• rules/2-2-use-nothing.md - Use nothing for Empty Content (MEDIUM)
• rules/2-3-use-repeat.md - Use repeat() for Keyed Lists (HIGH)
• rules/2-4-use-cache.md - Use cache() for Conditional Subtrees (MEDIUM)
• rules/2-5-derived-state.md - Compute Derived State in willUpdate() (HIGH)

3. Styling

• rules/3-1-static-styles.md - Always Use Static Styles (CRITICAL)
• rules/3-2-host-styling.md - Style the Host Element Properly (HIGH)
• rules/3-3-css-custom-properties.md - CSS Custom Properties for Theming (MEDIUM)
• rules/3-4-css-parts.md - CSS Parts for Deep Styling (MEDIUM)

4. Events

• rules/4-1-composed-events.md - Dispatch Composed Events (CRITICAL)
• rules/4-2-event-naming.md - Event Naming Conventions (MEDIUM)
• rules/4-3-cleanup-listeners.md - Clean Up Event Listeners (HIGH)

5. Lifecycle

• rules/5-1-super-call-order.md - Correct super() Call Order (CRITICAL)
• rules/5-2-first-updated.md - Use firstUpdated for DOM Operations (HIGH)
• rules/5-3-will-update.md - Use willUpdate for Derived State (HIGH)
• rules/5-4-update-complete.md - Async Operations with updateComplete (MEDIUM)

6. Accessibility

• rules/6-1-delegates-focus.md - delegatesFocus for Interactive Components (HIGH)
• rules/6-2-aria-attributes.md - ARIA for Custom Interactive Components (CRITICAL)
• rules/6-3-form-associated.md - Form-Associated Custom Elements (HIGH)

7. Performance

• rules/7-1-has-changed.md - Custom hasChanged for Complex Types (HIGH)
• rules/7-2-batch-updates.md - Batch Property Updates (MEDIUM)
• rules/7-3-lazy-loading.md - Lazy Load Heavy Dependencies (HIGH)
• rules/7-4-memoization.md - Memoize Expensive Computations (MEDIUM)

Quick Reference

Essential Imports

// Core
import { LitElement, html, css, nothing } from 'lit';
import { customElement, property, state, query } from 'lit/decorators.js';

// Common Directives
import { repeat } from 'lit/directives/repeat.js';
import { cache } from 'lit/directives/cache.js';
import { classMap } from 'lit/directives/class-map.js';
import { until } from 'lit/directives/until.js';

Component Skeleton

@customElement('my-component')
export class MyComponent extends LitElement {
  static styles = css`
    :host { display: block; }
    :host([hidden]) { display: none; }
  `;

  @property({ type: String }) value = '';
  @property({ type: Boolean, reflect: true }) disabled = false;
  @state() private _internal = '';

  render() {
    return html`<slot></slot>`;
  }
}

Resources

• Lit Documentation
• Open Web Components
• Lion Web Components
• web.dev Custom Elements Best Practices