Nuxt SEO Metadata

Nuxt SEO Metadata

Set page titles, Open Graph tags, canonical URLs, and structured data with useSeoMeta and useHead

When to Use

• You need to set unique <title>, <meta description>, or OG tags per page
• You are implementing social sharing previews (og:image, twitter:card)
• You need to configure robots directives or canonical URLs
• You are adding JSON-LD structured data for search engine rich results
• You want to set global defaults and override them per page

Instructions

useSeoMeta — typed meta tags (preferred):

1. Use useSeoMeta for all standard SEO and OG meta tags. It provides full TypeScript autocompletion and prevents common tag duplication mistakes:

// pages/product/[id].vue
useSeoMeta({
  title: product.name,
  description: product.description,
  ogTitle: product.name,
  ogDescription: product.description,
  ogImage: product.imageUrl,
  ogType: 'product',
  twitterCard: 'summary_large_image',
  twitterTitle: product.name,
  twitterImage: product.imageUrl,
});

2. Use useServerSeoMeta in SSR-only contexts for better performance (skips client-side hydration):

useServerSeoMeta({
  robots: 'index, follow',
  ogSiteName: 'My Site',
});

useHead — generic head management:

3. Use useHead for tags not covered by useSeoMeta (canonical, structured data, custom link tags):

useHead({
  link: [{ rel: 'canonical', href: `https://mysite.com${route.path}` }],
  script: [
    {
      type: 'application/ld+json',
      innerHTML: JSON.stringify({
        '@context': 'https://schema.org',
        '@type': 'Product',
        name: product.name,
        offers: { '@type': 'Offer', price: product.price },
      }),
    },
  ],
});

4. Set global defaults in app.vue or a layout, then override per page:

// app.vue
useHead({
  titleTemplate: (title) => (title ? `${title} — My Site` : 'My Site'),
  htmlAttrs: { lang: 'en' },
  meta: [{ name: 'theme-color', content: '#ffffff' }],
});

Reactive meta — computed values:

5. Pass computed refs or reactive values to update meta when data changes:

const { data: post } = await useAsyncData('post', () => fetchPost(id));

useSeoMeta({
  title: () => post.value?.title ?? 'Loading...',
  description: () => post.value?.excerpt,
  ogImage: () => post.value?.coverImage,
});

Robots configuration:

6. Configure robots globally in nuxt.config.ts:

export default defineNuxtConfig({
  app: {
    head: {
      meta: [{ name: 'robots', content: 'index, follow' }],
    },
  },
});

7. Block specific pages from indexing:

// pages/admin/settings.vue
useSeoMeta({ robots: 'noindex, nofollow' });

nuxt-site-config module:

8. For production-grade SEO including automatic canonical URLs, robots.txt, and sitemap integration, use the @nuxtjs/seo module family:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-site-config'],
  site: {
    url: 'https://mysite.com',
    name: 'My Site',
    defaultLocale: 'en',
  },
});

Details

useSeoMeta vs. useHead:

useSeoMeta is a higher-level abstraction built on top of useHead. It knows which meta tags belong in name vs. property attributes, prevents duplicate tags, and offers typed keys. Prefer it for all standard SEO and social meta. Use useHead for raw head control (scripts, links, custom attributes).

Tag deduplication:

Nuxt uses @unhead/vue under the hood. Tags are deduplicated by key — the most recently called composable wins. This means a page's useSeoMeta call overrides the layout's defaults without any explicit merge logic.

Open Graph image requirements:

• Minimum size: 1200x630px for optimal display
• Use absolute URLs (include the full https:// origin)
• For dynamic OG images, consider @nuxtjs/og-image which generates them at build time or on-demand

// With @nuxtjs/og-image
defineOgImage({
  component: 'MyOgImageTemplate',
  title: post.title,
  description: post.excerpt,
});

Structured data (JSON-LD) patterns:

Common schema types for Nuxt apps:

• Article — blog posts, news
• Product — e-commerce
• BreadcrumbList — navigation path
• Organization — company info in layout
• FAQPage — FAQ sections

Place organization-level JSON-LD in the default layout; page-specific data in individual pages.

Performance note:

useServerSeoMeta renders meta tags only during SSR and skips the client-side hydration step, reducing JavaScript execution. Use it for any meta that does not need to change after initial render.

Source

https://nuxt.com/docs/getting-started/seo-meta

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.