secondsky/claude-skills / plugins/nuxt-seo/skills/nuxt-seo
nuxt-seo
VerifiedNuxt 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.6 KB |
| assets/package-versions.json | config | 3.6 KB |
| references/advanced-configuration.md | markdown | 9.0 KB |
| references/advanced-seo-guides.md | markdown | 18.8 KB |
| references/ai-seo-tools.md | markdown | 10.9 KB |
| references/api-reference.md | markdown | 10.2 KB |
| references/best-practices.md | markdown | 5.4 KB |
| references/common-patterns.md | markdown | 12.7 KB |
| references/installation-guide.md | markdown | 7.2 KB |
| references/module-details.md | markdown | 14.2 KB |
| references/modules-overview.md | markdown | 9.6 KB |
| references/nitro-api-reference.md | markdown | 14.2 KB |
| references/nuxt-content-integration.md | markdown | 14.4 KB |
| references/og-image-guide.md | markdown | 13.5 KB |
| references/pro-modules.md | markdown | 6.8 KB |
| references/seo-guides.md | markdown | 24.7 KB |
| references/sitemap-advanced.md | markdown | 16.3 KB |
| references/troubleshooting.md | markdown | 5.7 KB |
| references/v5-migration-guide.md | markdown | 8.5 KB |
| scripts/init-nuxt-seo.shexecutable | script | 7.0 KB |
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |