# stenciljs/core architecture

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

- Interactive diagram: https://gitdiagram.com/stenciljs/core
- Repository: https://github.com/stenciljs/core

## Overview

Stencil turns TypeScript/JSX component definitions into framework-independent Web Components. The principal workflow is project authors invoking the CLI to compile component metadata and source into distributable outputs, which browser applications load and render through Stencil’s runtime. Separate branches support development serving and hot updates, server-side hydration and prerendering, and project testing. The graph reflects the README’s product description and the supplied source/tree; several subsystem links are based on the documented product workflow because their implementation was not sampled.

Main entry points: [`src/compiler/compiler.ts`](https://github.com/stenciljs/core/blob/main/src/compiler/compiler.ts) (Compiler), [`src/compiler/output-targets/index.ts`](https://github.com/stenciljs/core/blob/main/src/compiler/output-targets/index.ts) (Output targets), [`src/cli/task-build.ts`](https://github.com/stenciljs/core/blob/main/src/cli/task-build.ts) (Build task), [`src/cli/index.ts`](https://github.com/stenciljs/core/blob/main/src/cli/index.ts) (Stencil CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Project build"]
  node_cli["Stencil CLI<br/>[index.ts]"]
  node_buildtask["Build task<br/>[task-build.ts]"]
  node_config["Config loading<br/>[load-config.ts]"]
end

subgraph group_compile["Compilation"]
  node_compiler["Compiler<br/>[compiler.ts]"]
  node_transpile["TypeScript transforms<br/>[transpile.ts]"]
  node_metadata["Component metadata<br/>[component.ts]"]
  node_bundler["Module bundling"]
  node_componentgraph["Component graph<br/>[component-graph.ts]"]
  node_outputs["Output targets<br/>[index.ts]"]
  node_lazyoutput["Lazy component output<br/>[lazy-output.ts]"]
  node_hydrateoutput["Hydrate script output<br/>[index.ts]"]
  node_types["Type generation<br/>[generate-types.ts]"]
end

subgraph group_runtime["Component runtime"]
  node_loader["Lazy module loader"]
  node_bootstrap["Runtime bootstrap<br/>[bootstrap-lazy.ts]"]
  node_componentruntime["Component lifecycle"]
  node_render["DOM rendering<br/>[vdom-render.ts]"]
  node_hydrate["Hydration runtime<br/>[hydrate-app.ts]"]
end

subgraph group_serve["Serving and rendering"]
  node_devserver["Development server<br/>[index.ts]"]
  node_devclient["Live-update client"]
  node_prerender["Prerender worker"]
end

subgraph group_tools["Project tools"]
  node_testing["Testing platform"]
  node_mockdoc["Mock DOM<br/>[index.ts]"]
end

node_author(("Project author"))
node_artifacts["Web Component artifacts"]
node_browser(("Browser application"))

node_author -->|"invokes"| node_cli
node_cli -->|"dispatches"| node_buildtask
node_buildtask -->|"loads config"| node_config
node_buildtask -->|"requests build"| node_compiler
node_compiler -->|"transforms source"| node_transpile
node_compiler -->|"extracts metadata"| node_metadata
node_compiler -->|"resolves dependencies"| node_componentgraph
node_compiler -->|"bundles modules"| node_bundler
node_compiler -->|"generates targets"| node_outputs
node_outputs -->|"writes lazy format"| node_lazyoutput
node_outputs -->|"writes hydrate format"| node_hydrateoutput
node_compiler -->|"generates types"| node_types
node_outputs -->|"writes artifacts"| node_artifacts
node_artifacts -->|"loads components"| node_browser
node_browser -->|"requests module"| node_loader
node_loader -->|"loads bundle"| node_bootstrap
node_bootstrap -->|"initializes components"| node_componentruntime
node_componentruntime -->|"updates DOM"| node_render
node_browser -.->|"requests app"| node_devserver
node_devserver -->|"sends build updates"| node_devclient
node_devclient -->|"reloads or updates"| node_browser
node_compiler -.->|"dispatches prerender"| node_prerender
node_prerender -->|"hydrates document"| node_hydrate
node_testing -->|"uses mock DOM"| node_mockdoc

click node_cli "https://github.com/stenciljs/core/blob/main/src/cli/index.ts"
click node_buildtask "https://github.com/stenciljs/core/blob/main/src/cli/task-build.ts"
click node_config "https://github.com/stenciljs/core/blob/main/src/compiler/config/load-config.ts"
click node_compiler "https://github.com/stenciljs/core/blob/main/src/compiler/compiler.ts"
click node_transpile "https://github.com/stenciljs/core/blob/main/src/compiler/transpile.ts"
click node_metadata "https://github.com/stenciljs/core/blob/main/src/compiler/transformers/static-to-meta/component.ts"
click node_bundler "https://github.com/stenciljs/core/blob/main/src/compiler/bundle/bundle-interface.ts"
click node_componentgraph "https://github.com/stenciljs/core/blob/main/src/compiler/entries/component-graph.ts"
click node_outputs "https://github.com/stenciljs/core/blob/main/src/compiler/output-targets/index.ts"
click node_lazyoutput "https://github.com/stenciljs/core/blob/main/src/compiler/output-targets/dist-lazy/lazy-output.ts"
click node_hydrateoutput "https://github.com/stenciljs/core/blob/main/src/compiler/output-targets/dist-hydrate-script/index.ts"
click node_types "https://github.com/stenciljs/core/blob/main/src/compiler/types/generate-types.ts"
click node_loader "https://github.com/stenciljs/core/blob/main/src/client/client-load-module.ts"
click node_bootstrap "https://github.com/stenciljs/core/blob/main/src/runtime/bootstrap-lazy.ts"
click node_componentruntime "https://github.com/stenciljs/core/blob/main/src/runtime/initialize-component.ts"
click node_render "https://github.com/stenciljs/core/blob/main/src/runtime/vdom/vdom-render.ts"
click node_hydrate "https://github.com/stenciljs/core/blob/main/src/hydrate/platform/hydrate-app.ts"
click node_devserver "https://github.com/stenciljs/core/blob/main/src/dev-server/index.ts"
click node_devclient "https://github.com/stenciljs/core/blob/main/src/dev-server/dev-server-client/client-web-socket.ts"
click node_prerender "https://github.com/stenciljs/core/blob/main/src/compiler/prerender/prerender-worker.ts"
click node_testing "https://github.com/stenciljs/core/blob/main/src/testing/platform/testing-platform.ts"
click node_mockdoc "https://github.com/stenciljs/core/blob/main/src/mock-doc/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_buildtask,node_config,node_browser toneBlue
class node_compiler,node_transpile,node_metadata,node_bundler,node_componentgraph,node_outputs,node_lazyoutput,node_hydrateoutput,node_types toneAmber
class node_loader,node_bootstrap,node_componentruntime,node_render,node_hydrate toneMint
class node_devserver,node_devclient,node_prerender toneRose
class node_testing,node_mockdoc,node_author,node_artifacts toneIndigo
```

## Components

### Project build

- [Stencil CLI](https://github.com/stenciljs/core/blob/main/src/cli/index.ts): `src/cli/index.ts`
- [Build task](https://github.com/stenciljs/core/blob/main/src/cli/task-build.ts): `src/cli/task-build.ts`
- [Config loading](https://github.com/stenciljs/core/blob/main/src/compiler/config/load-config.ts): `src/compiler/config/load-config.ts`

### Compilation

- [Compiler](https://github.com/stenciljs/core/blob/main/src/compiler/compiler.ts): `src/compiler/compiler.ts`
- [TypeScript transforms](https://github.com/stenciljs/core/blob/main/src/compiler/transpile.ts): `src/compiler/transpile.ts`
- [Component metadata](https://github.com/stenciljs/core/blob/main/src/compiler/transformers/static-to-meta/component.ts): `src/compiler/transformers/static-to-meta/component.ts`
- [Module bundling](https://github.com/stenciljs/core/blob/main/src/compiler/bundle/bundle-interface.ts): `src/compiler/bundle/bundle-interface.ts`
- [Component graph](https://github.com/stenciljs/core/blob/main/src/compiler/entries/component-graph.ts): `src/compiler/entries/component-graph.ts`
- [Output targets](https://github.com/stenciljs/core/blob/main/src/compiler/output-targets/index.ts): `src/compiler/output-targets/index.ts`
- [Lazy component output](https://github.com/stenciljs/core/blob/main/src/compiler/output-targets/dist-lazy/lazy-output.ts): `src/compiler/output-targets/dist-lazy/lazy-output.ts`
- [Hydrate script output](https://github.com/stenciljs/core/blob/main/src/compiler/output-targets/dist-hydrate-script/index.ts): `src/compiler/output-targets/dist-hydrate-script/index.ts`
- [Type generation](https://github.com/stenciljs/core/blob/main/src/compiler/types/generate-types.ts): `src/compiler/types/generate-types.ts`

### Component runtime

- [Lazy module loader](https://github.com/stenciljs/core/blob/main/src/client/client-load-module.ts): `src/client/client-load-module.ts`
- [Runtime bootstrap](https://github.com/stenciljs/core/blob/main/src/runtime/bootstrap-lazy.ts): `src/runtime/bootstrap-lazy.ts`
- [Component lifecycle](https://github.com/stenciljs/core/blob/main/src/runtime/initialize-component.ts): `src/runtime/initialize-component.ts`
- [DOM rendering](https://github.com/stenciljs/core/blob/main/src/runtime/vdom/vdom-render.ts): `src/runtime/vdom/vdom-render.ts`
- [Hydration runtime](https://github.com/stenciljs/core/blob/main/src/hydrate/platform/hydrate-app.ts): `src/hydrate/platform/hydrate-app.ts`

### Serving and rendering

- [Development server](https://github.com/stenciljs/core/blob/main/src/dev-server/index.ts): `src/dev-server/index.ts`
- [Live-update client](https://github.com/stenciljs/core/blob/main/src/dev-server/dev-server-client/client-web-socket.ts): `src/dev-server/dev-server-client/client-web-socket.ts`
- [Prerender worker](https://github.com/stenciljs/core/blob/main/src/compiler/prerender/prerender-worker.ts): `src/compiler/prerender/prerender-worker.ts`

### Project tools

- [Testing platform](https://github.com/stenciljs/core/blob/main/src/testing/platform/testing-platform.ts): `src/testing/platform/testing-platform.ts`
- [Mock DOM](https://github.com/stenciljs/core/blob/main/src/mock-doc/index.ts): `src/mock-doc/index.ts`

### Other components

- **Project author**
- **Web Component artifacts**
- **Browser application**

## Connections

- Project author → Stencil CLI: invokes
- Stencil CLI → Build task: dispatches
- Build task → Config loading: loads config
- Build task → Compiler: requests build
- Compiler → TypeScript transforms: transforms source
- Compiler → Component metadata: extracts metadata
- Compiler → Component graph: resolves dependencies
- Compiler → Module bundling: bundles modules
- Compiler → Output targets: generates targets
- Output targets → Lazy component output: writes lazy format
- Output targets → Hydrate script output: writes hydrate format
- Compiler → Type generation: generates types
- Output targets → Web Component artifacts: writes artifacts
- Web Component artifacts → Browser application: loads components
- Browser application → Lazy module loader: requests module
- Lazy module loader → Runtime bootstrap: loads bundle
- Runtime bootstrap → Component lifecycle: initializes components
- Component lifecycle → DOM rendering: updates DOM
- Browser application → Development server: requests app
- Development server → Live-update client: sends build updates
- Live-update client → Browser application: reloads or updates
- Compiler → Prerender worker: dispatches prerender
- Prerender worker → Hydration runtime: hydrates document
- Testing platform → Mock DOM: uses mock DOM