feat(content): add defineOgImageSchema() composable (#520)

harlan-zw · web-flow · commit e9cded097cf6 · 2026-03-24T01:27:37.000+11:00
diff --git a/docs/content/4.integrations/1.content.md b/docs/content/4.integrations/1.content.md
@@ -11,21 +11,22 @@ You can see a demo of this integration in the [Nuxt OG Image & Nuxt Content Play
 
 ## Setup Nuxt Content v3
 
-In Nuxt Content v3 we need to use the `asOgImageCollection()`{lang="ts"} function to augment any collections
-to be able to use the `ogImage` frontmatter key.
+Add `defineOgImageSchema()`{lang="ts"} to your collection's schema to enable the `ogImage` frontmatter key.
 
 ```ts [content.config.ts]
 import { defineCollection, defineContentConfig } from '@nuxt/content'
-import { asOgImageCollection } from 'nuxt-og-image/content'
+import { defineOgImageSchema } from 'nuxt-og-image/content'
+import { z } from 'zod'
 
 export default defineContentConfig({
   collections: {
-    content: defineCollection(
-      asOgImageCollection({
-        type: 'page',
-        source: '**/*.md',
+    content: defineCollection({
+      type: 'page',
+      source: '**/*.md',
+      schema: z.object({
+        ogImage: defineOgImageSchema(),
       }),
-    ),
+    }),
   },
 })
 ```
diff --git a/playground/content.config.ts b/playground/content.config.ts
@@ -1,16 +1,16 @@
-import { defineCollection, defineContentConfig, z } from '@nuxt/content'
-import { asOgImageCollection } from '../src/content'
+import { defineCollection, defineContentConfig } from '@nuxt/content'
+import { z } from 'zod'
+import { defineOgImageSchema } from '../src/content'
 
 export default defineContentConfig({
   collections: {
-    content: defineCollection(
-      asOgImageCollection({
-        type: 'page',
-        source: '**/*.md',
-        schema: z.object({
-          date: z.string().optional(),
-        }),
+    content: defineCollection({
+      type: 'page',
+      source: '**/*.md',
+      schema: z.object({
+        date: z.string().optional(),
+        ogImage: defineOgImageSchema(),
       }),
-    ),
+    }),
   },
 })
diff --git a/src/content.ts b/src/content.ts
@@ -1,17 +1,58 @@
 import type { Collection } from '@nuxt/content'
 import { z } from 'zod'
 
-export const ogImageSchema = z.object({
-  url: z.string().optional(),
-  component: z.string().optional(),
-  props: z.record(z.string(), z.any()),
-}).optional()
+function buildOgImageObjectSchema(_z: typeof z) {
+  return _z.object({
+    url: _z.string().optional(),
+    component: _z.string().optional(),
+    props: _z.record(_z.string(), _z.any()),
+  }).optional()
+}
+
+const ogImageObjectSchema = buildOgImageObjectSchema(z)
+
+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 DefineOgImageSchemaOptions {
+  /**
+   * 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 ogImage schema field for a Nuxt Content collection.
+ *
+ * @example
+ * defineCollection({
+ *   type: 'page',
+ *   source: '**',
+ *   schema: z.object({
+ *     ogImage: defineOgImageSchema()
+ *   })
+ * })
+ */
+export function defineOgImageSchema(options?: DefineOgImageSchemaOptions) {
+  const s = options?.z ? buildOgImageObjectSchema(options.z) : ogImageObjectSchema
+  return withEditorHidden(s)
+}
+
+// Legacy exports
+export const ogImageSchema = ogImageObjectSchema
 
 export const schema = z.object({
-  ogImage: ogImageSchema,
+  ogImage: withEditorHidden(ogImageObjectSchema),
 })
 
+/** @deprecated Use `defineOgImageSchema()` in your collection schema instead. See https://nuxtseo.com/og-image/integrations/content */
 export function asOgImageCollection<T>(collection: Collection<T>): Collection<T> {
+  console.warn('[og-image] `asOgImageCollection()` is deprecated. Use `defineOgImageSchema()` in your collection schema instead. See https://nuxtseo.com/og-image/integrations/content')
   if (collection.type === 'page') {
     // @ts-expect-error untyped
     collection.schema = collection.schema ? schema.extend(collection.schema.shape) : schema
