Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 32 ยท Components and styling

Head, SEO and assets

Control the page title, meta tags and Open Graph data with useHead and useSeoMeta, add canonical links, sitemaps and robots rules, and place files in public or assets.

Search engines and social networks do not look at your page the way people do. They read the HTML: the <title>, the description, the canonical link, the Open Graph tags that decide how a link looks when pasted into a chat. Because Nuxt renders pages on the server, all of that can be present in the very first response, which is a large part of why people choose Nuxt for content sites.

This lesson covers the composables that set those tags, the modules that produce a sitemap and a robots file, and the other half of "assets": where to put images, fonts and other files. The real Nuxt code is read-only because the sandbox cannot run Nuxt. The runnable examples are stand-ins written in plain Node.js that render head tags to HTML, so you can see exactly what the real composables produce and how conflicts between tags are resolved.

What goes in the head

Title The tab text and the search result headline.
Description The snippet under the headline.
Open Graph The preview card for shared links.
Canonical The one true URL of the page.
1 / 2

useHead

useHead adds anything to the document head: the title, meta tags, links, scripts, and attributes on <html> and <body>.

VUE
<script setup lang="ts">
// real Nuxt code, read-only
useHead({
  title: 'Pricing',
  htmlAttrs: { lang: 'en' },
  meta: [{ name: 'description', content: 'Plans and prices for every team size.' }],
  link: [{ rel: 'canonical', href: 'https://example.com/pricing' }],
})
</script>

The values may be refs or getter functions, so the head updates when data changes. Call it in any component: Nuxt collects the entries from the whole page, and the server writes them into the HTML. When two entries describe the same tag (for example, two descriptions), the one registered later, usually the page rather than the layout, wins. Defaults for the whole site go into nuxt.config.ts:

TypeScript
// nuxt.config.ts (real Nuxt code, read-only)
export default defineNuxtConfig({
  app: {
    head: {
      htmlAttrs: { lang: 'en' },
      titleTemplate: '%s | Example Shop',
      meta: [{ name: 'viewport', content: 'width=device-width, initial-scale=1' }],
    },
  },
})

titleTemplate

titleTemplate wraps every page title, so each page only supplies its own part. With the template above, a page that sets title: 'Pricing' produces Pricing | Example Shop. The %s marks where the title goes. It can also be a function, for example to drop the suffix on the home page. If a page sets no title, the template is skipped and only the site's default shows, so check that every page sets one.

useSeoMeta

Writing <meta property="og:title"> by hand is easy to get wrong: some tags use name, others property, and one typo makes a tag silently useless. useSeoMeta takes flat, typed keys and builds the right tags:

VUE
<script setup lang="ts">
// real Nuxt code, read-only
useSeoMeta({
  title: 'Pricing',
  description: 'Plans and prices for every team size.',
  ogTitle: 'Example Shop pricing',
  ogDescription: 'Plans and prices for every team size.',
  ogImage: 'https://example.com/images/pricing-card.png',
  twitterCard: 'summary_large_image',
})
</script>

Keys like ogTitle become <meta property="og:title">, and twitterCard becomes <meta name="twitter:card">. Because the keys are typed, your editor autocompletes them and flags mistakes.

