Packages

@unhead/ssr

3.4.3 · 13 Oct 2026MIT277.2k / weekRepositoryHomepagenpmAtom feed

Your version

3.0.0

major9 Apr 2026Where it was published

3.4.3 is the newest release of 3.x.

In short

14 breaking16 new9 faster31 fixed14 changed

  • Breaking

    init hook removed

  • Breaking

    dom:renderTag, dom:rendered hooks deprecated (will be removed in v4)

  • Breaking

    dom:beforeRender is now synchronous (no async handlers)

  • Breaking

    PluginSchemaOrg / SchemaOrgUnheadPlugin replaced with UnheadSchemaOrg

  • Breaking

    canonicalHost replaced with host, canonicalUrl replaced with host + path

  • Breaking

    Drop deprecations

  • Breaking

    useHead() type narrowing

  • Breaking

    Sync renderDOMHead()

Release note

Unhead v3 rebuilds the rendering engine from the ground up. The motivation: streaming SSR. Frameworks like Nuxt, SolidStart, and SvelteKit stream HTML to the browser as data loads, but head tags were still stuck in a request/response model, resolved once and never updated. To fix this properly, we had to make rendering synchronous, pluggable, and side-effect free. The result is a faster, smaller, and more capable head manager.

Highlights

Streaming SSR

Head tags now update dynamically as suspense boundaries resolve during streaming. As each chunk streams to the browser, new <title>, <meta>, and <link> tags are pushed to a client-side queue and applied to the DOM. No waiting for the full page to load.

// entry-server.ts
import { createStreamableHead } from '@unhead/vue/stream/server'

const { head, wrapStream } = createStreamableHead()
app.use(head)

// wraps the Vue stream, injecting head updates as chunks resolve
return wrapStream(renderToWebStream(app), template)
// entry-client.ts
import { createStreamableHead } from '@unhead/vue/stream/client'

const head = createStreamableHead()
app.use(head)

Under the hood: a queue stub (window.__unhead__) collects head entries as they stream in before the main JS bundle loads. Once the client head instance initializes, it processes the queue and takes over. No entries are ever lost regardless of timing.

Streaming is supported for Vue, React, Solid.js, Svelte, and vanilla TypeScript. See PR #537.

Unified Vite Plugin + DevTools

A single @unhead/{framework}/vite plugin replaces the old manual composition of @unhead/addons + streaming plugin + framework glue. One import, one call, and you get tree-shaking, useSeoMeta → useHead transform, inline minification, streaming SSR, dev-mode ValidatePlugin auto-injection, and Vite DevTools integration.

// vite.config.ts
import { Unhead } from '@unhead/vue/vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue(), Unhead()],
})

The DevTools panel surfaces live head state during development: every useHead() / useSeoMeta() call with its source file and line number, resolved tags, SEO overview (title, description, canonical, Open Graph), useScript() load status, active plugins, template params, and warnings from the Validate plugin. Source tracing lets you click through from any tag back to the exact line that created it.

Available for Vue, React, Svelte, Solid, and vanilla via @unhead/bundler/vite (the renamed @unhead/addons package; the old name still works with a deprecation warning).

See PRs #726, #733, #731.

useHead() Type Narrowing

useHead() now narrows types based on input. Link, script, and meta tags resolve to specific subtypes instead of a generic union, so you get precise autocomplete and type errors when something is wrong.

useHead({
  link: [
    // Narrows to StylesheetLink: requires href, offers media, integrity, etc.
    { rel: 'stylesheet', href: '/styles.css' },
    // Narrows to PreloadLink: requires as attribute
    { rel: 'preload', as: 'font', href: '/font.woff2', crossorigin: 'anonymous' },
  ],
  script: [
    // Narrows to ModuleScript
    { src: '/app.mjs', type: 'module' },
    // Narrows to JsonLdScript
    { type: 'application/ld+json', innerHTML: '{}' },
  ],
})

See PRs #627, #665, #729.

ValidatePlugin

New optional ValidatePlugin that inspects resolved head output and warns about common mistakes: missing titles, duplicate meta tags, contradictory preload priorities, render-blocking scripts, late <meta charset>, too many fetchpriority="high" hints, preconnect without crossorigin, and more. Also includes v2 migration rules that detect deprecated property names (children, hid/vmid, body: true), missing TemplateParamsPlugin, and missing AliasSortingPlugin — all of which cause silent breakage on upgrade. Auto-injected in dev by the unified Vite plugin so warnings surface in the browser console without any manual setup. Fully tree-shakeable. Rules use ESLint-style flat config:

import { ValidatePlugin } from 'unhead/plugins'

createHead({
  plugins: [
    ValidatePlugin({
      rules: {
        'missing-description': 'off',
      }
    })
  ]
})

