# alpinejs/alpine architecture

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

- Interactive diagram: https://gitdiagram.com/alpinejs/alpine
- Repository: https://github.com/alpinejs/alpine

## Overview

Alpine.js is a lightweight, HTML-driven reactive UI framework, accompanied here by plugins, a CSP-safe evaluator, and accessible UI components. The primary workflow starts with markup in a browser: Alpine initializes the page, observes DOM changes, registers directives, evaluates their expressions against scoped data, and updates behavior and presentation reactively. Plugins add optional browser behaviors; the UI package provides higher-level components. Edges are limited to relationships shown in excerpts, source-index references, or README descriptions; unsampled modules are represented only where the tree or README supports their role.

Main entry points: [`packages/alpinejs/src/alpine.js`](https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/alpine.js) (Alpine API), [`packages/alpinejs/src/index.js`](https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/index.js) (Core setup), [`packages/alpinejs/src/directives.js`](https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/directives.js) (Directive system), [`packages/alpinejs/src/mutation.js`](https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/mutation.js) (DOM mutation observer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Alpine core"]
  node_alpine["Alpine API<br/>[alpine.js]"]
  node_entry["Core setup<br/>[index.js]"]
  node_directives["Directive system<br/>[directives.js]"]
  node_builtins["Built-in directives<br/>[index.js]"]
  node_evaluator["Expression evaluator<br/>[evaluator.js]"]
  node_scope["Data scopes<br/>[scope.js]"]
  node_magics["Magic properties<br/>[magics.js]"]
  node_reactivity["Reactivity engine<br/>[reactivity.js]"]
end

subgraph group_runtime["DOM runtime"]
  node_lifecycle["Tree lifecycle<br/>[lifecycle.js]"]
  node_mutation["DOM mutation observer<br/>[mutation.js]"]
  node_clone["DOM cloning<br/>[clone.js]"]
  node_transition["Transitions<br/>[x-transition.js]"]
  node_scheduler["Job scheduler<br/>[scheduler.js]"]
end

subgraph group_plugins["Alpine plugins"]
  node_plugins["Browser behavior plugins"]
end

subgraph group_csp["CSP evaluator"]
  node_parser["CSP expression parser<br/>[parser.js]"]
  node_csp_eval["CSP evaluator<br/>[evaluator.js]"]
end

subgraph group_ui["UI components"]
  node_ui_context["List context<br/>[list-context.js]"]
  node_ui_controls["Accessible controls"]
end

node_markup["HTML markup"]
node_browser(("Browser user"))

node_browser -->|"interacts with"| node_markup
node_markup -->|"initializes"| node_entry
node_entry -->|"imports core"| node_alpine
node_entry -->|"registers"| node_builtins
node_entry -->|"configures"| node_evaluator
node_entry -->|"configures"| node_reactivity
node_alpine -->|"exposes"| node_directives
node_alpine -->|"exposes"| node_lifecycle
node_alpine -->|"exposes"| node_mutation
node_alpine -->|"exposes"| node_scope
node_directives -->|"evaluates with"| node_evaluator
node_directives -->|"binds effects"| node_reactivity
node_directives -->|"tracks removal"| node_mutation
node_evaluator -->|"reads scopes"| node_scope
node_evaluator -->|"injects"| node_magics
node_magics -->|"gets utilities"| node_directives
node_magics -->|"cleans up on removal"| node_mutation
node_mutation -->|"queues jobs"| node_scheduler
node_transition -->|"mutates DOM through"| node_mutation
node_clone -->|"uses lifecycle"| node_lifecycle
node_plugins -.->|"adds directives"| node_markup
node_csp_eval -->|"parses expressions with"| node_parser
node_ui_controls -->|"uses list state"| node_ui_context
node_ui_controls -->|"uses list state"| node_ui_context

click node_alpine "https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/alpine.js"
click node_entry "https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/index.js"
click node_directives "https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/directives.js"
click node_builtins "https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/directives/index.js"
click node_evaluator "https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/evaluator.js"
click node_scope "https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/scope.js"
click node_magics "https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/magics.js"
click node_reactivity "https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/reactivity.js"
click node_lifecycle "https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/lifecycle.js"
click node_mutation "https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/mutation.js"
click node_clone "https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/clone.js"
click node_transition "https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/directives/x-transition.js"
click node_scheduler "https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/scheduler.js"
click node_plugins "https://github.com/alpinejs/alpine/tree/main/packages"
click node_parser "https://github.com/alpinejs/alpine/blob/main/packages/csp/src/parser.js"
click node_csp_eval "https://github.com/alpinejs/alpine/blob/main/packages/csp/src/evaluator.js"
click node_ui_context "https://github.com/alpinejs/alpine/blob/main/packages/ui/src/list-context.js"
click node_ui_controls "https://github.com/alpinejs/alpine/tree/main/packages/ui/src"

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_alpine,node_entry,node_directives,node_builtins,node_evaluator,node_scope,node_magics,node_reactivity,node_browser toneBlue
class node_lifecycle,node_mutation,node_clone,node_transition,node_scheduler toneAmber
class node_plugins toneMint
class node_parser,node_csp_eval toneRose
class node_ui_context,node_ui_controls,node_markup toneIndigo
```

## Components

### Alpine core

- [Alpine API](https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/alpine.js): `packages/alpinejs/src/alpine.js`
- [Core setup](https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/index.js): `packages/alpinejs/src/index.js`
- [Directive system](https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/directives.js): `packages/alpinejs/src/directives.js`
- [Built-in directives](https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/directives/index.js): `packages/alpinejs/src/directives/index.js`
- [Expression evaluator](https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/evaluator.js): `packages/alpinejs/src/evaluator.js`
- [Data scopes](https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/scope.js): `packages/alpinejs/src/scope.js`
- [Magic properties](https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/magics.js): `packages/alpinejs/src/magics.js`
- [Reactivity engine](https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/reactivity.js): `packages/alpinejs/src/reactivity.js`

### DOM runtime

- [Tree lifecycle](https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/lifecycle.js): `packages/alpinejs/src/lifecycle.js`
- [DOM mutation observer](https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/mutation.js): `packages/alpinejs/src/mutation.js`
- [DOM cloning](https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/clone.js): `packages/alpinejs/src/clone.js`
- [Transitions](https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/directives/x-transition.js): `packages/alpinejs/src/directives/x-transition.js`
- [Job scheduler](https://github.com/alpinejs/alpine/blob/main/packages/alpinejs/src/scheduler.js): `packages/alpinejs/src/scheduler.js`

### Alpine plugins

- [Browser behavior plugins](https://github.com/alpinejs/alpine/tree/main/packages): `packages`

### CSP evaluator

- [CSP expression parser](https://github.com/alpinejs/alpine/blob/main/packages/csp/src/parser.js): `packages/csp/src/parser.js`
- [CSP evaluator](https://github.com/alpinejs/alpine/blob/main/packages/csp/src/evaluator.js): `packages/csp/src/evaluator.js`

### UI components

- [List context](https://github.com/alpinejs/alpine/blob/main/packages/ui/src/list-context.js): `packages/ui/src/list-context.js`
- [Accessible controls](https://github.com/alpinejs/alpine/tree/main/packages/ui/src): `packages/ui/src`

### Other components

- **HTML markup**
- **Browser user**

## Connections

- Browser user → HTML markup: interacts with
- HTML markup → Core setup: initializes
- Core setup → Alpine API: imports core (evidence: `packages/alpinejs/src/index.js`)
- Core setup → Built-in directives: registers (evidence: `packages/alpinejs/src/index.js`)
- Core setup → Expression evaluator: configures (evidence: `packages/alpinejs/src/index.js`)
- Core setup → Reactivity engine: configures (evidence: `packages/alpinejs/src/index.js`)
- Alpine API → Directive system: exposes (evidence: `packages/alpinejs/src/alpine.js`)
- Alpine API → Tree lifecycle: exposes (evidence: `packages/alpinejs/src/alpine.js`)
- Alpine API → DOM mutation observer: exposes (evidence: `packages/alpinejs/src/alpine.js`)
- Alpine API → Data scopes: exposes (evidence: `packages/alpinejs/src/alpine.js`)
- Directive system → Expression evaluator: evaluates with (evidence: `packages/alpinejs/src/directives.js`)
- Directive system → Reactivity engine: binds effects (evidence: `packages/alpinejs/src/directives.js`)
- Directive system → DOM mutation observer: tracks removal (evidence: `packages/alpinejs/src/directives.js`)
- Expression evaluator → Data scopes: reads scopes (evidence: `packages/alpinejs/src/evaluator.js`)
- Expression evaluator → Magic properties: injects (evidence: `packages/alpinejs/src/evaluator.js`)
- Magic properties → Directive system: gets utilities (evidence: `packages/alpinejs/src/magics.js`)
- Magic properties → DOM mutation observer: cleans up on removal (evidence: `packages/alpinejs/src/magics.js`)
- DOM mutation observer → Job scheduler: queues jobs (evidence: `packages/alpinejs/src/mutation.js`)
- Transitions → DOM mutation observer: mutates DOM through (evidence: `packages/alpinejs/src/directives/x-transition.js`)
- DOM cloning → Tree lifecycle: uses lifecycle (evidence: `packages/alpinejs/src/clone.js`)
- Browser behavior plugins → HTML markup: adds directives
- CSP evaluator → CSP expression parser: parses expressions with (evidence: `packages/csp/src/evaluator.js`)
- Accessible controls → List context: uses list state (evidence: `packages/ui/src/combobox.js`)
- Accessible controls → List context: uses list state (evidence: `packages/ui/src/listbox.js`)
