repository·main·Indexed 22 days ago
https://github.com/unjs/unheadA high-performance document head and template manager for modern reactive SSR JavaScript frameworks. Unhead enables management of SEO, meta tags, and scripts with support for streaming SSR and Vite integration. The ecosystem includes specialized packages such as @unhead/angular for Angular applications, @unhead/bundler for build-time optimizations, @unhead/cli for auditing and migration, and @unhead/eslint-plugin for source-level linting.
@unhead/angular provides full-stack <head> management for Angular applications. It is optimized for Angular, supports Server-Side Rendering (SSR), and integrates with Angular's dependency injection system. It allows for reactive management of titles, meta tags, and other head elements using Angular Signals.Unhead is a document head and template manager designed to improve SEO, performance, and developer experience in reactive SSR JavaScript frameworks.
Key features include:
useHead(): Handles deduping, sorting, tag merging, and type narrowing.useSeoMeta(): Provides flat SEO meta tags with compile-time transforms.useScript(): A powerful and performant API for script loading.<head> elements, such as titles, meta tags, scripts, and structured data. It supports both server-side rendering (SSR) and client-side rendering across various frameworks including Vue, React, Svelte, Solid, and Angular, as well as vanilla TypeScript.Unhead provides several specialized capabilities for managing document metadata:
useSeoMeta().useSchemaOrg().useScript().Unhead is a universal head manager designed for JavaScript applications to manage document metadata across both Server-Side Rendering (SSR) and Client-Side Rendering (CSR) environments.
It manages:
<head> element.<html> and <body> elements (e.g., htmlAttrs, bodyAttrs).bodyOpen and bodyClose to allow rendering content outside the main app entry point.Unhead is designed to be framework-agnostic, providing a core API that can be used with Vue, React, Svelte, Solid, Angular, or vanilla TypeScript.
Unhead validation is organized into three layers to provide different feedback loops:
audit / migrate): The fastest feedback loop. Runs on the AST. Catches typos, deprecated props, and structural issues (e.g., missing @ on Twitter handles). Best used in your editor via @unhead/eslint-plugin or in CI.validate-html / validate-url): Runs the ValidatePlugin over rendered HTML. Catches issues that depend on the resolved tag list, such as og:image dimensions, canonical mismatches, or charset position.ValidatePlugin: Runs live in your application during development, providing real-time warnings.The ESLint rules work by walking source-level calls into the following unhead APIs:
useHeaduseHeadSafeuseServerHeaduseServerHeadSafeuseSeoMetauseServerSeoMetadefineLink / defineScript (tag helpers)Rules automatically descend into tag arrays inside meta, link, script, noscript, and style, as well as object literals inside htmlAttrs and bodyAttrs.
Note: Because rules are limited to what is expressible in the AST, they cannot perform cross-tag or rendered-output checks. For checks like canonical-og-url-mismatch, meta-beyond-1mb, charset-not-early, or too-many-preloads, you must use the runtime ValidatePlugin or the @unhead/cli commands unhead validate-url or unhead validate-html.
The rendered JSON-LD is automatically escaped to prevent input from closing the <script> element. However, Unhead does not validate node values or sanitize HTML contained within them.
Warning: Do not pass unknown or untrusted third-party input without validating and sanitizing it yourself first.
useSeoMeta()name vs property attributes and converts camelCase keys to meta tags.useHead()When updating head tags in Angular, you have two patterns depending on your state management:
Track Signals in an Effect (Recommended): Use this when multiple code paths or components might update a signal. The effect() ensures the head is always in sync with the current signal value.
Patch Imperatively: Use this when a specific method already owns the state change logic. This is useful for performance or simplicity if you don't need the overhead of an effect.
Comparison:
// Pattern 1: Effect-based (Recommended)
constructor() {
effect(() => {
this.head.patch({
meta: [{ name: 'description', content: this.description() }]
})
})
}
// Pattern 2: Imperative
setTitle(title: string) {
this.title.set(title)
this.head.patch({ title })
}Aliases adjust the registration order after Unhead has calculated each tag's weight. They do not recalculate the weight of the aliasing tag during the current resolution.
Executable scripts are rejected in safe mode. A <script> tag is only kept if it has textContent and its type ends in json (e.g., application/json or application/ld+json).
When a JSON script is kept, the JSON is parsed or serialized again, and prototype-related keys are removed to prevent injection. Note that innerHTML is never allowed in safe mode.
useHeadSafe({
script: [{
type: 'application/json',
textContent: { theme: 'dark' },
}],
})