Unhead is a full-stack, framework-agnostic head manager designed to simplify and standardize how metadata (like `<title>`, `<meta>`, `<link>`) is managed in JavaScript applications. It is currently at version 3.0.4, with frequent patch releases addressing bug fixes and minor improvements, and major versions (like the recent v3.0.0) introducing significant architectural changes, such as the rebuild for streaming SSR. Its key differentiators include comprehensive framework agnosticism, reactive head management, robust server-side rendering support with a focus on streaming capabilities, SEO-friendliness, type safety via TypeScript, and a lightweight, tree-shakable design optimized for performance with minimal runtime overhead. It integrates seamlessly with popular frameworks through dedicated packages like `@unhead/vue` and `@unhead/react`.
npm install unheadVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to create a head instance, add common head elements (title, meta, link, script) using `useHead`, and then synchronously render the collected head and body tags, which is typically done in a Server-Side Rendering (SSR) context.
Review the v3 migration guide on the Unhead documentation site. Update `head.render()` calls to `head.renderSync()` where applicable for SSR. Adapt custom renderers and plugins to the new synchronous, pluggable architecture. Ensure CommonJS `require` statements are replaced with ESM `import` statements.
Upgrade to `unhead` version 2.1.11 or later immediately, especially if your application handles untrusted input with `useHeadSafe`.
Upgrade to `unhead` version 2.1.12 or later to mitigate potential prototype pollution risks.
Always use ES module `import` syntax (e.g., `import { createHead } from 'unhead'`). Ensure your project is configured for ESM or use a bundler that correctly handles ESM imports.For server-side rendering, always import `createHead` from `unhead/server` (e.g., `import { createHead } from 'unhead/server'`). For client-side rendering, use `unhead/client`.Change `head.render()` to `head.renderSync()` for synchronous SSR rendering.
Update your import statements to use ES Module syntax: `import { createHead, useHead } from 'unhead'`.Upgrade Unhead to the latest v3 patch version (e.g., v3.0.4 or later) as recent fixes address `readonly` inputs and string widening issues. Ensure custom `rel` or `type` attributes are correctly typed as `string & {}` or use `as const` for literals to prevent widening.Ensure you are using `unhead` version 3.0.3 or higher if you are experiencing inconsistent head tag updates or hydration issues in a Vite development environment.