# lit/lit-element architecture

> Architecture diagram of the GitHub repository lit/lit-element, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lit/lit-element
- Repository: https://github.com/lit/lit-element

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library Modules
    subgraph "Core Library"
        Updating["src/lib/updating-element.ts"]:::source
        CSS["src/lib/css-tag.ts"]:::source
        Decorators["src/decorators.ts"]:::source
        LitElement["src/lit-element.ts"]:::source
    end

    %% Build & Packaging Pipeline
    subgraph "Build & Packaging" 
        TS["tsconfig.json"]:::pipeline
        Babel[".babelrc"]:::pipeline
        Rollup["rollup.config.js"]:::pipeline
        Dist["dist/"]:::output
    end

    %% Publish & Registry
    subgraph "Publish"
        Publish["npm publish"]:::pipeline
        Registry["npm registry"]:::external
    end

    %% Consumers
    Consumers["App Developers"]:::external

    %% Test Pipeline
    subgraph "Test Pipeline"
        TestsTS["src/test/"]:::pipeline
        TestsRunner["test/runner.html<br/>runner-babel.html<br/>test/index.html"]:::pipeline
        WCT["wct.conf.json"]:::pipeline
        ActionsTest[".github/workflows/tests.yml"]:::external
    end

    %% Documentation Pipeline
    subgraph "Docs Pipeline"
        DocsSrc["docs/"]:::source
        Layouts["docs/_layouts/"]:::source
        Includes["docs/_includes/"]:::source
        Guide["docs/_guide/"]:::source
        APIRef["docs/_api/"]:::source
        DocsPy["docs/main.py"]:::pipeline
        DocsRollup["docs/rollup.config.js"]:::pipeline
        DocsPkg["docs/package.json"]:::pipeline
        Site["Static docs site"]:::output
    end

    %% Demo Application
    subgraph "Demo App"
        DemoPage["demo/lit-element.html"]:::output
        DemoTS["src/demo/ts-element.ts"]:::source
    end

    %% Benchmark Pipeline
    subgraph "Benchmark Pipeline"
        BenchSrc["benchmarks/"]:::source
        Shack["benchmarks/shack/"]:::source
        Tachometer["benchmarks/tachometer.json"]:::pipeline
        ActionsBench[".github/workflows/benchmarks.yml"]:::external
    end

    %% Repository Metadata & CI
    RepoMeta["package.json<br/>tslint.json<br/>.github/CODEOWNERS"]:::source

    %% Flows
    Updating --> TS
    CSS --> TS
    Decorators --> TS
    LitElement --> TS
    TS --> Babel --> Rollup --> Dist
    Dist --> Publish --> Registry --> Consumers

    %% Test flow
    Dist --> TestsTS --> TestsRunner
    WCT --> TestsRunner
    ActionsTest --> TestsTS

    %% Docs flow
    DocsSrc & Layouts & Includes & Guide & APIRef --> DocsPy --> DocsRollup --> Site

    %% Demo flow
    Dist --> DemoPage
    DemoTS --> DemoPage

    %% Benchmark flow
    Dist --> BenchSrc --> Shack --> Tachometer
    ActionsBench --> BenchSrc

    %% Click Events
    click Updating "https://github.com/lit/lit-element/blob/master/src/lib/updating-element.ts"
    click CSS "https://github.com/lit/lit-element/blob/master/src/lib/css-tag.ts"
    click Decorators "https://github.com/lit/lit-element/blob/master/src/decorators.ts"
    click LitElement "https://github.com/lit/lit-element/blob/master/src/lit-element.ts"
    click TS "https://github.com/lit/lit-element/blob/master/tsconfig.json"
    click Babel "https://github.com/lit/lit-element/blob/master/.babelrc"
    click Rollup "https://github.com/lit/lit-element/blob/master/rollup.config.js"
    click TestsTS "https://github.com/lit/lit-element/tree/master/src/test/"
    click TestsRunner "https://github.com/lit/lit-element/blob/master/test/runner.html"
    click WCT "https://github.com/lit/lit-element/blob/master/wct.conf.json"
    click ActionsTest "https://github.com/lit/lit-element/blob/master/.github/workflows/tests.yml"
    click DocsSrc "https://github.com/lit/lit-element/tree/master/docs/"
    click Layouts "https://github.com/lit/lit-element/tree/master/docs/_layouts/"
    click Includes "https://github.com/lit/lit-element/tree/master/docs/_includes/"
    click Guide "https://github.com/lit/lit-element/tree/master/docs/_guide/"
    click APIRef "https://github.com/lit/lit-element/tree/master/docs/_api/"
    click DocsPy "https://github.com/lit/lit-element/blob/master/docs/main.py"
    click DocsRollup "https://github.com/lit/lit-element/blob/master/docs/rollup.config.js"
    click DocsPkg "https://github.com/lit/lit-element/blob/master/docs/package.json"
    click DemoPage "https://github.com/lit/lit-element/blob/master/demo/lit-element.html"
    click DemoTS "https://github.com/lit/lit-element/blob/master/src/demo/ts-element.ts"
    click BenchSrc "https://github.com/lit/lit-element/tree/master/benchmarks/"
    click Shack "https://github.com/lit/lit-element/tree/master/benchmarks/shack/"
    click Tachometer "https://github.com/lit/lit-element/blob/master/benchmarks/tachometer.json"
    click ActionsBench "https://github.com/lit/lit-element/blob/master/.github/workflows/benchmarks.yml"
    click RepoMeta "https://github.com/lit/lit-element/blob/master/package.json"

    %% Styles
    classDef source fill:#e0f7fa,stroke:#0288d1,color:#01579b
    classDef pipeline fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    classDef output fill:#fff3e0,stroke:#ef6c00,color:#e65100
    classDef external fill:#ffecb3,stroke:#f9a825,color:#e65100
```
