feat(nuxt): migrate to latest @vueuse/head

[harlan-zw]

🔗 Linked issue

resolves nuxt/nuxt#14271, resolves nuxt/nuxt#15029, resolves nuxt/nuxt#13848, (maybe resolves) nuxt/nuxt#15093

❓ 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

A number of updates have gone out for https://github.com/vueuse/head to try and improve the DX, fix bugs and unblock integration features. This PR aims to get Nuxt using them.

nuxt-hedge

To make the upgrade easier to test, I created the module https://github.com/harlan-zw/nuxt-hedge, it has core logic parity to this PR.

You can play with it here: https://stackblitz.com/edit/nuxt-starter-we3qh7?file=pages/index.vue

---

Nuxt meta Module Update

Missing Component props

Adds support for body and render-priority to components (Note: key is not supported by Vue for deduping)

Block DOM updates until page is ready

This solves the suspense issue and improves hydration speed. (nuxt/nuxt#14271)

Simplify ref wrapping/unwrapping

⚠️ Changes the shortcut props (viewport and charset) to only be typed for the nuxt.config.ts app.head. This avoids the complexity around wrapping every input in a ref

app.head is typed as a plain object - no reactivity

(see breaking changes)

---

@vueuse/head Updates

Type Improvements

Nuxt has not migrated to the latest @vueuse/head types (powered by zhead), this PR introduces them.

Legacy key support

Help users migrating from vue-meta / nuxt v2

• feat: support deprecated dedupe keys vueuse/head#106
• textContent and innerHTML will map to children

Better Reactivity

Currently, users are restricted to refs and computed, now they can use computed getters like they can elsewhere in Vue and VueUse.

useHead({
  title: () => `${title.value} - My Site`
})

• feat: computed getter support vueuse/head#110
• refactor!: v1 initial, CSR performance, awaitable hooks vueuse/head#126

Hooks

These are not documented yet as they are intended to be for framework integrations.

• feat: before dom update hookable vueuse/head#114, resolves useHead causes flicker when hydrating SSR-rendered page nuxt#14271
• feat: hook into resolved tags hookTagsResolved vueuse/head#115
• feat: improved hook api vueuse/head#132

More performant

When there are multiple useHead's, there is a significant performance improvement. This also allows tags will be ordered when CSR'd.

• feat: debounce dom updates vueuse/head#120
• refactor!: v1 initial, CSR performance, awaitable hooks vueuse/head#126

---

⚠️ Breaking Changes

The shortcuts viewport and charset are available to make configuring these global meta tags easier. However, it complicates useHead reactivity logic, so we choose to drop support for them within the composable.

Instead, these shortcuts can only be provided when used in nuxt.config.ts. If you are using the values (width=device-width, initial-scale=1, utf-8), then you can simply delete these as they are the defaults.

Before - Your page

useHead({
  viewport: 'width=device-width, initial-scale=2',
  charset: 'utf-16'
})

After - nuxt.config.ts

export default defineNuxtConfig({
    // ....
    app: {
      head: {
        viewport: 'width=device-width, initial-scale=2',
        charset: 'utf-16',
      },
    },
})    

Alternatively, you can always type out the full meta tag

After - Your page

useHead({
  meta: [
    { name: 'viewport', content: 'width=device-width, initial-scale=2' },
    { charset: 'utf-16' }
  ],
})

📝 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

[netlify]

✅ Deploy Preview for nuxt3-docs canceled.

Name	Link
🔨 Latest commit	b21a8ce
🔍 Latest deploy log	https://app.netlify.com/sites/nuxt3-docs/deploys/6346ddc8973f0a00093f0e6e

[harlan-zw]

Still working on this and want to build out full tests, feel free to review the code but it may change

[jgupta]

It would be very nice if this could be part of rc12.

[socket-security]

Socket Security Report

👍 No new dependency issues detected in pull request

Socket.dev scan summary

Issue	Status
Did you mean?	✅ no new possible package typos
Install scripts	✅ no new install scripts
Telemetry	✅ no new telemetry
Troll package	✅ no new troll packages
Malware	✅ no new malware
Native code	✅ no new native modules

Bot Commands

To ignore an alert, reply with a comment starting with @SocketSecurity ignore followed by a space separated list of package-name@version specifiers. e.g. @SocketSecurity ignore foo@1.0.0 bar@2.4.2

⚠️ Please accept the latest app permissions to ensure bot commands work properly. Accept the new permissions here.

Powered by socket.dev

[danielroe]

This is very exciting ❤️ A few comments below.

[danielroe]

My only worry is if there are any bugs in @vueuse/head it will be difficult to fix them until the next Nuxt release. If you're happy to commit to no (intended) breaking changes between rc5 -> v1 then maybe we could consider ~ constraint?

wdyt @antfu?

[nicooprat]

I just migrated to latest Nuxt "nuxt": "3.0.0-rc.12", & Nuxt Content "@nuxt/content": "2.2.0", but it seems I still can't import useHeadRaw:

Did I miss something?

Thanks!

[harlan-zw]

I just migrated to latest Nuxt "nuxt": "3.0.0-rc.12", & Nuxt Content "@nuxt/content": "2.2.0", but it seems I still can't import useHeadRaw:

Did I miss something?

Thanks!

Hey @nicooprat

By default in the latest RC of @vueuse/head, all input is deemed raw.

There is an exposed function called useHeadSafe which would be used if you are inserting data from an untrusted source. If it's coming from nuxt/content you're probably fine to just use useHead. See v1 docs https://github.com/vueuse/head/tree/v1

Nuxt does not have this composable (yet), if you have any more questions on it please make an issue on the @vueuse/head repo.

[nicooprat]

Thanks for your answer.

I just understood that I was looking at the wrong version of the docs, the correct ones are from the latest RC tag: https://github.com/vueuse/head/tree/v1.0.0-rc.12

So useHeadRaw has been replaced by useHeadSafe. I successfully imoprted my analytics script this way:

if (process.client) {
  useHeadSafe({
    script: [
      {
        children: '...'
      },
    ],
  });
}