feat(nuxt): add useHeadSafe and remove layer around head imports

[harlan-zw]

🔗 Linked issue

❓ Type of change

• 📖 Documentation (updates to the documentation, readme or JSdoc annotations)
• 🐞 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)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

For some context, Nuxt 3 was initially built to support different head providers. Initially, it was providing support for @vueuse/head and Vue meta (although there was no way to opt-in to it).

With @vueuse/head moving towards deprecation and Nuxt going all-in on Unhead, it makes sense to clean up some of the technical debt introduced in supporting multiple head providers.

This technical debt can be summarised as:

• #head alias - pointed towards where the head composables where for
• #app re-exporting the #head composables - allowed nuxt internally to use any head provider

With this PR we move all head composables to the auto imports. For the Nxut app internal useHead calls, we import directly from @unhead/vue.

Inadvertibly we also are adding support for the new composable useHeadSafe so I have provided doc and tests for it.

⚠️ We are now deprecating importing useHead from #head or #app. Users should switch to importing from #imports. Also, we no longer recommend augmenting HeadAugmentations; instead, we can directly augment the Unhead schema if we want to add custom completions.

📝 Checklist

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

[codesandbox]

  Open in CodeSandbox Web Editor | VS Code | VS Code Insiders

[danielroe]

This is great! To reduce breaking changes, do you think we can keep an export from #app that is marked as deprecated - and likewise, for HeadAugmentations - mark it as deprecated? We can then remove both in next minor: v3.4.

[danielroe]

I've tentatively pushed a reversion of the breaking change in favour of deprecating the exports/interface, but happy to rethink if you think this isn't sensible. 🙏