# unjs/unhead architecture

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

- Interactive diagram: https://gitdiagram.com/unjs/unhead
- Repository: https://github.com/unjs/unhead

## Overview

##### Project Type and Purpose
- This is an open-source, monorepo JavaScript/TypeScript library (“unhead”) for managing `<head>` tags/reactive SEO in SSR frameworks, with plugin support and framework-specific bindings.
- It provides a core engine (head entry definitions, deduping, sorting) plus client/server APIs, schema-org integration, framework adapters (Vue, React, Angular, Solid.js, Svelte), addons (e.g., SEO meta, treeshaking), documentation, examples, benchmarks, and CI/CD pipelines.

##### File Structure Analysis
- Top-level:
– pnpm-workspace.yaml, package.json, tsconfig.json, vitest.config.ts → orchestrate workspace
– .github/workflows → CI for test, build, release, bundle-size
– docs/ → content for documentation site (guides, API references, framework-specific sections)
– examples/ → sample SSR apps showing unhead integration in Angular, React, Vue, Svelte, TypeScript, streaming, prerendering
– bench/ → performance benchmarks for core engine, SSR pipelines, SEO meta
– packages/ & packages-aliased/ → core unhead, schema-org, framework adapters, plugins (addons), shared utilities, legacy support
– test/ → high-level exports tests for each package
- Each package folder contains: src/, build.config.ts, package.json, tests (unit/e2e), typings (d.ts), TS configs.

##### README Insights
- Confirms “unhead” is a head and template manager focusing on reactive SSR, SEO, performance.
- Mentions core composables (`useHead()`, `useSeoMeta()`, `useScript()`), tree-shaking, multi-framework support.

a. Main Components
- Monorepo Root (pnpm workspace, CI/CD, tooling)
- Core Engine (packages/unhead/src: core logic, client API, server API, plugins directory, scripts)
- Schema-org Module (packages/schema-org)
- Addons/Plugins (packages/addons)
- Framework Adapters (packages/vue, packages/react, packages/angular, packages/solid-js, packages/svelte)
- Examples (apps under examples/)
- Documentation Site (docs/)
- Benchmark Suite (bench/)
- CI/CD Pipelines (.github/workflows)
b. Relationships & Interactions
- Workspace orchestrator runs build tasks → compiles each package → outputs dist artifacts → published to npm
- Core Engine exposes public API (`createHead`, `useHead`) → consumed by framework adapters and examples
- Schema-org module plugs into core engine for JSON-LD generation
- Addons inject build-time or runtime transforms via unplugin systems (Vite, Webpack)
- Framework adapters wrap core API in framework-specific hooks/composables (e.g., React context, Vue mixins)
- Examples import framework adapter packages and core engine to demonstrate SSR and hydration flows
- Documentation site pulls guide MD files and auto-generates nav/API pages
- Benchmark suite runs core engine and SSR flows to measure perf
- CI/CD workflows trigger on commits/tags: run lint, tests, benchmarks, release
c. Architectural Patterns
- Monorepo with workspace package management (pnpm) and shared TS config
- Plugin architecture (unplugin) for build-time transformations
- Adapter pattern for framework integration
- Core engine + extension points (hooks, plugins, scripts)
- Document generator for docs and examples
d. Key Technologies
- TypeScript, pnpm, Vitest, unplugin (Vite/Webpack), Node.js, various framework CLIs (Vite, Angular CLI)
- CI: GitHub Actions
- Doc site: Markdown files + static site generator (implied)
- Benchmarking: custom scripts in bench/