See PRs #690, #691, #716, #722, #725, #732.

Canonical Plugin

New built-in CanonicalPlugin that auto-generates <link rel="canonical"> tags and resolves relative URLs to absolute in og:image, twitter:image, and og:url. Includes query parameter filtering (strips tracking params like utm_source, fbclid, gclid by default), trailing slash normalization, and automatic hash fragment stripping. Essential for SEO and social sharing.

import { CanonicalPlugin } from 'unhead/plugins'

createHead({
  plugins: [
    CanonicalPlugin({
      canonicalHost: 'https://mysite.com',
      trailingSlash: true,
      queryWhitelist: ['page', 'sort'],
    })
  ]
})

See PRs #492, #713.

MinifyPlugin

New optional MinifyPlugin that minifies inline <script> and <style> tag content during SSR. Uses lightweight pure-JS minifiers with zero native dependencies, safe for edge and serverless runtimes. A companion build-time transform (MinifyTransform in @unhead/bundler) pre-minifies static innerHTML literals at compile time. Standalone utilities (minifyJS, minifyCSS, minifyJSON) are also available via unhead/minify.

import { MinifyPlugin } from 'unhead/plugins'

createHead({
  plugins: [MinifyPlugin()]
})

See PR #705.

Performance

Buildv3 sizev2 sizeDelta gz
client1025411513-534 (-11.2%)
server989410361-194 (-4.6%)
vueClient1132312567-533 (-10.2%)
vueServer1084911312-191 (-4.1%)
Benchmarkv2 meanv3 meanDelta
@unhead/vue0.106ms0.072ms32% faster
core0.088ms0.073ms17% faster

