Skip to content

secondsky/claude-skills / plugins/nuxt-seo/skills/nuxt-seo

nuxt-seo

Verified

Nuxt SEO v5 modules (robots, sitemap, og-image, schema-org, link-checker, seo-utils, site-config). Use when implementing SEO, robots.txt, sitemaps, Schema.org, or meta tags in Nuxt apps.

references/nitro-api-reference.md

View on GitHub
# Nuxt SEO - Nitro API Reference

Server-side APIs for customizing SEO behavior at runtime using Nitro hooks and composables.

---

## Table of Contents

1. [Sitemap Nitro Hooks](#sitemap-nitro-hooks)
2. [OG Image Nitro Hooks](#og-image-nitro-hooks)
3. [Robots Nitro Composables](#robots-nitro-composables)
4. [defineSitemapEventHandler](#definesitemapeventhandler)
5. [Common Recipes](#common-recipes)

---

## Sitemap Nitro Hooks

Hooks for modifying sitemap output at runtime.

### sitemap:input

Triggered when raw URLs are collected. Best for adding new URLs.

```typescript
// server/plugins/sitemap.ts
import { defineNitroPlugin } from 'nitropack/runtime'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('sitemap:input', async (ctx) => {
    // Add string URL
    ctx.urls.push('/foo')

    // Add URL object
    ctx.urls.push({
      loc: '/bar',
      changefreq: 'daily',
      priority: 0.8,
    })
  })
})
```

**Type:**
```typescript
async (ctx: { urls: SitemapUrlInput[]; sitemapName: string }) => void | Promise<void>
```

### sitemap:resolved

Triggered after XML structure is generated. Best for modifying or removing entries.

```typescript
// server/plugins/sitemap.ts
import { defineNitroPlugin } from 'nitropack/runtime'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('sitemap:resolved', async (ctx) => {
    // Add URL to specific sitemap
    if (ctx.sitemapName === 'posts') {
      ctx.urls.push({
        loc: '/posts/my-post',
        changefreq: 'daily',
        priority: 0.8,
      })
    }

    // Filter URLs
    ctx.urls = ctx.urls.filter(url => !url.loc.includes('/private/'))
  })
})
```

**Type:**
```typescript
async (ctx: { urls: ResolvedSitemapUrl[]; sitemapName: string }) => void | Promise<void>
```

### sitemap:index-resolved

Triggered when sitemap index is generated.

```typescript
// server/plugins/sitemap.ts
import { defineNitroPlugin } from 'nitropack/runtime'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('sitemap:index-resolved', async (ctx) => {
    // Add external sitemap to index
    ctx.sitemaps.push({
      sitemap: 'https://mysite.com/my-sitemap.xml',
      lastmod: new Date().toISOString(),
    })
  })
})
```

**Type:**
```typescript
async (ctx: { sitemaps: { sitemap: string, lastmod?: string }[] }) => void | Promise<void>
```

### sitemap:output

Triggered before sending to client. Access raw XML string.

```typescript
// server/plugins/sitemap.ts
import { defineNitroPlugin } from 'nitropack/runtime'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('sitemap:output', async (ctx) => {
    // Append comment
    ctx.sitemap = `${ctx.sitemap}\n<!-- Generated by Nuxt SEO -->`

    // Add custom xmlns
    ctx.sitemap = ctx.sitemap.replace(
      '<urlset ',
      '<urlset xmlns:mobile="http://www.baidu.com/schemas/sitemap-mobile/1/" '
    )
  })
})
```

**Type:**
```typescript
async (ctx: { sitemap: string; sitemapName: string }) => void | Promise<void>
```

### sitemap:sources

Triggered before resolving sources. Modify source list dynamically.

```typescript
// server/plugins/sitemap.ts
import { defineNitroPlugin } from 'nitropack/runtime'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('sitemap:sources', async (ctx) => {
    // Add new source
    ctx.sources.push('/api/dynamic-urls')

    // Add auth headers from request
    ctx.sources = ctx.sources.map(source => {
      if (typeof source === 'object' && source.fetch) {
        const [url, options = {}] = Array.isArray(source.fetch)
          ? source.fetch
          : [source.fetch, {}]

        const authHeader = ctx.event.node.req.headers.authorization
        if (authHeader) {
          options.headers = options.headers || {}
          options.headers['Authorization'] = authHeader
        }
        source.fetch = [url, options]
      }
      return source
    })

    // Filter sources
    ctx.sources = ctx.sources.filter(source => {
      if (typeof source === 'string') {
        return !source.includes('skip-this')
      }
      return true
    })
  })
})
```

**Type:**
```typescript
async (ctx: {
  event: H3Event;
  sitemapName: string;
  sources: (SitemapSourceBase | SitemapSourceResolved)[]
}) => void | Promise<void>
```

---

## OG Image Nitro Hooks

Hooks for customizing OG image generation.

### nuxt-og-image:context

Modify render context before image generation.

```typescript
// server/plugins/ogImage.ts
import { defineNitroPlugin } from 'nitropack/runtime/plugin'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('nuxt-og-image:context', async (ctx) => {
    // Check path
    if (!ctx.e.path.startsWith('/fancy-og-images/'))
      return

    // Modify props
    ctx.options.props.isFancy = true

    // Set custom cache key
    ctx.key = 'fancy-og-images'
  })
})
```

**Type:**
```typescript
async (ctx: OgImageRenderEventContext) => void | Promise<void>
```

### nuxt-og-image:satori:vnodes

Modify Satori virtual nodes before rendering.

```typescript
// server/plugins/ogImage.ts
import { defineNitroPlugin } from 'nitropack/runtime/plugin'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('nuxt-og-image:satori:vnodes', async (vnodes) => {
    for (const child of vnodes.children) {
      // Modify class
      if (child.props?.class) {
        child.props.class = child.props.class.replace('icon', '')
      }
    }
  })
})
```

**Type:**
```typescript
async (vnodes: VNode[]) => void | Promise<void>
```

### OG Image Nuxt Hooks (Build-time)

#### nuxt-og-image:runtime-config

Modify OG Image config at build time.

```typescript
// nuxt.config.ts
export default defineNuxtConfig({
  hooks: {
    'nuxt-og-image:runtime-config': (config) => {
      config.colorPreference = 'dark'
    }
  }
})
```

#### nuxt-og-image:components

Modify available OG Image components.

```typescript
// nuxt.config.ts
export default defineNuxtConfig({
  hooks: {
    'nuxt-og-image:components': (ctx) => {
      // Remove community components
      ctx.components = ctx.components.filter(c => c.category !== 'community')

      // Add custom component
      const myComponentPath = resolve('./MyComponent.vue')
      const myComponentContents = fsp.readFile(myComponentPath)
      ctx.components.push({
        hash: hash(myComponentContents),
        pascalName: 'MyComponent',
        kebabName: 'my-component',
        path: nuxt.options.dev ? myComponentPath : undefined,
        category: 'community',
        credits: 'My Company',
      })
    }
  }
})
```

---

## Robots Nitro Composables

Server-side composables for checking indexability.

### getSiteRobotConfig()

Check if entire site is indexable.

```typescript
// server/routes/og.png.ts
import { getSiteRobotConfig } from '#imports'

export default defineEventHandler((e) => {
  const { indexable, hints } = getSiteRobotConfig(e)

  if (!indexable) {
    // Site is not indexable
    // hints array explains why
    console.log('Not indexable:', hints)
  }
})
```

**Returns:**
```typescript
{
  indexable: boolean  // Whether site is indexable
  hints: string[]     // Reasons for indexability status
}
```

### getPathRobotConfig()

Check if specific path is indexable.

```typescript
// server/plugins/strip-og-tags.ts
import { defineNitroPlugin, getPathRobotConfig } from '#imports'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('render:html', async (ctx, { event }) => {
    const { indexable, rule, debug } = getPathRobotConfig(event)

    if (!indexable) {
      // Strip OG tags for non-indexable pages
      ctx.html = ctx.html.replace(/<meta property="og:.*?">/g, '')
    }
  })
})
```

**Options:**
```typescript
interface GetPathRobotConfigOptions {
  userAgent?: string          // Check for specific user agent
  skipSiteIndexable?: boolean // Ignore site-wide config
  path?: string               // Override path to check
}
```

**Returns:**
```typescript
interface GetPathRobotResult {
  rule: string              // The robot rule (e.g., "noindex")
  indexable: boolean        // Whether path is indexable
  debug?: {                 // Only in development
    source: string          // Source of the rule
    line: string            // Line number in source
  }
}
```

### getBotDetection()

Access bot detection state in Nitro routes.

```typescript
// server/api/protected.ts
import { getBotDetection } from '#imports'

export default defineEventHandler((e) => {
  const botInfo = getBotDetection(e)

  if (botInfo?.isBot) {
    // Handle bot request differently
    return { cached: true, data: getCachedData() }
  }

  return { cached: false, data: getFreshData() }
})
```

---

## defineSitemapEventHandler

Type-safe handler for creating sitemap URL endpoints.

### Basic Usage

```typescript
// server/api/__sitemap__/urls.ts
import { defineSitemapEventHandler } from '#imports'
import type { SitemapUrlInput } from '#sitemap/types'

export default defineSitemapEventHandler(() => {
  return [
    {
      loc: '/about-us',
      _sitemap: 'pages',
    },
  ] satisfies SitemapUrlInput[]
})
```

### Async with API Fetch

```typescript
// server/api/__sitemap__/urls.ts
import { defineSitemapEventHandler } from '#imports'
import type { SitemapUrl } from '#sitemap/types'

export default defineSitemapEventHandler(async () => {
  const [posts, pages] = await Promise.all([
    $fetch<{ slug: string }[]>('https://api.example.com/posts')
      .then(posts => posts.map(p => ({
        loc: `/blog/${p.slug}`,
        _sitemap: 'posts',
      } satisfies SitemapUrl))),
    $fetch<{ path: string }[]>('https://api.example.com/pages')
      .then(pages => pages.map(p => ({
        loc: p.path,
        _sitemap: 'pages',
      } satisfies SitemapUrl))),
  ])

  return [...posts, ...pages]
})
```

### WordPress Example

```typescript
// server/api/__sitemap__/wordpress.ts
import { defineSitemapEventHandler } from '#imports'

export default defineSitemapEventHandler(async () => {
  const posts = await $fetch('https://example.com/wp-json/wp/v2/posts')

  return posts.map(post => ({
    loc: `/blog/${post.slug}`,  // NOT post.link
    lastmod: post.modified,
    changefreq: 'weekly',
    priority: 0.7,
  }))
})
```

### i18n Dynamic URLs

```typescript
// server/api/__sitemap__/urls.ts
import { defineSitemapEventHandler } from '#imports'
import type { SitemapUrl } from '#sitemap/types'

export default defineSitemapEventHandler(async () => {
  const config = useRuntimeConfig()
  const baseUrl = config.public.siteUrl
  const locales = config.public.i18n.locales.map(l => l.code)
  const isoLocales = Object.fromEntries(
    config.public.i18n.locales.map(l => ([l.code, l.iso]))
  )

  const apiQueries = locales.map(locale =>
    $fetch(`${config.public.apiEndpoint}/sitemap/${locale}/products`)
  )

  const sitemaps = await Promise.all(apiQueries)

  return sitemaps.flat().map(entry => ({
    _sitemap: isoLocales[entry.locale],
    loc: `${baseUrl}/${entry.locale}/product/${entry.url}`,
    alternatives: entry.alternates?.map(alt => ({
      hreflang: isoLocales[alt.locale],
      href: `${baseUrl}/${alt.locale}/product/${alt.url}`
    }))
  } satisfies SitemapUrl))
})
```

---

## Common Recipes

### Filter Videos by Host

```typescript
// server/plugins/sitemap.ts
import { defineNitroPlugin } from 'nitropack/runtime'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('sitemap:resolved', (ctx) => {
    ctx.urls.map((url) => {
      if (url.videos?.length) {
        url.videos = url.videos.filter((video) => {
          if (video.content_loc) {
            const parsedUrl = new URL(video.content_loc)
            return parsedUrl.host.startsWith('www.youtube.com')
          }
          return false
        })
      }
      return url
    })
  })
})
```

### Extract YouTube Videos from Prerender

```typescript
// nuxt.config.ts
import type { ResolvedSitemapUrl } from '#sitemap/types'

export default defineNuxtConfig({
  modules: [
    (_, nuxt) => {
      nuxt.hooks.hook('nitro:init', async (nitro) => {
        nitro.hooks.hook('prerender:generate', async (route) => {
          const html = route.contents
          const matches = html.match(/<iframe.*?youtube.com\/embed\/(.*?)".*?<\/iframe>/g)

          if (matches) {
            const sitemap = route._sitemap || {} as ResolvedSitemapUrl
            sitemap.videos = sitemap.videos || []

            for (const match of matches) {
              const videoId = match.match(/youtube.com\/embed\/(.*?)"/)[1]
              sitemap.videos.push({
                title: 'YouTube Video',
                description: 'A video from YouTube',
                content_loc: `https://www.youtube.com/watch?v=${videoId}`,
                thumbnail_loc: `https://img.youtube.com/vi/${videoId}/0.jpg`,
              })
            }
            route._sitemap = sitemap
          }
        })
      })
    },
  ],
})
```

### Strip OG Tags for Non-Indexable Pages

```typescript
// server/plugins/strip-og-tags.ts
import { defineNitroPlugin, getPathRobotConfig } from '#imports'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('render:html', async (ctx, { event }) => {
    const { indexable } = getPathRobotConfig(event)

    if (!indexable) {
      ctx.html = ctx.html.replace(/<meta property="og:.*?">/g, '')
    }
  })
})
```

### Disable OG Image Generation for Non-Indexable Sites

```typescript
// server/routes/og.png.ts
import { getSiteRobotConfig } from '#imports'

export default defineEventHandler((e) => {
  const { indexable } = getSiteRobotConfig(e)

  if (!indexable) {
    // Return placeholder or 404
    throw createError({
      statusCode: 404,
      message: 'OG Image not available'
    })
  }

  // Generate OG image normally
})
```

### Add Custom xmlns to Sitemap

```typescript
// server/plugins/sitemap.ts
import { defineNitroPlugin } from 'nitropack/runtime'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('sitemap:output', async (ctx) => {
    // Baidu mobile sitemap
    ctx.sitemap = ctx.sitemap.replace(
      '<urlset ',
      '<urlset xmlns:mobile="http://www.baidu.com/schemas/sitemap-mobile/1/" '
    )
  })
})
```

---

## Official Documentation

- **Sitemap Nitro Hooks**: https://nuxtseo.com/docs/sitemap/nitro-api/nitro-hooks
- **OG Image Nitro Hooks**: https://nuxtseo.com/docs/og-image/nitro-api/nitro-hooks
- **Robots Nitro API**: https://nuxtseo.com/docs/robots/nitro-api/get-site-robot-config
- **GitHub**: https://github.com/harlan-zw
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall