△ nuxt-unhead

Experimental features for Nuxt v3 head management. Powered by Unhead.

Status: Stable Please report any issues 🐛 Made possible by my Sponsor Program 💖 Follow me @harlan_zw 🐦 • Join Discord for help

ℹ️ Looking for a complete SEO solution? Check out Nuxt SEO Kit.

Features

Unlock all Unhead features and more:

• 🖥️ 0kb runtime tags useServerHead
• ✨ Automatic social share meta tags
• 🤖 Debug head tags component DebugHead
• 🌳 Fully typed Head Schema with href and src file auto-completion
• 🧩 Title template tokens: Use public runtime config in your templates: %s %titleSeperator %siteName.
• 🪝 Runtime hooks: head:tags, head:entries
• 📦 Load your asset files directly using aliases href: '~/assets/style.css' (Experimental)

Background

This module was built to test bug fixes as well as experimental new features which may land into the Nuxt core.

Install

npm install --save-dev nuxt-unhead# Using yarnyarn add --dev nuxt-unhead

Setup

nuxt.config.ts

export default defineNuxtConfig({  modules: [    'nuxt-unhead',  ],})

Module Configuration

Config key: unhead

nuxt.config.ts

export default defineNuxtConfig({  modules: ['nuxt-unhead'],  unhead: {    // config (see below)  },  //...})

Usage

Runtime Config Template Tokens

When defining your titleTemplate, title or meta content as strings, you can use tokens to reference values from your resolved runtime config.

For example, the default title template introduced by this module is %s %titleSeparator %siteName.

This uses the following:

• %s - The title of the page.
• %titleSeparator - runtimeConfig.public.titleSeparator
• %siteName - runtimeConfig.public.siteName

To provide the values for these tokens, you can update them in your nuxt config.

nuxt.config.ts

export default defineNuxtConfig({  runtimeConfig: {    public: {      siteName: 'My cool site',      titleSeparator: '|',    }  },})

Taking this further, we can see how we can handle complex tokenization.

nuxt.config.ts

export default defineNuxtConfig({  app: {    head: {      // dev | My page title | My cool site      titleTemplate: `%envName %titleSeperator %s %titleSeperator %siteName`,      meta: [        {          name: 'description',          // Hi, welcome to the dev v1.3.1 of Nuxt Playground.          content: 'Hi, welcome to the %envName v%app.version of %siteName.',        }      ]    }  },  runtimeConfig: {    public: {      app: {        version: process.env.npm_package_version,      },      titleSeparator: '|',      siteName: 'My cool site',      envName: process.env.NODE_ENV === 'development' ? 'dev' : 'live',    }  }})

The titleSeperator token is unique in that it will be trimmed from the start and end of the title.

Any missing tokens will be replaced with an empty string.

Config

seoOptimise

• Type: boolean
• Default: true
  Automatically optimise meta tags for SEO.
  It will automatically infer the og:title, og:description when a title and description are set respectively. It will ensure a twitter:card is set to summary_large_image if not set.
  This will do more in the future.

resolveAliases - EXPERIMENTAL

• Type: boolean
• Default: false
  Resolve aliases in href and src attributes. This will allow you to load your asset files directly using aliases.

  <script lang="ts" setup>useHead({  link: [    {      rel: 'stylesheet',      href: '~/assets/style.css',    },  ]})</script>

  Copy to clipboard

ogTitleTemplate

• Type: string
• Default: %s
  Template for the og:title meta tag. This will be used when inferring the og:title from title.

  defineNuxtConfig({  unhead: {    ogTitleTemplate: '%pageTitle - %siteName',  },})

  Copy to clipboard

  <script lang="ts" setup>useHead({  // og:title will be "My Title - My cool site"  title: 'My Title',})</script>

  Copy to clipboard

ogDescriptionTemplate

• Type: string
• Default: %s
  Template for the og:description meta tag. This will be used when inferring the og:description from description.

  defineNuxtConfig({  unhead: {    ogDescriptionTemplate: '%s. Check out my cool site',  },})

  Copy to clipboard

  <script lang="ts" setup>useHead({  // og:description will be "My Description. Check out my cool site"  meta: [ { name: 'description', content: 'My Description' } ],})</script>

  Copy to clipboard

Components

DebugHead

A component to debug your head tags.

<template>  <DebugHead /></template>

Sponsors

License

MIT License © 2022-PRESENT Harlan Wilton