A few quality rules that apply regardless of tool:

  • One page, one unique title and description. Duplicated titles across a site make results look the same.
  • Keep titles to roughly 60 characters and descriptions between 120 and 160, or search engines will cut them.
  • og:image must be an absolute URL (with https://). Social networks fetch it themselves, so a relative path does not work.
  • Add a canonical link when the same content is reachable through several URLs (query strings, trailing slashes). Use useRequestURL() or a siteUrl value from runtimeConfig (see Runtime config and environment variables) to build absolute URLs.
  • Use data you already loaded: useSeoMeta({ title: () => post.value?.title }) after a useFetch call.

A runnable stand-in: rendering head tags

The stand-in below does what Nuxt's head manager does in spirit: it gathers entries from a layout and a page, resolves conflicts (the later entry wins, keyed by tag identity), applies the title template, escapes values, and prints the HTML. Real parts: the entry shapes (title, titleTemplate, meta, link, htmlAttrs), the template with %s, and "later wins". Model parts: the renderer itself, which is far simpler than the real one.

Note the escaping. A title that contains <script> must appear as text, never as a tag.

Node.js Merging head entries into HTML

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The page description replaced the default one, the title received the template, and the hostile title turned into harmless text.

Sitemap and robots

Two small files help crawlers: a sitemap (a list of the URLs you want indexed) and robots rules (what crawlers may fetch). You can write public/robots.txt by hand. For anything dynamic, use modules, installed by adding them to modules in nuxt.config.ts:

TypeScript
// nuxt.config.ts (real Nuxt code, read-only)
export default defineNuxtConfig({
  modules: ['@nuxtjs/sitemap', '@nuxtjs/robots'],
  site: { url: 'https://example.com', name: 'Example Shop' },
})

@nuxtjs/sitemap builds /sitemap.xml from your routes (dynamic URLs can be added from an API or a database through its sources option), and @nuxtjs/robots serves /robots.txt and can add noindex rules per route. nuxt-og-image generates share images, and the @nuxtjs/seo package bundles several of these. Check each module's current documentation for option names, as they change between versions.

Remember that noindex pages belong in neither the sitemap nor your internal links. The second stand-in generates a sitemap and a robots file from a list of routes and checks titles and descriptions against the length rules above.

Node.js Sitemap, robots.txt and a title and description check

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Assets: public or assets?

Nuxt has two homes for files, and the difference is whether the build tool processes them.

Folder Behavior Use it for
public/ Served at the site root exactly as it is: public/robots.txt is /robots.txt. No processing, no hashing. Files whose URL must stay fixed: favicon.ico, robots.txt, verification files, large downloads, social images.
assets/ Processed by the build tool: imported through ~/assets/..., hashed file names, small files can be inlined, CSS is bundled. CSS, fonts and images that your components import.
VUE
<template>
  <!-- from public/: absolute path, not processed -->
  <img src="/logo.svg" alt="Example Shop" width="160" height="40">
  <!-- from assets/: processed and given a hashed name in production -->
  <img src="~/assets/images/hero.jpg" alt="A desk by a window" width="1200" height="600">
</template>

Always give images width and height (or a CSS aspect ratio) so the browser reserves space before they load; otherwise the page jumps as they appear.

NuxtImg

The @nuxt/image module adds <NuxtImg> and <NuxtPicture>. They take care of resizing, modern formats and lazy loading, either with a built-in image processor or through an image CDN provider:

VUE
<template>
  <NuxtImg src="/images/hero.jpg" width="800" height="400" format="webp" loading="lazy" alt="A desk by a window" />
</template>

It is worth adopting once a page has more than a handful of photos. See Performance and Core Web Vitals for how images affect loading metrics. If you want to understand the plain HTML underneath, see the lessons on responsive images in the HTML tutorial.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does server rendering help SEO tags?

    Because the server writes the head into the HTML, crawlers and share-card fetchers can read the tags immediately.
  2. 2. A layout sets a description and a page calls useSeoMeta with another description. What is rendered?

    Head entries are merged by tag identity and the later one replaces the earlier one.
  3. 3. What does titleTemplate: '%s | Example Shop' do for a page titled 'Pricing'?

    %s is replaced by the page's title.
  4. 4. Where should robots.txt and a fixed-name favicon.ico live?

    public/ files keep their names and are served from the root. assets/ files are processed and renamed.
  5. 5. Why must og:image be an absolute URL?

    A relative path like /card.png has no meaning to a crawler that is not browsing your site.

Summary

  • useHead controls anything in the head; useSeoMeta gives typed, flat keys for SEO and social tags. Set them per page, with defaults in app.head.
  • titleTemplate wraps page titles; keep titles near 60 characters and descriptions at 120 to 160, and make og:image and canonical URLs absolute.
  • Server rendering puts the tags into the first HTML, so crawlers see them. The later entry for the same tag wins.
  • @nuxtjs/sitemap and @nuxtjs/robots generate crawler files; keep noindex pages out of the sitemap.
  • Use public/ for files with fixed URLs and assets/ for files the build should process; @nuxt/image gives you <NuxtImg>.

Next: Styling in Nuxt