feat(content): add defineRobotsSchema() composable (#283)

Author: harlan-zw

docs/content/3.advanced/3.content.md

@@ -9,22 +9,22 @@ Nuxt Robots comes with an integration for Nuxt Content that allows you to config
 
 ## Setup Nuxt Content v3
 
-In Nuxt Content v3 we need to use the `asRobotsCollection()`{lang="ts"} function to augment any collections
-to be able to use the `robots` frontmatter key.
+Add `defineRobotsSchema()`{lang="ts"} to your collection's schema to enable the `robots` frontmatter key.
 
 ```ts [content.config.ts]
 import { defineCollection, defineContentConfig } from '@nuxt/content'
-import { asRobotsCollection } from '@nuxtjs/robots/content'
+import { defineRobotsSchema } from '@nuxtjs/robots/content'
+import { z } from 'zod'
 
 export default defineContentConfig({
   collections: {
-    content: defineCollection(
-      // adds the robots frontmatter key to the collection
-      asRobotsCollection({
-        type: 'page',
-        source: '**/*.md',
+    content: defineCollection({
+      type: 'page',
+      source: '**/*.md',
+      schema: z.object({
+        robots: defineRobotsSchema(),
       }),
-    ),
+    }),
   },
 })
 ```

src/content.ts

@@ -1,11 +1,49 @@
 import type { Collection } from '@nuxt/content'
 import { z } from 'zod'
 
+const robotsFieldSchema = z.union([z.string(), z.boolean()]).optional()
+
+function withEditorHidden<T extends z.ZodTypeAny>(s: T): T {
+  // .editor() is patched onto ZodType by @nuxt/content at runtime
+  if (typeof (s as any).editor === 'function')
+    return (s as any).editor({ hidden: true })
+  return s
+}
+
+export interface DefineRobotsSchemaOptions {
+  /**
+   * Pass the `z` instance from `@nuxt/content` to ensure `.editor({ hidden: true })` works
+   * across Zod versions. When omitted, the bundled `z` is used (`.editor()` applied if available).
+   */
+  z?: typeof z
+}
+
+/**
+ * Define the robots schema field for a Nuxt Content collection.
+ *
+ * @example
+ * defineCollection({
+ *   type: 'page',
+ *   source: '**',
+ *   schema: z.object({
+ *     robots: defineRobotsSchema()
+ *   })
+ * })
+ */
+export function defineRobotsSchema(options?: DefineRobotsSchemaOptions) {
+  const _z = options?.z ?? z
+  const s = _z.union([_z.string(), _z.boolean()]).optional()
+  return withEditorHidden(s)
+}
+
+// Legacy schema export (wraps entire collection)
 export const schema = z.object({
-  robots: z.union([z.string(), z.boolean()]).optional(),
+  robots: withEditorHidden(robotsFieldSchema),
 })
 
+/** @deprecated Use `defineRobotsSchema()` in your collection schema instead. See https://nuxtseo.com/robots/advanced/content */
 export function asRobotsCollection<T>(collection: Collection<T>): Collection<T> {
+  console.warn('[robots] `asRobotsCollection()` is deprecated. Use `defineRobotsSchema()` in your collection schema instead. See https://nuxtseo.com/robots/advanced/content')
   if (collection.type === 'page') {
     // @ts-expect-error untyped
     collection.schema = collection.schema ? schema.extend(collection.schema.shape) : schema

test/e2e/nuxt-content-v3-define-schema.test.ts

@@ -0,0 +1,29 @@
+import { createResolver } from '@nuxt/kit'
+import { $fetch, setup } from '@nuxt/test-utils'
+import { describe, expect, it } from 'vitest'
+
+const { resolve } = createResolver(import.meta.url)
+
+await setup({
+  rootDir: resolve('../fixtures/content-v3-define-schema'),
+})
+
+describe('nuxt/content v3 defineRobotsSchema', () => {
+  it('renders robots meta from content frontmatter', async () => {
+    const barHtml = await $fetch('/bar')
+    expect(String(barHtml).match(/<meta name="robots" content="([^"]+)">/)).toMatchInlineSnapshot(`
+      [
+        "<meta name="robots" content="test">",
+        "test",
+      ]
+    `)
+
+    const fooHtml = await $fetch('/foo')
+    expect(String(fooHtml).match(/<meta name="robots" content="([^"]+)">/)).toMatchInlineSnapshot(`
+      [
+        "<meta name="robots" content="noindex, nofollow">",
+        "noindex, nofollow",
+      ]
+    `)
+  }, 60000)
+})

test/fixtures/content-v3-define-schema/.nuxtrc

@@ -0,0 +1,2 @@
+imports.autoImport=true
+typescript.includeWorkspace=true

test/fixtures/content-v3-define-schema/app.vue

@@ -0,0 +1,3 @@
+<template>
+  <NuxtPage />
+</template>

test/fixtures/content-v3-define-schema/content.config.ts

@@ -0,0 +1,16 @@
+import { defineCollection, defineContentConfig } from '@nuxt/content'
+import { defineRobotsSchema } from '../../../src/content'
+import { z } from 'zod'
+
+export default defineContentConfig({
+  collections: {
+    content: defineCollection({
+      type: 'page',
+      source: '**/*.md',
+      schema: z.object({
+        date: z.string().optional(),
+        robots: defineRobotsSchema(),
+      }),
+    }),
+  },
+})

test/fixtures/content-v3-define-schema/content/bar.md

@@ -0,0 +1,6 @@
+---
+path: /bar
+robots: "test"
+---
+
+# bar

test/fixtures/content-v3-define-schema/content/foo.md

@@ -0,0 +1,7 @@
+---
+path: '/foo'
+robots: false
+date: 2026-10-10
+---
+
+# foo

test/fixtures/content-v3-define-schema/content/index.md

@@ -0,0 +1,4 @@
+---
+---
+
+# index

test/fixtures/content-v3-define-schema/nuxt.config.ts

@@ -0,0 +1,13 @@
+import NuxtRobots from '../../../src/module'
+
+export default defineNuxtConfig({
+  modules: [
+    NuxtRobots,
+    '@nuxt/content',
+  ],
+
+  site: {
+    url: 'https://nuxtseo.com',
+  },
+  compatibilityDate: '2024-12-06',
+})