@djangocfg/nextjs 2.1.438 → 2.1.439

package/src/og-image/index.ts

@@ -1,6 +1,11 @@
-export type { OGImageParams, OGPreset, OGLayout } from './types'
-export { buildOgUrl } from './url'
-export { createOgMetadata, withOgImage } from './metadata'
-export type { WithOgImageOptions } from './metadata'
+// ── Recommended API ──────────────────────────────────────────────────────────
+// Bind the factory once per app, then call it from each page.
 export { createMetadata, makeMetadataFactory } from './metadata-factory'
 export type { SiteMetaConfig, PageMeta } from './metadata-factory'
+
+// ── Types ────────────────────────────────────────────────────────────────────
+export type { OGImageParams, OGPreset, OGLayout, OgSpec } from './types'
+
+// ── Low-level primitives (escape hatches) ────────────────────────────────────
+export { buildOgUrl } from './url'
+export { createOgMetadata, withOgImage, resolveOgImage, extractTitle } from './metadata'

package/src/og-image/metadata-factory.ts

@@ -1,6 +1,6 @@
 import type { Metadata } from 'next'
-import type { OGImageParams } from './types'
-import { withOgImage, type WithOgImageOptions } from './metadata'
+import type { OgSpec } from './types'
+import { resolveOgImage } from './metadata'
 
 /**
  * Site-wide identity the metadata factory needs. Config-agnostic on purpose —
@@ -18,32 +18,36 @@ export interface SiteMetaConfig {
   ogImage: string
   /** Optional favicon / apple-touch icons forwarded to Metadata.icons. */
   icons?: Metadata['icons']
-  /** Locales for hreflang alternates (first is treated as x-default if no enDefault). */
+  /** Locales for hreflang alternates. Omit for single-locale sites. */
   locales?: readonly string[]
   /** Locale used for x-default hreflang (defaults to "en" or first locale). */
   defaultLocale?: string
 }
 