##### Diagramming Conventions
– Monorepo Root (workspace)
– Core Engine
– Plugins/Addons
– Schema-org Module
– Framework Adapters (grouped or individual)
– Examples & Docs & Bench
– CI/CD
– Workspace → Build → Dist
– Core Engine → Framework Adapters → Examples
– Plugins → Core Engine
– Schema-org → Core Engine
– CI → Build & Test → Release
– Blue for core packages
– Green for adapters
– Orange for plugins/addons
– Gray for tooling/CI/docs/examples

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Monorepo Root
    subgraph "Monorepo Root (Workspace & Tooling)"
        direction TB
        WS["PNPM Workspace & Tooling"]:::tooling
        WS --> BuildProcess
        WS --> CI
        click WS "https://github.com/unjs/unhead/blob/main/pnpm-workspace.yaml"
        click WS "https://github.com/unjs/unhead/blob/main/package.json"
        click WS "https://github.com/unjs/unhead/blob/main/tsconfig.json"
        click WS "https://github.com/unjs/unhead/blob/main/vitest.config.ts"
    end

    %% Build Process
    BuildProcess["Build & Test & Release"]:::process
    BuildProcess --> DistArtifacts
    DistArtifacts["Dist Artifacts (npm)"]:::output

    %% CI/CD
    subgraph "CI/CD Pipelines"
        direction TB
        CI["GitHub Actions Workflows"]:::tooling
        click CI "https://github.com/unjs/unhead/tree/main/.github/workflows"
        CI --> BuildProcess
        CI --> Tests
        CI --> Release
    end

    Tests["Run Tests"]:::process
    Release["Publish Release"]:::process

    %% Core Engine
    subgraph "Core Engine"
        direction TB
        Core["unhead"]:::core
        click Core "https://github.com/unjs/unhead/tree/main/packages/unhead/"
    end

    %% Schema-org Module
    Schema["Schema-org Module"]:::plugin
    click Schema "https://github.com/unjs/unhead/tree/main/packages/schema-org/"

    %% Addons/Plugins
    Plugins["Addons / Plugins"]:::plugin
    click Plugins "https://github.com/unjs/unhead/tree/main/packages/addons/"

    %% Framework Adapters
    subgraph "Framework Adapters"
        direction TB
        Vue["Vue Adapter"]:::adapter
        React["React Adapter"]:::adapter
        Angular["Angular Adapter"]:::adapter
        Solid["Solid.js Adapter"]:::adapter
        Svelte["Svelte Adapter"]:::adapter

        click Vue "https://github.com/unjs/unhead/tree/main/packages/vue/"
        click React "https://github.com/unjs/unhead/tree/main/packages/react/"
        click Angular "https://github.com/unjs/unhead/tree/main/packages/angular/"
        click Solid "https://github.com/unjs/unhead/tree/main/packages/solid-js/"
        click Svelte "https://github.com/unjs/unhead/tree/main/packages/svelte/"
    end

    %% Examples
    Examples["Examples (SSR Apps)"]:::examples
    click Examples "https://github.com/unjs/unhead/tree/main/examples/"

    %% Documentation Site
    Docs["Documentation Site"]:::docs
    click Docs "https://github.com/unjs/unhead/tree/main/docs/"

    %% Benchmark Suite
    Bench["Benchmark Suite"]:::bench
    click Bench "https://github.com/unjs/unhead/tree/main/bench/"

    %% Relationships
    WS --> Core
    Core --> Schema
    Core --> Plugins
    Core --> Vue
    Core --> React
    Core --> Angular
    Core --> Solid
    Core --> Svelte

    Vue --> Examples
    React --> Examples
    Angular --> Examples
    Solid --> Examples
    Svelte --> Examples

    Docs --> WS
    Bench --> Core
    Bench --> BuildProcess

    %% Styles
    classDef core fill:#b3d4fc,stroke:#0366d6,color:#0366d6;
    classDef adapter fill:#d4fcb3,stroke:#2e8b29,color:#2e8b29;
    classDef plugin fill:#fcd4b3,stroke:#d97706,color:#d97706;
    classDef tooling fill:#e2e8f0,stroke:#4a5568,color:#4a5568;
    classDef process fill:#fff5bf,stroke:#d69e2e,color:#d69e2e;
    classDef output fill:#c6f6d5,stroke:#2f855a,color:#2f855a;
    classDef examples fill:#edf2ff,stroke:#5a67d8,color:#5a67d8;
    classDef docs fill:#ffe3e3,stroke:#c53030,color:#c53030;
    classDef bench fill:#e6fffa,stroke:#2c7a7b,color:#2c7a7b;
```
