# mjmlio/mjml architecture

> Architecture diagram of the GitHub repository mjmlio/mjml, 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/mjmlio/mjml
- Repository: https://github.com/mjmlio/mjml

## Overview

MJML is a markup language and compiler for responsive email HTML. The main workflow accepts MJML, parses it into a tree, validates and renders components, then returns or writes HTML; the CLI adds file, stream, watch, and output modes. The graph also preserves the standard component library and configuration/preset capabilities. Some subsystem links are documented or indexed imports; unsampled component and validator internals are represented at their existing package directories, without asserting unshown call paths.

Main entry points: [`packages/mjml-cli/src/client.js`](https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/src/client.js) (CLI orchestration), [`packages/mjml-core/src/index.js`](https://github.com/mjmlio/mjml/blob/master/packages/mjml-core/src/index.js) (HTML compiler), [`packages/mjml-cli/src/commands/watchFiles.js`](https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/src/commands/watchFiles.js) (Watch mode), [`packages/mjml-parser-xml/src/index.js`](https://github.com/mjmlio/mjml/blob/master/packages/mjml-parser-xml/src/index.js) (XML parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs and CLI"]
  node_cli["CLI orchestration<br/>[client.js]"]
  node_file_read["File input<br/>[readFile.js]"]
  node_watch["Watch mode<br/>[watchFiles.js]"]
  node_file_context["Include tracking<br/>[fileContext.js]"]
  node_file_output["File output<br/>[outputToFile.js]"]
  node_console_output["Console output<br/>[outputToConsole.js]"]
  node_stream_input["Stream input<br/>[readStream.js]"]
end

subgraph group_engine["Parsing and rendering"]
  node_parser["XML parser<br/>[index.js]"]
  node_tree_cleanup["Tree cleanup<br/>[cleanNode.js]"]
  node_core["HTML compiler<br/>[index.js]"]
  node_component_runtime["Component runtime<br/>[createComponent.js]"]
  node_core_helpers["Rendering helpers"]
end

subgraph group_components["Email components"]
  node_standard_components["Standard components"]
  node_component_preset["Core preset"]
end

subgraph group_validation["Validation and config"]
  node_validator["MJML validator"]
  node_config["MJML configuration<br/>[mjmlconfig.js]"]
end

node_author(("Template author"))
node_html["Responsive HTML"]

node_author -->|"supplies input"| node_cli
node_author -->|"compiles with"| node_core
node_cli -->|"reads files"| node_file_read
node_cli -->|"reads stream"| node_stream_input
node_cli -->|"starts watch"| node_watch
node_watch -->|"reads changes"| node_file_read
node_watch -->|"tracks includes"| node_file_context
node_watch -->|"compiles changes"| node_core
node_watch -->|"writes results"| node_file_output
node_cli -->|"parses input"| node_parser
node_cli -->|"renders input"| node_core
node_cli -->|"validates input"| node_validator
node_cli -->|"loads preset"| node_component_preset
node_cli -->|"writes HTML"| node_file_output
node_cli -->|"prints HTML"| node_console_output
node_parser -->|"cleans tree"| node_tree_cleanup
node_core -->|"uses runtime"| node_component_runtime
node_component_runtime -->|"parses fragments"| node_parser
node_component_runtime -->|"formats output"| node_core_helpers
node_core -->|"uses helpers"| node_core_helpers
node_parser -.->|"feeds rendering"| node_html
node_core -->|"produces HTML"| node_html
node_standard_components -.->|"rendered by"| node_core
node_component_preset -.->|"registers components"| node_standard_components
node_validator -.->|"checks MJML"| node_core
node_config -.->|"configures rendering"| node_core

click node_cli "https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/src/client.js"
click node_file_read "https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/src/commands/readFile.js"
click node_watch "https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/src/commands/watchFiles.js"
click node_file_context "https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/src/helpers/fileContext.js"
click node_file_output "https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/src/commands/outputToFile.js"
click node_console_output "https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/src/commands/outputToConsole.js"
click node_stream_input "https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/src/commands/readStream.js"
click node_parser "https://github.com/mjmlio/mjml/blob/master/packages/mjml-parser-xml/src/index.js"
click node_tree_cleanup "https://github.com/mjmlio/mjml/blob/master/packages/mjml-parser-xml/src/helpers/cleanNode.js"
click node_core "https://github.com/mjmlio/mjml/blob/master/packages/mjml-core/src/index.js"
click node_component_runtime "https://github.com/mjmlio/mjml/blob/master/packages/mjml-core/src/createComponent.js"
click node_core_helpers "https://github.com/mjmlio/mjml/tree/master/packages/mjml-core/src/helpers"
click node_standard_components "https://github.com/mjmlio/mjml/tree/master/packages"
click node_component_preset "https://github.com/mjmlio/mjml/tree/master/packages/mjml-preset-core/src"
click node_validator "https://github.com/mjmlio/mjml/tree/master/packages/mjml-validator/src"
click node_config "https://github.com/mjmlio/mjml/blob/master/packages/mjml-core/src/helpers/mjmlconfig.js"

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_file_read,node_watch,node_file_context,node_file_output,node_console_output,node_stream_input toneBlue
class node_parser,node_tree_cleanup,node_core,node_component_runtime,node_core_helpers toneAmber
class node_standard_components,node_component_preset toneMint
class node_validator,node_config toneRose
class node_author,node_html toneIndigo
```

## Components

### Inputs and CLI

- [CLI orchestration](https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/src/client.js): `packages/mjml-cli/src/client.js`
- [File input](https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/src/commands/readFile.js): `packages/mjml-cli/src/commands/readFile.js`
- [Watch mode](https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/src/commands/watchFiles.js): `packages/mjml-cli/src/commands/watchFiles.js`
- [Include tracking](https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/src/helpers/fileContext.js): `packages/mjml-cli/src/helpers/fileContext.js`
- [File output](https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/src/commands/outputToFile.js): `packages/mjml-cli/src/commands/outputToFile.js`
- [Console output](https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/src/commands/outputToConsole.js): `packages/mjml-cli/src/commands/outputToConsole.js`
- [Stream input](https://github.com/mjmlio/mjml/blob/master/packages/mjml-cli/src/commands/readStream.js): `packages/mjml-cli/src/commands/readStream.js`

### Parsing and rendering

- [XML parser](https://github.com/mjmlio/mjml/blob/master/packages/mjml-parser-xml/src/index.js): `packages/mjml-parser-xml/src/index.js`
- [Tree cleanup](https://github.com/mjmlio/mjml/blob/master/packages/mjml-parser-xml/src/helpers/cleanNode.js): `packages/mjml-parser-xml/src/helpers/cleanNode.js`
- [HTML compiler](https://github.com/mjmlio/mjml/blob/master/packages/mjml-core/src/index.js): `packages/mjml-core/src/index.js`
- [Component runtime](https://github.com/mjmlio/mjml/blob/master/packages/mjml-core/src/createComponent.js): `packages/mjml-core/src/createComponent.js`
- [Rendering helpers](https://github.com/mjmlio/mjml/tree/master/packages/mjml-core/src/helpers): `packages/mjml-core/src/helpers`

### Email components

- [Standard components](https://github.com/mjmlio/mjml/tree/master/packages): `packages`
- [Core preset](https://github.com/mjmlio/mjml/tree/master/packages/mjml-preset-core/src): `packages/mjml-preset-core/src`

### Validation and config

- [MJML validator](https://github.com/mjmlio/mjml/tree/master/packages/mjml-validator/src): `packages/mjml-validator/src`
- [MJML configuration](https://github.com/mjmlio/mjml/blob/master/packages/mjml-core/src/helpers/mjmlconfig.js): `packages/mjml-core/src/helpers/mjmlconfig.js`

### Other components

- **Template author**
- **Responsive HTML**

## Connections

- Template author → CLI orchestration: supplies input (evidence: `README.md`)
- Template author → HTML compiler: compiles with (evidence: `README.md`)
- CLI orchestration → File input: reads files (evidence: `packages/mjml-cli/src/client.js`)
- CLI orchestration → Stream input: reads stream (evidence: `packages/mjml-cli/src/client.js`)
- CLI orchestration → Watch mode: starts watch (evidence: `packages/mjml-cli/src/client.js`)
- Watch mode → File input: reads changes (evidence: `packages/mjml-cli/src/commands/watchFiles.js`)
- Watch mode → Include tracking: tracks includes (evidence: `packages/mjml-cli/src/commands/watchFiles.js`)
- Watch mode → HTML compiler: compiles changes (evidence: `packages/mjml-cli/src/commands/watchFiles.js`)
- Watch mode → File output: writes results (evidence: `packages/mjml-cli/src/commands/watchFiles.js`)
- CLI orchestration → XML parser: parses input (evidence: `packages/mjml-cli/src/client.js`)
- CLI orchestration → HTML compiler: renders input (evidence: `packages/mjml-cli/src/client.js`)
- CLI orchestration → MJML validator: validates input (evidence: `packages/mjml-cli/src/client.js`)
- CLI orchestration → Core preset: loads preset (evidence: `packages/mjml-cli/src/client.js`)
- CLI orchestration → File output: writes HTML (evidence: `packages/mjml-cli/src/client.js`)
- CLI orchestration → Console output: prints HTML (evidence: `packages/mjml-cli/src/client.js`)
- XML parser → Tree cleanup: cleans tree (evidence: `packages/mjml-parser-xml/src/index.js`)
- HTML compiler → Component runtime: uses runtime (evidence: `packages/mjml-core/src/index.js`)
- Component runtime → XML parser: parses fragments (evidence: `packages/mjml-core/src/createComponent.js`)
- Component runtime → Rendering helpers: formats output (evidence: `packages/mjml-core/src/createComponent.js`)
- HTML compiler → Rendering helpers: uses helpers (evidence: `packages/mjml-core/src/index.js`)
- XML parser → Responsive HTML: feeds rendering
- HTML compiler → Responsive HTML: produces HTML (evidence: `README.md`)
- Standard components → HTML compiler: rendered by (evidence: `packages/mjml-core/src/index.js`)
- Core preset → Standard components: registers components
- MJML validator → HTML compiler: checks MJML
- MJML configuration → HTML compiler: configures rendering (evidence: `packages/mjml-core/src/index.js`)