Key optimizations:

  • Client-only CAPO sorting

  • Pure, tree-shakeable core with no side effects

  • Minified internal DOM state properties

  • Migrated unplugins from estree-walker/acorn-loose to oxc-walker

  • Walker-based transformHtmlTemplate

  • TemplateParamsPlugin and AliasSortingPlugin made opt-in for smaller bundles (#493, #494)

Schema.org

  • 12 new nodes: Dataset, MusicAlbum, MusicGroup, MusicPlaylist, MusicRecording, PodcastEpisode, PodcastSeason, PodcastSeries, Service, TVEpisode, TVSeason, TVSeries

  • Graph resolution rewrite for correctness and performance

  • Removed ohash and defu dependencies

Other Changes

  • renderDOMHead() / renderSSRHead() are now fully synchronous, single-pass via a composable resolveTags() pipeline; the head instance exposes a pluggable render() function for framework integrations (#619, #622, #628, #629, #630)

  • @unhead/react/helmet drop-in compat export for users migrating from react-helmet

  • useHeadSafe() now whitelists CSS styles

  • Support for blocking attribute on scripts and stylesheets

  • useScript() consolidated back into core, legacy support dropped

  • fediverse:creator meta tag support

  • Switched from hookable to lighter HookableCore with sync-only hooks

  • Deprecation warnings added to aliased packages (@unhead/schema, @unhead/shared)

  • templateParams extensible via module augmentation

  • Respect user-provided twitter:card in InferSeoMetaPlugin

  • Enforce as attribute for preload links

  • onRendered callback option on useHead() for synchronizing with DOM head updates

  • tagWeight option on createHead() to override default CAPO tag weight function

Bug Fixes

  • Hydration race condition with deferred patches

  • Process pending patches even when dirty is false

  • Deduplicate matching tags inside same render cycle

  • Dedupe <link rel="alternate"> correctly (#655, #656, #658)

  • React: Dispose head entries on unmount in StrictMode

  • React: Force invalidation on entry disposal

  • Vue: Support computed getter trigger

  • Vue: Expose @unhead/vue/stream/iife with correct types

  • Scripts: Prevent scope disposal from aborting unrelated trigger

  • Schema.org: Allow null to opt out of default values

  • Schema.org: Normalize target to array before merging potentialAction

  • Avoid mutating cached titleTemplate tag in resolveTitleTemplate

Breaking Changes

Synchronous rendering

renderDOMHead() and renderSSRHead() no longer return promises. Remove await.

Build plugins: @unhead/addons → @unhead/bundler (#726, #733)

The @unhead/addons package has been renamed to @unhead/bundler (the old name still works with a deprecation warning). Framework Vite plugins now use a named Unhead export and ship from each framework's /vite subpath:

- import unhead from '@unhead/addons/vite'
+ import { Unhead } from '@unhead/vue/vite'
// or @unhead/react/vite, @unhead/svelte/vite, @unhead/solid-js/vite

  export default defineConfig({
-   plugins: [unhead()],
+   plugins: [Unhead()],
  })

Strict Link / Script / Meta types

Link and Script unions no longer fall back to GenericLink / GenericScript, so the type system enforces per-tag constraints (e.g. preload + as: 'font' requires crossorigin). Meta content is now required; use content: null explicitly to remove a meta tag. Custom rel / type values need satisfies GenericLink / satisfies GenericScript.

Dropped deprecations

OldNew
childreninnerHTML
hid / vmidkey
body: truetagPosition: 'bodyClose'
useServerHead / useServerSeoMetauseHead / useSeoMeta
createHeadCorecreateUnhead
@unhead/vue/legacy@unhead/vue/client or @unhead/vue/server (legacy path still works with deprecation warning)
mode option on entriesUse client/server createHead imports

CJS removed

All packages are ESM-only.

Plugins now opt-in

TemplateParamsPlugin and AliasSortingPlugin are no longer included by default. Import and register them explicitly if needed.

Hooks removed

  • Breaking

    init hook removed

  • Breaking

    dom:renderTag, dom:rendered hooks deprecated (will be removed in v4)

  • Breaking

    dom:beforeRender is now synchronous (no async handlers)

Type changes

RemovedReplacement
HeadHeadTag
MetaFlatInputMetaFlat
RuntimeModeRemoved
@unhead/schemaunhead/types
@unhead/sharedunhead

Schema.org

  • Breaking

    PluginSchemaOrg / SchemaOrgUnheadPlugin replaced with UnheadSchemaOrg

  • Breaking

    canonicalHost replaced with host, canonicalUrl replaced with host + path

Migration Tooling

Add ValidatePlugin during your upgrade to automatically detect v2 patterns:

import { ValidatePlugin } from 'unhead/plugins'
createHead({ plugins: [ValidatePlugin()] })

It will warn about missing plugins, deprecated properties, and other common migration issues. Remove it once migration is complete. If you use the unified Vite plugin, ValidatePlugin is auto-injected in dev so you don't have to wire it up manually. See PRs #722, #733.

Migration Guide

See the full Migration Guide for detailed upgrade instructions.

Changelog

Breaking Changes

  • Breaking

    Drop deprecations

  • Breaking

    useHead() type narrowing

  • Breaking

    Sync renderDOMHead()

  • Breaking

    Sync renderSSRHead()

  • Breaking

    Pluggable render() function

  • Breaking

    bundler: Named Unhead export, ctx-based transforms, dev-mode validate

  • Breaking

    types: Enforce strict type narrowing for Link and Script unions

  • Breaking

    unhead: Sync resolve tag engine

  • Breaking

    unhead: Composable resolveTags()

Features

  • Streaming support

  • ValidatePlugin for head tag validation

  • Access resolved head with onRendered

  • Add MinifyPlugin for inline script/style minification

  • V2 migration rules in ValidatePlugin + DOM hook deprecations

  • @unhead/bundler and /vite subpath exports

  • canonical: Query param filtering, trailing slash & hash stripping

  • devtools: Vite devtools integration

  • react: Add @unhead/react/helmet compat export

  • unhead: Add tagWeight option and meta-beyond-1mb validation rule

  • validate: Add performance validation rules

  • validate: Add 7 performance/web vitals validation rules

  • vue,streaming: Lower level stream APIs

Bug Fixes

  • Switch to HookableCore

  • Pure unhead core

  • Hydration race condition with deferred patches

  • Sync transformHtmlTemplate

  • Stricter type narrowing for head schema

  • Type render() return across all framework integrations

  • Cherry-pick fixes from main

  • Add fediverse:creator meta tag support

  • Avoid mutating cached titleTemplate tag in resolveTitleTemplate

  • addons: Respect user-provided twitter:card in InferSeoMetaPlugin

  • client: Process pending patches even when dirty is false

  • react: Ssr regression

  • schema-org: Avoid crashing from 3+ duplicate nodes

  • schema-org: Allow null to opt out of default values

  • schema-org: Clear graph nodes on each normalization cycle

  • schema-org: Dedupe typed arrays

  • schema-org: Normalize target to array before merging potentialAction

  • schema-org: Add missing Vue exports for schemaAutoImports entries

  • types: Enforce required as attribute for preload links

  • types: Make templateParams extensible via module augmentation

  • unhead: Avoid explicit vite dependency

  • unhead: Deduplicate matching tags inside same render cycle

  • unhead: Broken book:release_date meta

  • validate: False positives for warmup preloads and charset position

  • vue: Expose @unhead/vue/stream/iife with correct types

  • vue: Restore Style component inside Head and children prop

Performance

  • Migrate unplugins to oxc-walker

  • client: Reduce bundle size

  • unhead: Client only capo sorting

A whole project to check? Paste its package.json in the dependency check: every deprecated, outdated or vulnerable dependency, with what to upgrade to. Free, no account.