# a-h/templ architecture

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

- Interactive diagram: https://gitdiagram.com/a-h/templ
- Repository: https://github.com/a-h/templ

## Overview

##### Project Type & Purpose
- This is a compiler‐style developer tool: an HTML templating language for Go (“templ”).
- It provides a CLI (`cmd/templ`) with subcommands (`generate`, `fmt`, `lsp`, etc.), a parser (`parser/v2`), a generator (`generator/…`), a runtime library (`runtime/…`), tooling support (LSP server in `lsp/jsonrpc2` and `lsp/protocol`), plus documentation and examples.

##### File Structure Analysis
- Top level:
- `cmd/templ` – the CLI entry point with multiple subcommands.
- `parser/v2` – full template parser producing an AST.
- `generator` – code generator that turns AST + templates into Go source.
- `runtime` – runtime library used by generated code for rendering, streaming, watch mode.
- `internal` – shared internal utilities (formatting, imports, HTML finding, lazy loading).
- `lsp` – JSON-RPC and LSP protocol implementation supporting editor integration.
- `docs` & `storybook` – documentation site (Docusaurus) and storybook examples.
- `examples` & `benchmarks` – sample apps & performance tests.

##### Key README Insights
- Core user flows:
- `templ generate` transforms `.templ` files into `_templ.go` files.
- `templ fmt` applies code formatting to Go & templ files.
- `templ lsp` acts as an LSP server for IDE support.
- CI/CD and release uses GitHub Actions, goreleaser, version management.

##### Main Components & Interactions
a. CLI Layer (`cmd/templ/…`)
- Subcommands:
- `generatecmd` reads templates, calls Parser → Generator → writes Go code.
- `fmtcmd` invokes Parser → internal/format → writes formatted templates.
- `lspcmd` sets up JSON-RPC server for editor requests, uses parser + generator on‐demand.
- Dependencies: parser/v2, generator, internal packages, lsp packages.
b. Parser (`parser/v2`)
- Tokenizes & parses templ syntax into an in‐memory AST.
c. Generator (`generator`)
- Walks AST, emits Go source files (`*_templ.go`).
- Integrated with sourcemap support (`parser/v2/sourcemap.go`) for LSP & debug.
d. Runtime Library (`runtime`)
- Provides buffers, builders, streaming, CSS/JS management, watch mode for live reload.
- Bundled into generated Go code or invoked at runtime.
e. LSP Server (`lsp/jsonrpc2` + `lsp/protocol`)
- Implements the Language Server Protocol over JSON-RPC for IDE features (go to definition, diagnostics).
f. Internal Utilities (`internal/…`)
- Formatting rules, import processing, HTML utilities, lazy loading packages, skipping directories.
g. Documentation Site (`docs`/Docusaurus)
- Static site generator using Node/NPM, shows user docs, guides, examples.
h. Examples & Benchmarks
- Serve as integration tests/workflows illustrating real‐world use cases.

##### Architectural Patterns & Design Principles
- Separation of concerns: parsing, code generation, formatting, runtime, CLI, LSP are isolated modules.
- Compiler pipeline:
1. Parse
2. AST transformations
3. Code generation
4. Format & write output
- Plugin-style CLI: each subcommand is a separate Go package under `cmd/templ`.
- Library + Executable: core logic in reusable packages, thin CLI wrappers.

