feat(head): improved Unhead integration - #19302

🔗 Linked issue

unjs/unhead#116, #15668

❓ Type of change

• 📖 Documentation (updates to the documentation or readme)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality like performance)
• ✨ New feature (a non-breaking change that adds functionality)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

Unhead v1.1.0 was recently released.

With the dep update, I figure it's a good time to improve the integration:

PR To Do

• benchmark v1.1
• test treeshaking

Features

Dropping @vueuse/head dependency

To avoid breaking a bunch of third-party packages, the dependency was kept on @vueuse/head, which acted as a simple compatibility wrapper for Unhead. While we still need some support for this, Unhead now exports the compatibility layer directly.

This gives finer control over what's imported, allowing for better tree-shaking. For example, @unhead/dom should be treeshaken from the server build now.

Support app.head.options

While there are minimal build-time options available for Unhead, this is needed to enable experimentalHashHydration which I'm going to enable for nuxt-unhead. It will be enabled in the future by default but want to test it out a bit first.

SSR: Skip app.head entry client-side

This provides a performance improvement for SSR apps, fixes the bug unjs/unhead#116 and allows for experimentalHashHydration.

export default defineNuxtConfig({
  app: {
    head: {
      options: {
        experimentalHashHydration: true
      }
    }
  }
})

New composables

useServerSeoMeta - Basically what was already available but it provides a { mode: 'server' } which allows for the experimental hash hydration

useHeadSafe / useServerHeadSafe - Bit verbose having both but we need the server function for the above and to treeshake it from the client build (once the vite plugin is implemented)

Unhead Unplugin

• Treeshakes server components
• Transforms useSeoMeta (saves ~2kb gzipd)

Todo (subsequent PRs?)

The following items are things I'd like to solve but I don't think can exist within this PR.

Expose Unhead Hooks

These are pretty easy to implement but not sure if this PR is the best spot for them. They're currently not documented within the Unhead docs so should probably sort that out first.

Document Template Params

These are mainly used for lower-level integrations at this point.

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.