-/** Per-page inputs. Everything is optional except what makes the page unique. */
+/**
+ * Per-page inputs. Only `title` is really worth setting per page; everything
+ * else falls back to the site config.
+ */
 export interface PageMeta {
-  /** Page title (without the brand suffix — the template adds it). */
+  /** Page title (without the brand suffix). Falls back to the site name. */
   title?: string
   /** Page description; falls back to the site description. */
   description?: string
   keywords?: string[]
   /** Current locale, used for canonical + openGraph.locale + alternates. */
   locale?: string
-  /** Path without locale prefix, e.g. "/skills". '' for home. Drives alternates. */
+  /** Path without locale prefix, e.g. "/skills". '' for home. */
   path?: string
   /**
-   * OG image control, forwarded to `withOgImage`:
-   * - omitted        → static brand image (`config.ogImage`) — the safe default
-   * - `true`         → dynamic render from the page title
-   * - OGImageParams  → dynamic render with explicit preset/layout/colors
-   * - `false`        → no image (inherit whatever the layout set)
-   * - string         → explicit image URL
+   * What the OG image should be. Defaults to `'static'` (the brand image).
+   * - `'static'`          brand image from config (default)
+   * - `'dynamic'`         render the page title onto the card
+   * - `{ render: {...} }` render with explicit preset/layout/colors
+   * - `{ image, alt? }`   an exact image URL (e.g. a content screenshot)
    */
-  og?: boolean | string | Omit<OGImageParams, 'title'>
+  og?: OgSpec
+  /** Escape hatch: extra Metadata fields merged last (robots, authors, etc.). */
+  extra?: Metadata
 }
 
 function buildAlternates(
@@ -52,26 +56,25 @@ function buildAlternates(
   locale: string
 ): Metadata['alternates'] {
   if (!config.locales?.length) {
-    return { canonical: `${config.siteUrl}/${locale}${path}` }
+    return { canonical: `${config.siteUrl}/${path}`.replace(/\/+$/, '') || config.siteUrl }
   }
   const languages: Record<string, string> = {}
   for (const loc of config.locales) {
     languages[loc] = `${config.siteUrl}/${loc}${path}`
   }
-  const xDefault = config.defaultLocale ?? (config.locales.includes('en') ? 'en' : config.locales[0])
+  const xDefault =
+    config.defaultLocale ?? (config.locales.includes('en') ? 'en' : config.locales[0])
   languages['x-default'] = `${config.siteUrl}/${xDefault}${path}`
   return { canonical: `${config.siteUrl}/${locale}${path}`, languages }
 }
 
 /**
- * Builds a complete Next.js `Metadata` object from a one-time site config plus
- * per-page inputs — title-template, description, openGraph, twitter, canonical
- * + hreflang alternates, and icons — so pages only declare what's unique.
- *
- * OG image defaults to the static brand image (`config.ogImage`); opt into the
- * dynamic renderer per page with `og: true` / `og: { preset: 'DARK_BLUE' }`.
+ * Builds a complete Next.js `Metadata` from a one-time site config plus per-page
+ * inputs — title-template, description, openGraph, twitter, canonical + hreflang,
+ * icons, and the OG image — so pages only declare what's unique.
  *
- * Bind the config once in your app, then call the bound fn from each page:
+ * The OG image is chosen by the single `og` field (defaults to the static brand
+ * image). There is exactly one way to do each thing.
  *
  *   // app/_core/metadata.ts
  *   export const createMetadata = makeMetadataFactory({
@@ -83,16 +86,25 @@ function buildAlternates(
  *     locales: LOCALES,
  *   })
  *
- *   // any page.tsx
- *   export const metadata = createMetadata({ title: 'Skills', path: '/skills' })
+ *   // landing page — static brand image (default)
+ *   export const metadata = createMetadata({ title: 'Pricing', path: '/pricing' })
+ *   // content page — title rendered onto the card
+ *   export const metadata = createMetadata({ title: post.title, path, og: 'dynamic' })
+ *   // content page with its own image
+ *   export const metadata = createMetadata({ title: p.name, og: { image: p.image } })
  */
 export function createMetadata(config: SiteMetaConfig, page: PageMeta = {}): Metadata {
   const title = page.title ?? config.name
   const description = page.description ?? config.description
   const locale = page.locale ?? config.defaultLocale ?? 'en'
   const path = page.path ?? ''
+  const ogUrl = config.locales?.length
+    ? `${config.siteUrl}/${locale}${path}`
+    : `${config.siteUrl}${path}`
 
-  const base: Metadata = {
+  const ogImage = resolveOgImage(page.og ?? 'static', config.ogImage, title)
+
+  const metadata: Metadata = {
     title,
     description,
     keywords: page.keywords,
@@ -100,41 +112,34 @@ export function createMetadata(config: SiteMetaConfig, page: PageMeta = {}): Met
     openGraph: {
       type: 'website',
       locale,
-      url: `${config.siteUrl}/${locale}${path}`,
+      url: ogUrl,
       siteName: config.name,
       title,
       description,
+      ...ogImage.openGraph,
     },
     twitter: {
-      card: 'summary_large_image',
       title,
       description,
+      ...ogImage.twitter,
     },
     icons: config.icons,
   }
 
-  // Resolve the `og` shorthand into withOgImage options.
-  let ogOptions: WithOgImageOptions
-  if (page.og === undefined || page.og === false) {
-    // Default & explicit-off both map to the static brand image. (false on the
-    // factory means "don't render dynamic" — but we still want a brand image,
-    // so we point at the static one. Use og:false at the page only if you've
-    // set images elsewhere; here static is the friendly default.)
-    ogOptions = { image: config.ogImage }
-  } else if (page.og === true) {
-    ogOptions = {} // dynamic, title auto-extracted
-  } else if (typeof page.og === 'string') {
-    ogOptions = { image: page.og }
-  } else {
-    ogOptions = page.og // OGImageParams → dynamic with overrides
+  if (!page.extra) return metadata
+  // Shallow-merge the escape hatch, but deep-merge the nested og/twitter so the
+  // image we just set isn't clobbered by a partial `extra.openGraph`.
+  return {
+    ...metadata,
+    ...page.extra,
+    openGraph: { ...metadata.openGraph, ...page.extra.openGraph },
+    twitter: { ...metadata.twitter, ...page.extra.twitter },
   }
-
-  return withOgImage(base, ogOptions)
 }
 
 /**
  * Curries `createMetadata` with a fixed site config so pages call a zero-config
- * factory. See the docstring on `createMetadata` for the usage pattern.
+ * factory. This is the single recommended entry point for app metadata.
  */
 export function makeMetadataFactory(config: SiteMetaConfig) {
   return (page: PageMeta = {}): Metadata => createMetadata(config, page)

package/src/og-image/metadata.ts

@@ -1,109 +1,88 @@
 import type { Metadata } from 'next'
-import type { OGImageParams } from './types'
+import type { OGImageParams, OgSpec } from './types'
 import { buildOgUrl } from './url'
 
+const OG_WIDTH = 1200
+const OG_HEIGHT = 630
+
+/** A Next.js OG image entry. */
+function imageEntry(url: string, alt: string) {
+  return { url, width: OG_WIDTH, height: OG_HEIGHT, alt }
+}
+
 /**
- * Creates Next.js Metadata fragment with og:image and twitter:image
- * pointing to Django's django_ogimage renderer.
- *
- * Usage in generateMetadata():
- *   return createOgMetadata({ title: 'Page', preset: 'DARK_BLUE' })
+ * Builds the og/twitter image fragment for a given image URL — the one place
+ * that knows the shape Next.js expects. Both static URLs and the dynamic
+ * renderer funnel through here, so there's a single source of truth.
  */
-export function createOgMetadata(params: OGImageParams): Metadata {
-  const url = buildOgUrl(params)
-  const image = { url, width: 1200, height: 630, alt: params.title }
+function ogImageFragment(url: string, alt: string): Pick<Metadata, 'openGraph' | 'twitter'> {
   return {
-    openGraph: {
-      images: [image],
-    },
-    twitter: {
-      card: 'summary_large_image',
-      images: [url],
-    },
+    openGraph: { images: [imageEntry(url, alt)] },
+    twitter: { card: 'summary_large_image', images: [url] },
   }
 }
 
 /**
- * Options for `withOgImage`. Extends the dynamic-renderer params with an
- * `image` opt-out so a page can keep its own (static) OG image instead of the
- * dynamically-rendered one.
+ * Metadata fragment whose OG image is rendered by Django's django_ogimage
+ * endpoint (/cfg/og/). Low-level — most callers use `createMetadata`'s `og`
+ * field instead.
  */
-export type WithOgImageOptions = Omit<OGImageParams, 'title'> & {
-  title?: string
-  /**
-   * Controls the OG image source:
-   * - omitted / `true` → dynamic render via Django's /cfg/og/ (default)
-   * - `false`          → don't touch images; the page/layout's own og:image
-   *                      is preserved (use for a ready-made static brand image)
-   * - `string`         → use this exact URL as a static og/twitter image
-   */
-  image?: boolean | string
+export function createOgMetadata(params: OGImageParams): Metadata {
+  return ogImageFragment(buildOgUrl(params), params.title)
+}
+
+/** Extract a plain title string from Next.js's title shapes. */
+export function extractTitle(metadata: Metadata): string {
+  const t = metadata.title
+  if (!t) return ''
+  if (typeof t === 'string') return t
+  if (typeof t === 'object' && 'absolute' in t) return (t as { absolute: string }).absolute
+  if (typeof t === 'object' && 'default' in t) return (t as { default: string }).default
+  return ''
 }
 
 /**
- * Merges og:image metadata into an existing Metadata object.
+ * Resolves an `OgSpec` against a base Metadata into a concrete og/twitter image
+ * fragment. `staticUrl` is the site's brand image, used for the `'static'` case.
+ * Returns `null` only if there's genuinely nothing to set.
  *
- * Usage:
- *   // dynamic (default)
- *   return withOgImage({ title: 'Page', description: '...' }, { preset: 'DARK_BLUE' })
- *   // keep the page's own static image
- *   return withOgImage(meta, { preset: 'DARK_BLUE', image: false })
- *   // explicit static image
- *   return withOgImage(meta, { image: '/static/ogimage.png' })
+ * This is the single decision point for "what is the OG image" — no other code
+ * branches on the spec.
  */
-export function withOgImage(
-  metadata: Metadata,
-  params: WithOgImageOptions = {}
-): Metadata {
-  const { image, ...ogParams } = params
-
-  // Opt-out: leave the incoming metadata's images untouched.
-  if (image === false) {
-    return metadata
+export function resolveOgImage(
+  spec: OgSpec,
+  staticUrl: string,
+  fallbackTitle: string
+): Pick<Metadata, 'openGraph' | 'twitter'> {
+  if (spec === 'static') {
+    return ogImageFragment(staticUrl, fallbackTitle)
   }
-
-  // Explicit static URL: set og/twitter images without hitting the renderer.
-  if (typeof image === 'string') {
-    return {
-      ...metadata,
-      openGraph: {
-        ...metadata.openGraph,
-        images: [{ url: image, width: 1200, height: 630, alt: extractTitle(metadata) }],
-      },
-      twitter: {
-        card: 'summary_large_image',
-        ...metadata.twitter,
-        images: [image],
-      },
-    }
+  if (spec === 'dynamic') {
+    return ogImageFragment(buildOgUrl({ title: fallbackTitle }), fallbackTitle)
   }
-
-  // Default: dynamic render. Auto-extract title; params.title overrides.
-  const resolvedParams: OGImageParams = {
-    title: extractTitle(metadata),
-    ...ogParams,
+  if ('image' in spec) {
+    return ogImageFragment(spec.image, spec.alt ?? fallbackTitle)
   }
+  // { render: {...} } — dynamic with explicit params; title defaults to page title.
+  const title = spec.render.title ?? fallbackTitle
+  return ogImageFragment(buildOgUrl({ ...spec.render, title }), title)
+}
 
-  const ogMeta = createOgMetadata(resolvedParams)
-
+/**
+ * Merges OG image metadata (dynamic render) into existing Metadata. Kept for
+ * low-level/manual use; `createMetadata` is the recommended entry point.
+ *
+ *   return withOgImage({ title: 'Page' }, { preset: 'DARK_BLUE' })
+ */
+export function withOgImage(
+  metadata: Metadata,
+  params: Omit<OGImageParams, 'title'> & { title?: string } = {}
+): Metadata {
+  const title = params.title ?? extractTitle(metadata)
+  const frag = createOgMetadata({ ...params, title })
   return {
     ...metadata,
-    openGraph: {
-      ...metadata.openGraph,
-      ...ogMeta.openGraph,
-    },
-    twitter: {
-      ...metadata.twitter,
-      ...ogMeta.twitter,
-    },
+    openGraph: { ...metadata.openGraph, ...frag.openGraph },
+    twitter: { ...metadata.twitter, ...frag.twitter },
   }
 }
-
-function extractTitle(metadata: Metadata): string {
-  const t = metadata.title
-  if (!t) return ''
-  if (typeof t === 'string') return t
-  if (typeof t === 'object' && 'absolute' in t) return (t as { absolute: string }).absolute
-  if (typeof t === 'object' && 'default' in t) return (t as { default: string }).default
-  return ''
-}

package/src/og-image/types.ts

@@ -11,6 +11,21 @@ export type OGPreset =
 
 export type OGLayout = 'DEFAULT' | 'HERO' | 'ARTICLE' | 'MINIMAL'
 
+/**
+ * Per-page OG image intent — the single axis that decides what the OG image is.
+ * A discriminated union so every case is explicit and type-checked:
+ *
+ *   'static'              brand image from site config (the default)
+ *   'dynamic'             render the page title onto the OG card
+ *   { render: {...} }     render with explicit preset/layout/colors
+ *   { image, alt? }       an exact image URL (e.g. a content screenshot)
+ */
+export type OgSpec =
+  | 'static'
+  | 'dynamic'
+  | { render: Omit<OGImageParams, 'title'> & { title?: string } }
+  | { image: string; alt?: string }
+
 /** Mirrors Django OGImageParams exactly */
 export interface OGImageParams {
   title: string