unjs/unhead v1.1.0 on GitHub

1.1.0 is here and with it comes some exciting new features, significantly performance improvements a number of security improvements
and more!

👀 Highlights

🪄 Template Params (PR)

Allows you to add template parameters that can be referenced in other tags. This is useful for reducing boilerplate and for third-party integrations to provide runtime configuration.

useHead({
  templateParams: {
    seperator: '|',
    site: {
      name: 'My Site',
      url: 'https://example.com',
    }
  },
  titleTemplate: '%s %seperator %site.name',
  meta: [
    {
      property: 'og:url',
      content: '%site.url'
    },
    {
      property: 'og:image',
      content: '%site.url/image.png'
    }
  ]
})

Read docs

🦺 useHeadSafe (PR)

This release signifies a shift in how we deal with potential XSS issues. The useHeadSafe composable is now the recommended way to
add head data when the input is not trusted. The white-listed tags and attributes are significantly limited, as
there are many more XSS vectors than just script tags.

useHeadSafe({
  title: 'About',
  meta: [
    {
      name: 'description',
      content: 'My about page'
    }
  ]
})

Read docs

✨ Inner Content Changes (PR)

The previous recommendation for tag inner content was to use the children key. This worked well, but it was not clear what kind of
behaviour this would have in the DOM and SSR. children is now deprecated in favour of using textContent and innerHTML keys.

useHead({
  script: [
    // more obvious that this is dangerous  
    {  innerHTML: "console.log('hello world')" }
  ]
})

While dealing with tags, which will just be inner content such as <style> and <script>, shorthand input is now available.

useHead({
 // This will be converted to <style>body { background: red; }</style>
  style: [  'body { background: red; }'  ],
  //  shorthand urls are also supported: <script src="https://example.com/script.js"></script>
  script: [ 'https://example.com/script.js' ]
})

Read docs

Opt-in Performance: experimentalHashHydration (PR)

The experimentalHashHydration option is being introduced, it is opt-in. It offers some sites the ability to completely bypass the blocking CPU time for the client hydration of head tags. (between 5-25ms reduction)

createHead({
  experimentalHashHydration: true,
})

Opt-in Performance: UseSeoMetaTransform (PR)

The useSeoMeta function is a great addition for developer experience, but the code required to unpack the meta is around 2kb and in most cases is not needed at runtime. We add a custom Vite transformer which turns useSeoMeta into useHead.

import UnheadVite from '@unhead/addons/vite'

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

Changelog

compare changes

🚀 Enhancements

unhead: template params #111
unhead: improved inner content handling #109
unhead: useHeadSafe #113
addons: experimental UseSeoMetaTransform #117

🔥 Performance

dom lazily create dom elements #102
dom avoid expensive JSON.stringify #101

🩹 Fixes

unhead: data-* booleans no longer omitted #107
unhead: improved class normalising #108
unhead: deprecate shorthand composables #114