# salesforce/lwc architecture

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

- Interactive diagram: https://gitdiagram.com/salesforce/lwc
- Repository: https://github.com/salesforce/lwc

## Overview

LWC is a component compiler and runtime. The principal workflow is authoring component source, compiling JavaScript/templates/styles, then registering and rendering components through a browser or server runtime; browser rendering can hydrate existing markup. Runtime internals support component definitions, decorators, reactive state, and template execution. The README establishes the compiler/engine product, while the source index and excerpts show several engine relationships; less-documented compiler and renderer links are marked unverified or omitted.

Main entry points: [`packages/@lwc/engine-core/src/framework/main.ts`](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/main.ts) (Engine entry points), [`packages/@lwc/engine-dom/src/renderer.ts`](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-dom/src/renderer.ts) (Browser renderer), [`packages/@lwc/engine-core/src/framework/decorators/register.ts`](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/decorators/register.ts) (Decorator registration), [`packages/@lwc/compiler/src/transformers/transformer.ts`](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/compiler/src/transformers/transformer.ts) (LWC compiler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Compilation"]
  node_compiler["LWC compiler<br/>[transformer.ts]"]
  node_babel["Component transforms<br/>[component.ts]"]
end

subgraph group_runtime["Component Runtime"]
  node_engine_api["Engine entry points<br/>[main.ts]"]
  node_registration["Component registration<br/>[component.ts]"]
  node_definitions["Component definitions<br/>[def.ts]"]
  node_decorators["Decorator registration<br/>[register.ts]"]
  node_base_component["LightningElement base"]
  node_bridge["DOM bridge element"]
  node_reactivity["Reactive membrane<br/>[membrane.ts]"]
  node_mutation["Mutation tracking"]
  node_component_lifecycle["Component lifecycle<br/>[component.ts]"]
  node_vm["Component VM<br/>[vm.ts]"]
  node_wiring["Wire and context<br/>[wiring.ts]"]
end

subgraph group_rendering["Rendering"]
  node_template["Template runtime<br/>[template.ts]"]
  node_secure_template["Template registration<br/>[secure-template.ts]"]
  node_stylesheet["Stylesheet runtime<br/>[stylesheet.ts]"]
  node_dom_engine["Browser renderer<br/>[renderer.ts]"]
  node_server_engine["Server renderer"]
  node_hydration["DOM hydration<br/>[hydration.ts]"]
end

subgraph group_integrations["Platform Support"]
  node_shadow["Synthetic shadow<br/>[main.ts]"]
end

node_developer(("Component author"))
node_browser(("Browser DOM"))
node_server(("Server host"))

node_developer -->|"provides source"| node_compiler
node_compiler -.->|"transforms components"| node_babel
node_compiler -->|"targets compiled APIs"| node_engine_api
node_engine_api -->|"exports registration"| node_registration
node_engine_api -->|"exports definitions"| node_definitions
node_engine_api -->|"exports decorator registration"| node_decorators
node_engine_api -->|"exports VM APIs"| node_vm
node_engine_api -->|"exports template APIs"| node_template
node_engine_api -->|"exports template registration"| node_secure_template
node_registration -->|"reads decorator metadata"| node_decorators
node_definitions -->|"reads decorator metadata"| node_decorators
node_base_component -->|"schedules updates"| node_component_lifecycle
node_component_lifecycle -->|"observes component state"| node_mutation
node_component_lifecycle -->|"schedules rehydration"| node_vm
node_reactivity -->|"reports changes"| node_mutation
node_decorators -->|"registers wire support"| node_wiring
node_vm -.->|"executes template"| node_template
node_dom_engine -.->|"uses runtime APIs"| node_engine_api
node_server_engine -.->|"uses runtime APIs"| node_engine_api
node_dom_engine -.->|"renders into DOM"| node_browser
node_server_engine -.->|"renders markup"| node_server
node_hydration -.->|"hydrates DOM"| node_dom_engine
node_engine_api -->|"exports hydration"| node_hydration
node_shadow -.->|"patches shadow DOM"| node_browser
node_stylesheet -.->|"applies styles"| node_dom_engine

click node_compiler "https://github.com/salesforce/lwc/blob/master/packages/%40lwc/compiler/src/transformers/transformer.ts"
click node_babel "https://github.com/salesforce/lwc/blob/master/packages/%40lwc/babel-plugin-component/src/component.ts"
click node_engine_api "https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/main.ts"
click node_registration "https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/component.ts"
click node_definitions "https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/def.ts"
click node_decorators "https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/decorators/register.ts"
click node_base_component "https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/base-lightning-element.ts"
click node_bridge "https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/base-bridge-element.ts"
click node_reactivity "https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/membrane.ts"
click node_mutation "https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/mutation-tracker.ts"
click node_component_lifecycle "https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/component.ts"
click node_vm "https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/vm.ts"
click node_template "https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/template.ts"
click node_secure_template "https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/secure-template.ts"
click node_stylesheet "https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/stylesheet.ts"
click node_dom_engine "https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-dom/src/renderer.ts"
click node_server_engine "https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-server/src/apis/render-component.ts"
click node_hydration "https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/hydration.ts"
click node_wiring "https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/wiring/wiring.ts"
click node_shadow "https://github.com/salesforce/lwc/blob/master/packages/%40lwc/synthetic-shadow/src/polyfills/shadow-root/main.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_compiler,node_babel,node_browser toneBlue
class node_engine_api,node_registration,node_definitions,node_decorators,node_base_component,node_bridge,node_reactivity,node_mutation,node_component_lifecycle,node_vm,node_wiring toneAmber
class node_template,node_secure_template,node_stylesheet,node_dom_engine,node_server_engine,node_hydration,node_server toneMint
class node_shadow toneRose
class node_developer toneIndigo
```

## Components

### Compilation

- [LWC compiler](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/compiler/src/transformers/transformer.ts): `packages/@lwc/compiler/src/transformers/transformer.ts`
- [Component transforms](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/babel-plugin-component/src/component.ts): `packages/@lwc/babel-plugin-component/src/component.ts`

### Component Runtime

- [Engine entry points](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/main.ts): `packages/@lwc/engine-core/src/framework/main.ts`
- [Component registration](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/component.ts): `packages/@lwc/engine-core/src/framework/component.ts`
- [Component definitions](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/def.ts): `packages/@lwc/engine-core/src/framework/def.ts`
- [Decorator registration](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/decorators/register.ts): `packages/@lwc/engine-core/src/framework/decorators/register.ts`
- [LightningElement base](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/base-lightning-element.ts): `packages/@lwc/engine-core/src/framework/base-lightning-element.ts`
- [DOM bridge element](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/base-bridge-element.ts): `packages/@lwc/engine-core/src/framework/base-bridge-element.ts`
- [Reactive membrane](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/membrane.ts): `packages/@lwc/engine-core/src/framework/membrane.ts`
- [Mutation tracking](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/mutation-tracker.ts): `packages/@lwc/engine-core/src/framework/mutation-tracker.ts`
- [Component lifecycle](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/component.ts): `packages/@lwc/engine-core/src/framework/component.ts`
- [Component VM](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/vm.ts): `packages/@lwc/engine-core/src/framework/vm.ts`
- [Wire and context](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/wiring/wiring.ts): `packages/@lwc/engine-core/src/framework/wiring/wiring.ts`

### Rendering

- [Template runtime](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/template.ts): `packages/@lwc/engine-core/src/framework/template.ts`
- [Template registration](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/secure-template.ts): `packages/@lwc/engine-core/src/framework/secure-template.ts`
- [Stylesheet runtime](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/stylesheet.ts): `packages/@lwc/engine-core/src/framework/stylesheet.ts`
- [Browser renderer](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-dom/src/renderer.ts): `packages/@lwc/engine-dom/src/renderer.ts`
- [Server renderer](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-server/src/apis/render-component.ts): `packages/@lwc/engine-server/src/apis/render-component.ts`
- [DOM hydration](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/engine-core/src/framework/hydration.ts): `packages/@lwc/engine-core/src/framework/hydration.ts`

### Platform Support

- [Synthetic shadow](https://github.com/salesforce/lwc/blob/master/packages/%40lwc/synthetic-shadow/src/polyfills/shadow-root/main.ts): `packages/@lwc/synthetic-shadow/src/polyfills/shadow-root/main.ts`

### Other components

- **Component author**
- **Browser DOM**
- **Server host**

## Connections

- Component author → LWC compiler: provides source (evidence: `README.md`)
- LWC compiler → Component transforms: transforms components
- LWC compiler → Engine entry points: targets compiled APIs (evidence: `packages/@lwc/engine-core/src/framework/main.ts`)
- Engine entry points → Component registration: exports registration (evidence: `packages/@lwc/engine-core/src/framework/main.ts`)
- Engine entry points → Component definitions: exports definitions (evidence: `packages/@lwc/engine-core/src/framework/main.ts`)
- Engine entry points → Decorator registration: exports decorator registration (evidence: `packages/@lwc/engine-core/src/framework/main.ts`)
- Engine entry points → Component VM: exports VM APIs (evidence: `packages/@lwc/engine-core/src/framework/main.ts`)
- Engine entry points → Template runtime: exports template APIs (evidence: `packages/@lwc/engine-core/src/framework/main.ts`)
- Engine entry points → Template registration: exports template registration (evidence: `packages/@lwc/engine-core/src/framework/main.ts`)
- Component registration → Decorator registration: reads decorator metadata (evidence: `packages/@lwc/engine-core/src/framework/decorators/register.ts`)
- Component definitions → Decorator registration: reads decorator metadata (evidence: `packages/@lwc/engine-core/src/framework/def.ts`)
- LightningElement base → Component lifecycle: schedules updates (evidence: `packages/@lwc/engine-core/src/framework/base-lightning-element.ts`)
- Component lifecycle → Mutation tracking: observes component state (evidence: `packages/@lwc/engine-core/src/framework/component.ts`)
- Component lifecycle → Component VM: schedules rehydration (evidence: `packages/@lwc/engine-core/src/framework/component.ts`)
- Reactive membrane → Mutation tracking: reports changes (evidence: `packages/@lwc/engine-core/src/framework/membrane.ts`)
- Decorator registration → Wire and context: registers wire support (evidence: `packages/@lwc/engine-core/src/framework/decorators/register.ts`)
- Component VM → Template runtime: executes template
- Browser renderer → Engine entry points: uses runtime APIs
- Server renderer → Engine entry points: uses runtime APIs
- Browser renderer → Browser DOM: renders into DOM
- Server renderer → Server host: renders markup
- DOM hydration → Browser renderer: hydrates DOM
- Engine entry points → DOM hydration: exports hydration (evidence: `packages/@lwc/engine-core/src/framework/main.ts`)
- Synthetic shadow → Browser DOM: patches shadow DOM
- Stylesheet runtime → Browser renderer: applies styles
