@nuxtjs/robots
Covers @nuxtjs/robots 7. Runtime behaviour was tested with 6.2.4 on Nuxt 4.6.0; version 7 changes are listed under Version limits.
The module serves /robots.txt, sends X-Robots-Tag, and adds <meta name="robots"> to each SSR page.
Site config decides if the whole site is indexable. Route rules decide per path.
Setup
// nuxt.config.ts
import { defineNuxtConfig } from 'nuxt/config'
export default defineNuxtConfig({
modules: ['@nuxtjs/robots'],
site: { url: 'https://example.com' },
})Included in @nuxtjs/seo v6. If the app uses @nuxtjs/seo, configure the robots key and do not add the module again.
Site-wide indexing is a site key (nuxt-site-config), not a robots key.
Automatic behaviour
- The site is indexable if
site.indexableis true. If it is unset, the site is indexable when the siteenvisproduction.nuxt devis not indexable.nuxt buildandnuxt generateare. - Indexable: robots.txt is
User-agent: *and an emptyDisallow:. Pages getindex, follow, max-image-preview:large, max-snippet:-1, max-video-preview:-1. - Not indexable: robots.txt is
Disallow: /. Every response getsX-Robots-Tag: noindex, nofollow, including API routes,/robots.txt, and/_nuxt/files. /_nuxt/**always getsX-Robots-Tag: noindex.- The module merges a hand-written robots.txt from
public/_robots.txtorrobots.txtin the project root, or fromassets/robots.txtorpages/robots.txtinsrcDir(app/on Nuxt 4). Nuxt renamespublic/robots.txttopublic/_robots.txtin your source tree each time it loads the module,nuxt prepareincluded. nuxt generateprerenders/robots.txt. A static preset that reads_headers, such as Netlify, gets the header rules there.- To turn parts off, set
robots.robotsTxt,robots.header, orrobots.metaTagtofalse.useRobotsRule()still writes a meta tag whenmetaTagisfalse.robots.enabled: falseturns off everything, and the composables do nothing.
Common tasks
Keep paths out of search results. By default, a route rule does not change robots.txt.
// nuxt.config.ts
import { defineNuxtConfig } from 'nuxt/config'
export default defineNuxtConfig({
modules: ['@nuxtjs/robots'],
site: { url: 'https://example.com' },
// Only needed for defineRouteRules() in a page.
experimental: { inlineRouteRules: true },
routeRules: {
'/admin/**': { robots: false }, // robotsDisabledValue: noindex, nofollow
'/tags/**': { robots: 'noindex, follow' },
'/docs/**': { robots: { 'index': true, 'max-snippet': 120 } },
},
})Decide per request, during SSR. Route rules cannot match a query string:
<!-- app/pages/search.vue -->
<script setup lang="ts">
import { useRobotsRule, useRoute } from '#imports'
const route = useRoute()
// A string rule replaces the default rule for this response.
if (route.query.q)
useRobotsRule('noindex, follow')
</script>
<template>
<div>Search</div>
</template>With experimental.inlineRouteRules, defineRouteRules({ robots: false }) in a page sets a static rule.
Keep staging out of search: set NUXT_SITE_ENV=staging or NUXT_SITE_INDEXABLE=false. The Node server reads both at runtime.
For nuxt generate, set NUXT_SITE_INDEXABLE=false at build time. NUXT_SITE_ENV=staging there blocks robots.txt and the meta tags, but _headers gets no site-wide noindex rule.
Remove a live site from search: add the route rule '/**': { robots: 'noindex, nofollow' }. A more specific robots route rule, or a useRobotsRule() call, still wins over it.
Do not use site.indexable: false for this. Its Disallow: / stops crawlers before they read noindex.
Write robots.txt rules:
// nuxt.config.ts
import { defineNuxtConfig } from 'nuxt/config'
export default defineNuxtConfig({
modules: ['@nuxtjs/robots'],
site: { url: 'https://example.com' },
robots: {
disallow: ['/admin'],
allow: ['/admin/login'],
sitemap: '/sitemap.xml', // made absolute with site.url
blockAiBots: 'training', // Training opt-out. Use true to also block AI search and user fetches.
groups: [
{ userAgent: ['Googlebot'], disallow: ['/private'], comment: ['Google only'] },
],
},
})Import server functions from #robots/server and app composables from #robots/app. Auto-imports also work.
Do not import server functions from #imports. On Nuxt 4.6, that fails nuxt typecheck.
Turn off indexing for one host of a multi-domain deployment. This is per request:
// server/plugins/robots-host.ts
import { getNitroOrigin } from '#site-config/server'
export default defineNitroPlugin((nitroApp) => {
nitroApp.hooks.hook('site-config:init', ({ event, siteConfig }) => {
if (new URL(getNitroOrigin(event)).hostname.startsWith('staging.'))
siteConfig.push({ _context: 'staging-host', indexable: false })
})
})In Nitro, getSiteRobotConfig(event) returns { indexable, hints }. getPathRobotConfig(event, { path }) returns { indexable, rule, debug }.
Detect bots from the User-Agent header:
// server/middleware/block-bots.ts
import { createError, defineEventHandler } from 'nuxt/server'
import { getBotDetection } from '#robots/server'
export default defineEventHandler((event) => {
const bot = getBotDetection(event) // { isBot, botName, botCategory, trusted }
// Search engines and AI crawlers count as trusted. To block AI crawlers, test bot.botCategory === 'ai'.
if (event.url.pathname.startsWith('/api/') && bot.isBot && !bot.trusted)
throw createError({ status: 403 })
})In the app, useBotDetection() returns the same fields as computed refs.
useBotDetection({ fingerprint: true }) also runs BotD in the browser. Its result arrives later, so watch isBot.
Outside Nuxt, getBotDetection(headers) from @nuxtjs/robots/util accepts a Headers instance or a plain header object.
Integrations
Nuxt Content v3 frontmatter and Nuxt i18n path expansion: references/integrations.md.
Traps
- A path can be crawlable and noindex, or blocked in robots.txt. It cannot be both. Google never reads
noindexon a disallowed URL and can still index it from links. useRobotsRule(true)keepsnoindexwhen the site is not indexable. To force a rule, pass the string, such asuseRobotsRule('index, follow').useRobotsRule(null)anduseRobotsRule(undefined)keep the existing rule.useRobotsRule()sets the rule only during SSR. In the browser it only reads the rendered value.noaiornoimageaimakes a path non-indexable to the module, even withindex: true.getPathRobotConfigreturnsindexable: false, anddisallowNonIndexableRoutesdisallows the path.- An
app.baseURLother than/turns off robots.txt and logs an error. Crawlers only read/robots.txtat the host root. - Nuxt Content frontmatter
robotssets the meta tag. CalluseRobotsRule()to send the same rule in the header. See references/integrations.md. - The key is
blockAiBots, notblockAIBots. - Use
blockAiBots: 'training'to leave dedicated AI search and user fetch agents unblocked. Existing rules still apply. - Training mode includes Google-Extended, which also controls grounding in Gemini Apps and Vertex AI.
Version limits
Version 7 breaks these 6.x patterns:
- Nuxt 3 and Node 20 are unsupported. Use Nuxt
^4.6.0 || ^5.0.0and Node^22.22.3 || ^24.15.0 || >=26.0.0. #internal/nuxt-robotsis removed. Import from#robots/serveror#robots/app.- Hook events are
RequestEventfromnuxt/server. Readctx.event.req.headers.get('host'), notctx.event.headersorevent.node.req. - A
robots:configedit made withctx.eventchanges only that/robots.txtresponse. For per host indexing, use thesite-config:initplugin above. - A route rule beats
definePageMeta({ robots })on the same path. assets/robots.txtandpages/robots.txtload fromsrcDir. On Nuxt 4, move them intoapp/.- Nuxt Content v2 is unsupported, and Nuxt fails at startup with a version error. Upgrade to Nuxt Content v3.
- For Zod collections, import
defineRobotsSchema()from@nuxtjs/robots/contentand installzod^4.6.5. - The DevTools panel needs
nuxtseo-devtools-hostas a dev dependency:pnpm add -D nuxtseo-devtools-host.
Config
All options: nuxtseo.com/docs/robots/api/config. Options that are easy to miss:
robotsEnabledValueandrobotsDisabledValue: the rule strings for indexable and non-indexable paths.mergeWithRobotsTxtPath: a robots.txt path to merge, relative to the root, orfalse.cacheControl: the robots.txtCache-Control. The default ismax-age=14400, must-revalidate. Dev always sendsno-store.
Debug
- In dev, add
?mockProductionEnvto a URL to see the production rules. The meta tag shows the rule source indata-hint. /__robots__/debug-path.json?path=/admin&mockProductionEnv=truereturns the rule, its source, and the header./__robots__/debug.jsonreturns robots.txt, the indexable hints, and the resolved config. Both routes exist in dev, or withrobots.debug: true.