Unhead: Universal Head Manager

Common errors

• TypeError: head.render is not a function

  cause Attempting to call `render()` on a `head` instance created with v3, where `render` was renamed to `renderSync`.
  fix Change `head.render()` to `head.renderSync()` for synchronous SSR rendering.

• Error [ERR_REQUIRE_ESM]: require() of ES Module ... unhead/index.mjs not supported.

  cause Attempting to import `unhead` using CommonJS `require()` syntax in an environment where `unhead` is distributed as an ES Module.
  fix Update your import statements to use ES Module syntax: `import { createHead, useHead } from 'unhead'`.

• Property 'title' does not exist on type 'HeadEntryOptions' or similar TypeScript errors when defining head elements.

  cause Type widening in older Unhead versions or incorrect type definitions being passed, preventing proper type inference for specific meta attributes or elements. Might also occur if using a custom `rel` or `type` without proper type narrowing escape hatches.
  fix 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.

• Vite dev mode issues with head tags not updating correctly or SSR hydration mismatches.

  cause In `v3.0.3`, a bug was fixed where `SSRStaticReplace` was improperly disabled in Vite dev mode, leading to potential inconsistencies between server-rendered and client-hydrated head content.
  fix 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.

Warnings

• breaking Unhead v3.0.0 introduces a complete rebuild of the rendering engine to support streaming SSR. This change makes rendering synchronous, pluggable, and side-effect free. Existing v2 code relying on asynchronous rendering or specific internal behaviors will break. The core API for `render` became `renderSync`.
  Fix: 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.
• gotcha A security vulnerability (XSS bypass via attribute name injection) was fixed in v2.1.11 when using `useHeadSafe`. This could allow malicious script injection if `useHeadSafe` was used with untrusted user input.
  Fix: Upgrade to `unhead` version 2.1.11 or later immediately, especially if your application handles untrusted input with `useHeadSafe`.
• gotcha Unhead v2.1.12 included a fix for prototype pollution. While not explicitly detailed as an exploit, prototype pollution vulnerabilities can lead to various security issues, including arbitrary code execution or denial of service.
  Fix: Upgrade to `unhead` version 2.1.12 or later to mitigate potential prototype pollution risks.
• gotcha Since v3, Unhead is primarily an ESM-first package. Attempting to use `require()` for imports will lead to errors in most modern Node.js environments unless specific transpilation or module resolution configurations are in place.
  Fix: 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.
• deprecated In v3, the main `unhead` package for SSR context changed its export path. While `v3.0.3` restored some legacy exports for migration, relying on `createHead` from the root `unhead` package for SSR is generally incorrect.
  Fix: For server-side rendering, always import `createHead` from `unhead/server` (e.g., `import { createHead } from 'unhead/server'`). For client-side rendering, use `unhead/client`.

Install

• npm install unhead npm
• yarn add unhead yarn
• pnpm add unhead pnpm

Imports

• createHead
  wrong:

  const { createHead } = require('unhead')

  correct:

  import { createHead } from 'unhead'

  Primary function to initialize a new head instance. CommonJS `require` is not directly supported since v3, which is ESM-only.
• useHead
  wrong:

  import useHead from 'unhead/vue'

  correct:

  import { useHead } from 'unhead'

  Used to add head entries to the active head instance. While framework-specific wrappers exist (e.g., `@unhead/vue`), the core `useHead` is from `unhead` directly when using the generic API. Incorrectly importing from framework packages can lead to unexpected behavior.
• createHead (SSR)
  wrong:

  import { createHead } from 'unhead'

  correct:

  import { createHead } from 'unhead/server'

  When performing Server-Side Rendering (SSR), it's crucial to import `createHead` from `unhead/server` to ensure the correct SSR-optimized instance is used for rendering head tags synchronously and with streaming support. Using the client-side `createHead` in an SSR context will not yield the desired output.

Quickstart

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.

import { createHead, useHead } from 'unhead';

// 1. Create a head instance. For SSR, use `createHead` from 'unhead/server'.
const head = createHead();

// 2. Add reactive head entries using `useHead`.
// This example updates the title and adds a meta description.
useHead({
  title: 'My Dynamic App Title',
  meta: [
    { name: 'description', content: 'This is a dynamic description for my awesome application.' },
    { property: 'og:title', content: 'Open Graph Title' }
  ],
  link: [
    { rel: 'canonical', href: 'https://example.com/my-page' }
  ],
  script: [
    { src: 'https://unpkg.com/some-script.js', defer: true, body: true }
  ]
}, { head });

// 3. For SSR, render the head tags.
// In a real SSR environment, you'd call this after all components have rendered.
const { headTags, bodyTags } = head.renderSync();

console.log('Generated Head Tags:\n', headTags);
console.log('Generated Body Tags (scripts in body):\n', bodyTags);

// Output example (simplified):
// <title>My Dynamic App Title</title>
// <meta name="description" content="This is a dynamic description for my awesome application.">
// ...
// <script src="https://unpkg.com/some-script.js" defer></script>