- Parser (`parser/v2`)
- Generator (`generator`)
- Runtime (`runtime`)
- LSP Server (`lsp/jsonrpc2` & `lsp/protocol`)
- Internal Utilities (`internal/*`)
- Documentation Site (`docs`)
- Examples & Benchmarks
- Interactions:
- Technologies: label Go modules, JSON-RPC, Docusaurus (Node), GitHub Actions, goreleaser.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and external
    User["User"]:::external
    IDE["IDE"]:::external
    CI["CI Server"]:::external

    %% CLI Layer
    subgraph "CLI Layer" 
        direction TB
        GenerateCMD["generatecmd"]:::tooling
        FmtCMD["fmtcmd"]:::tooling
        LSPCMD["lspcmd"]:::tooling
        InfoCMD["infocmd"]:::tooling
        VisualizeCMD["visualize"]:::tooling
    end

    %% Compiler Pipeline
    subgraph "Compiler Pipeline"
        direction TB
        Parser["parser/v2"]:::compiler
        AST["AST"]:::compiler
        Generator["generator"]:::compiler
        FS["Generated Files"]:::storage
        InternalFmt["internal/format"]:::tooling
    end

    %% Runtime Library
    subgraph "Runtime Library"
        direction TB
        Runtime["runtime"]:::runtime
    end

    %% LSP Server
    subgraph "LSP Server"
        direction TB
        JSONRPC["lsp/jsonrpc2"]:::tooling
        Protocol["lsp/protocol"]:::tooling
        URI["lsp/uri"]:::tooling
        XContext["lsp/xcontext"]:::tooling
    end

    %% Docs & Examples
    subgraph "Documentation & Examples"
        direction TB
        Docs["docs"]:::docs
        Storybook["storybook"]:::docs
        Examples["examples"]:::docs
        Benchmarks["benchmarks"]:::docs
    end

    %% CI/CD
    subgraph "CI/CD & Release"
        direction TB
        GitHub[".github"]:::ci
        Goreleaser[".goreleaser.yaml"]:::ci
    end

    %% Connections
    User -->|"runs templ"| GenerateCMD
    User -->|"runs templ"| FmtCMD
    User -->|"runs templ"| LSPCMD
    GenerateCMD -->|"reads .templ files"| Parser
    Parser -->|"emits AST"| AST
    AST -->|"generates Go code"| Generator
    Generator -->|"writes _templ.go"| FS
    FS -->|"uses runtime lib"| Runtime

    FmtCMD -->|"invokes parser"| Parser
    Parser -->|"parses templates"| AST
    AST -->|"formats"| InternalFmt
    InternalFmt -->|"writes formatted files"| FS

    LSPCMD -->|"starts server"| JSONRPC
    JSONRPC -->|"uses protocol defs"| Protocol
    JSONRPC -->|"resolves URIs"| URI
    JSONRPC -->|"manages context"| XContext
    JSONRPC <-->|"JSON-RPC"| IDE
    JSONRPC -->|"parses/templates"| Parser

    User -->|"views docs"| Docs
    User -->|"views examples"| Storybook
    User -->|"runs sample apps"| Examples
    User -->|"runs benchmarks"| Benchmarks

    CI -->|"CI workflows"| GitHub
    CI -->|"release builds"| Goreleaser

    %% Click events
    click GenerateCMD "https://github.com/a-h/templ/tree/main/cmd/templ/generatecmd"
    click FmtCMD "https://github.com/a-h/templ/tree/main/cmd/templ/fmtcmd"
    click LSPCMD "https://github.com/a-h/templ/tree/main/cmd/templ/lspcmd"
    click InfoCMD "https://github.com/a-h/templ/tree/main/cmd/templ/infocmd"
    click VisualizeCMD "https://github.com/a-h/templ/tree/main/cmd/templ/visualize"
    click Parser "https://github.com/a-h/templ/tree/main/parser/v2"
    click Generator "https://github.com/a-h/templ/tree/main/generator"
    click Runtime "https://github.com/a-h/templ/tree/main/runtime"
    click InternalFmt "https://github.com/a-h/templ/tree/main/internal"
    click JSONRPC "https://github.com/a-h/templ/tree/main/lsp/jsonrpc2"
    click Protocol "https://github.com/a-h/templ/tree/main/lsp/protocol"
    click URI "https://github.com/a-h/templ/tree/main/lsp/uri"
    click XContext "https://github.com/a-h/templ/tree/main/lsp/xcontext"
    click Docs "https://github.com/a-h/templ/tree/main/docs"
    click Storybook "https://github.com/a-h/templ/tree/main/storybook"
    click Examples "https://github.com/a-h/templ/tree/main/examples"
    click Benchmarks "https://github.com/a-h/templ/tree/main/benchmarks"
    click GitHub "https://github.com/a-h/templ/blob/main/.github"
    click Goreleaser "https://github.com/a-h/templ/blob/main/.goreleaser.yaml"

    %% Styles
    classDef compiler fill:#cce5ff,stroke:#004085,color:#004085;
    classDef runtime fill:#d4edda,stroke:#155724,color:#155724;
    classDef tooling fill:#fff3cd,stroke:#856404,color:#856404;
    classDef docs fill:#ffe5b4,stroke:#cc8400,color:#cc8400;
    classDef ci fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef storage fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef external fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
```
