How lit/lit-element works
Project Type and Purpose
• This is an open-source JavaScript/TypeScript library (npm package) called LitElement.
• Purpose: provide a lightweight base class for building Web Components using lit-html for rendering and Shadow DOM for encapsulation.
Main Components
a. Core Library Module
• src/lib/updating-element.ts – core ReactiveElement base class
• src/lib/css-tag.ts – CSS template literal helper
• src/decorators.ts – customElement, property, state decorators
• src/lit-element.ts – LitElement class extending UpdatingElement with render() API
b. Build & Packaging Pipeline
• TypeScript compiler (tsconfig.json) → generates .d.ts and .js
• Babel (.babelrc) → transpiles modern syntax for older browsers
• Rollup (rollup.config.js) → bundles ES modules into dist/ for npm
c. Testing Suite
• src/test & test/ – unit tests (Mocha/Chai or Web Component Tester)
• wct.conf.json – Web Component Tester configuration
• GitHub Actions workflows (/.github/workflows/tests.yml)
d. Documentation Site
• docs/ directory structured as a Jekyll site (docs/_layouts, docs/_includes, docs/_guide, docs/_api)
• Markdown guides (docs/_guide) + Handlebars templates → static HTML
• docs/main.py / docs/package.json & docs/rollup.config.js → custom tooling for API docs
e. Demo & Benchmark Suites
• demo/ – simple HTML + JS to showcase basic usage
• benchmarks/ – performance benchmarks (“shack” sample apps)
• GitHub Actions workflow for benchmarks (/.github/workflows/benchmarks.yml)
f. Repository Metadata & CI/CD
• .github/ – issue/pr templates, CODEOWNERS, workflows for testing & benchmarking
• npm package scripts in package.json → build, test, lint, docs, demo, bench
Component Relationships & Data Flow
• Developer writes TS source in src/ → compiles via TypeScript → Babel → Rollup → outputs package in dist/ → published to npm registry.
• Consumers import LitElement from npm → use decorators, property system, and render() API.
• Test runner picks up compiled code + test files → runs unit tests in headless browser.
• Documentation build reads Markdown + API JSON (typedoc.json output) → generates static docs site served via GitHub Pages.
• Benchmark suite loads built package in real browser pages to measure render/update performance.
Architectural Patterns & Design Principles
• Modular architecture: each concern (reactivity, templating, styling) lives in its own module.
• Pipeline pattern for build, test, docs, and benchmarks.
• Decorator pattern for declaring properties and custom elements.
• Separation of concerns: core engine vs. example apps vs. docs.
Technology Stack Call-outs
• Runtime: ES2015+ modules, Shadow DOM, Web Components APIs
• Template engine: lit-html
• Compilation: TypeScript, Babel
• Bundling: Rollup
• Testing: Mocha/Chai or Web Component Tester (WCT)
• Documentation generator: Jekyll (Ruby), Handlebars templates, Typedoc for API metadata
• CI/CD: GitHub Actions, npm registry
Essential Details to Capture
• Module boundaries: core reactivity vs. templating vs. styling
• Build/test/docs as separate pipelines
• Integration points with external tools (TypeScript, Babel, Rollup, Jekyll, WCT, GitHub Actions)
• Public API entrypoints vs. internal helper modules