# bubkoo/html-to-image architecture

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

- Interactive diagram: https://gitdiagram.com/bubkoo/html-to-image
- Repository: https://github.com/bubkoo/html-to-image

## Overview

##### Project Type and Purpose
- This is an open‐source TypeScript library (“html‐to‐image”) that converts a given DOM node into an image (PNG, JPEG, SVG, Blob, Canvas element, or raw pixel data).
- It is packaged as an NPM module, bundled via Rollup, tested with Karma, and continuously integrated/deployed via GitHub Actions.

##### File Structure Analysis
- /src: core pipeline modules (cloning nodes, applying styles, embedding fonts/images, serializing to SVG, generating data URLs).
- /test: resource fixtures (HTML/CSS/media) and test specs.
- rollup.config.js & karma.conf.js: build and test configurations.
- package.json, tsconfig.json: package metadata and TypeScript compiler options.
- .github/workflows: CI pipelines for build, tests, coverage, releases.

##### Key README Insights
- Describes a linear pipeline: clone DOM → compute and inline styles (including pseudo‐elements) → embed fonts & images → serialize to SVG inside a `<foreignObject>` → render on canvas for raster outputs.
- Exposes multiple top‐level functions (`toPng`, `toSvg`, `toJpeg`, `toBlob`, `toCanvas`, `toPixelData`) returning Promises.

##### Main Components
a. Input Layer
- “User Code” calling library functions with a DOM node and options.
b. Core Pipeline Modules (in /src)
1. clone-node.ts & clone-pseudos.ts
2. apply-style.ts
3. embed-webfonts.ts
4. embed-images.ts & embed-resources.ts
5. dataurl.ts & util.ts (serialization helpers)
c. Output Generators
- toSvg: wraps serialized XML in SVG → returns SVG data URL.
- toCanvas: creates `<img>` from SVG URL → draws on off-screen `<canvas>`.
- toPng/toJpeg/toBlob: reads canvas and exports desired format.
- toPixelData: reads pixel buffer from canvas.
d. External Services/APIs
- Browser DOM & CSSOM
- Fetch API for fonts/images
- Canvas & Image HTML5 APIs
e. Build & CI Infrastructure
- Rollup bundling → npm package
- Karma + Jasmine + ts‐node tests → code coverage
- GitHub Actions workflows for CI, code scanning, and publishing

##### Relationships & Data Flow
- Within Core Pipeline: Clone → Style → Embed Fonts → Embed Images → Serialize → Output Generator
- Output Generator → return Promise<DataURL|Blob|Canvas|Uint8Array>
- Build/Test: Source modules → Rollup → Bundled JS → Package Registry; Source + Tests → Karma → CI → GitHub Actions

##### Architectural Patterns & Principles
- Pipeline/Chain of Responsibility: each module performs one transformation step.
- Separation of Concerns: cloning, styling, embedding, serialization handled by distinct modules.
- Promise‐based async flow for network I/O (fonts, images).
- Modular, pluggable via top‐level functions that orchestrate the pipeline.

## Diagram (Mermaid)

```mermaid
graph TB

  subgraph "Input Layer"
    User["User Code\n(toPng, toSvg, toJpeg, toBlob, toCanvas, toPixelData)"]:::io
  end

  subgraph "Core Pipeline"
    CloneNode["Clone Node"]:::core
    ClonePseudos["Clone Pseudo-elements"]:::core
    ApplyStyle["Compute & Inline Styles"]:::core
    EmbedWebfonts["Embed Webfonts"]:::core
    EmbedImages["Embed Images"]:::core
    EmbedResources["Embed Other Resources"]:::core
    DataURL["Serialize to DataURL/SVG"]:::core
  end

  subgraph "Output Generators"
    ToSvg["toSvg() →Promise<string>"]:::io
    ToCanvas["toCanvas() →Promise<HTMLCanvasElement>"]:::io
    ToPng["toPng() →Promise<Blob>"]:::io
    ToJpeg["toJpeg() →Promise<Blob>"]:::io
    ToBlob["toBlob() →Promise<Blob>"]:::io
    ToPixel["toPixelData() →Promise<Uint8Array>"]:::io
  end

  subgraph "External Browser APIs"
    DOM["Browser DOM & CSSOM"]:::external
    Fetch["Fetch API"]:::external
    CanvasAPI["Canvas & Image API"]:::external
  end

  subgraph "Build & CI Infrastructure"
    Rollup["Rollup Bundling"]:::infra
    Karma["Karma + Jasmine Tests"]:::infra
    GHActions["GitHub Actions"]:::infra
    PackageJSON["package.json & tsconfig.json"]:::infra
  end

  %% Data Flow
  User -->|"invoke pipeline"| CloneNode
  CloneNode --> ClonePseudos --> ApplyStyle --> EmbedWebfonts --> EmbedImages --> EmbedResources --> DataURL
  DataURL --> ToSvg
  DataURL --> ToCanvas
  ToCanvas --> ToPng
  ToCanvas --> ToJpeg
  ToCanvas --> ToBlob
  ToCanvas --> ToPixel

  %% External API interactions
  DOM --> CloneNode
  DOM --> ApplyStyle
  Fetch --> EmbedWebfonts
  Fetch --> EmbedImages
  Fetch --> EmbedResources
  CanvasAPI --> ToCanvas

  %% Build/Test Flow
  CloneNode & ClonePseudos & ApplyStyle & EmbedWebfonts & EmbedImages & EmbedResources & DataURL --> Rollup
  CloneNode & ClonePseudos --> Karma
  Karma --> GHActions
  Rollup --> GHActions
  GHActions --> PackageJSON

  %% Click Events
  click User "https://github.com/bubkoo/html-to-image/blob/master/src/index.ts"
  click CloneNode "https://github.com/bubkoo/html-to-image/blob/master/src/clone-node.ts"
  click ClonePseudos "https://github.com/bubkoo/html-to-image/blob/master/src/clone-pseudos.ts"
  click ApplyStyle "https://github.com/bubkoo/html-to-image/blob/master/src/apply-style.ts"
  click EmbedWebfonts "https://github.com/bubkoo/html-to-image/blob/master/src/embed-webfonts.ts"
  click EmbedImages "https://github.com/bubkoo/html-to-image/blob/master/src/embed-images.ts"
  click EmbedResources "https://github.com/bubkoo/html-to-image/blob/master/src/embed-resources.ts"
  click DataURL "https://github.com/bubkoo/html-to-image/blob/master/src/dataurl.ts"
  click Rollup "https://github.com/bubkoo/html-to-image/blob/master/rollup.config.js"
  click Karma "https://github.com/bubkoo/html-to-image/blob/master/karma.conf.js"
  click GHActions "https://github.com/bubkoo/html-to-image/blob/master/.github/workflows/ci.yml"
  click PackageJSON "https://github.com/bubkoo/html-to-image/blob/master/package.json"

  %% Styles
  classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
  classDef io fill:#90EE90,stroke:#000,stroke-width:1px
  classDef external fill:#FFE4B5,stroke:#000,stroke-width:1px
  classDef infra fill:#D3D3D3,stroke:#000,stroke-width:1px
```
