How unjs/unhead works
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