@djangocfg/nextjs 2.1.439 → 2.1.440

package/dist/og-image/index.d.mts

@@ -51,6 +51,16 @@ interface SiteMetaConfig {
     siteUrl: string;
     /** Ready-made static brand OG image URL (absolute or root-relative). */
     ogImage: string;
+    /**
+     * Django origin that serves the dynamic OG renderer (`/cfg/og/`), e.g.
+     * "https://api.example.com". Required for `og: 'dynamic'` / `{ render }`.
+     *
+     * - set    → dynamic OG images render against this origin
+     * - `''`   → no backend: dynamic specs fall back to the static brand image
+     *            (use this for a frontend with no Django, so no broken URLs)
+     * - omit   → fall back to env vars (MEDIA_URL → API_URL → SITE_URL)
+     */
+    ogBackend?: string;
     /** Optional favicon / apple-touch icons forwarded to Metadata.icons. */
     icons?: Metadata['icons'];
     /** Locales for hreflang alternates. Omit for single-locale sites. */
@@ -120,8 +130,12 @@ declare function makeMetadataFactory(config: SiteMetaConfig): (page?: PageMeta)
  * django_ogimage endpoint: /cfg/og/<base64params>/
  *
  * The URL is suitable for use in og:image and twitter:image meta tags.
+ *
+ * @param base Optional explicit backend origin (e.g. "https://api.example.com").
+ *   When omitted, it's resolved from env (MEDIA_URL → API_URL → SITE_URL → '').
+ *   Pass the `ogBackend` from your site config to avoid relying on env.
  */
-declare function buildOgUrl(params: OGImageParams): string;
+declare function buildOgUrl(params: OGImageParams, base?: string): string;
 
 /**
  * Metadata fragment whose OG image is rendered by Django's django_ogimage
@@ -134,12 +148,17 @@ declare function extractTitle(metadata: Metadata): string;
 /**
  * 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.
+ *
+ * `backend` is the Django origin that serves the dynamic renderer. The dynamic
+ * cases (`'dynamic'`, `{ render }`) require it: when it's `undefined`/empty —
+ * e.g. a frontend with no Django backend — they **fall back to the static brand
+ * image** instead of emitting a broken `/cfg/og/` URL. (`undefined` still lets
+ * `buildOgUrl` fall back to env vars; pass `''` to force the static fallback.)
  *
  * This is the single decision point for "what is the OG image" — no other code
  * branches on the spec.
  */
-declare function resolveOgImage(spec: OgSpec, staticUrl: string, fallbackTitle: string): Pick<Metadata, 'openGraph' | 'twitter'>;
+declare function resolveOgImage(spec: OgSpec, staticUrl: string, fallbackTitle: string, backend?: string): Pick<Metadata, 'openGraph' | 'twitter'>;
 /**
  * Merges OG image metadata (dynamic render) into existing Metadata. Kept for
  * low-level/manual use; `createMetadata` is the recommended entry point.

package/dist/og-image/index.mjs

@@ -16,10 +16,10 @@ function cleanParams(params) {
     )
   );
 }
-function buildOgUrl(params) {
+function buildOgUrl(params, base) {
   const b64 = encodeBase64(JSON.stringify(cleanParams(params)));
-  const base = resolveOgPublicBase();
-  return `${base}/cfg/og/${b64}/`;
+  const origin = (base ?? resolveOgPublicBase()).replace(/\/$/, "");
+  return `${origin}/cfg/og/${b64}/`;
 }
 
 // src/og-image/metadata.ts
@@ -45,18 +45,19 @@ function extractTitle(metadata) {
   if (typeof t === "object" && "default" in t) return t.default;
   return "";
 }
-function resolveOgImage(spec, staticUrl, fallbackTitle) {
+function resolveOgImage(spec, staticUrl, fallbackTitle, backend) {
+  const canRenderDynamic = backend === void 0 || backend !== "";
   if (spec === "static") {
     return ogImageFragment(staticUrl, fallbackTitle);
   }
   if (spec === "dynamic") {
-    return ogImageFragment(buildOgUrl({ title: fallbackTitle }), fallbackTitle);
+    return canRenderDynamic ? ogImageFragment(buildOgUrl({ title: fallbackTitle }, backend), fallbackTitle) : ogImageFragment(staticUrl, fallbackTitle);
   }
   if ("image" in spec) {
     return ogImageFragment(spec.image, spec.alt ?? fallbackTitle);
   }
   const title = spec.render.title ?? fallbackTitle;
-  return ogImageFragment(buildOgUrl({ ...spec.render, title }), title);
+  return canRenderDynamic ? ogImageFragment(buildOgUrl({ ...spec.render, title }, backend), title) : ogImageFragment(staticUrl, title);
 }
 function withOgImage(metadata, params = {}) {
   const title = params.title ?? extractTitle(metadata);
@@ -87,7 +88,7 @@ function createMetadata(config, page = {}) {
   const locale = page.locale ?? config.defaultLocale ?? "en";
   const path = page.path ?? "";
   const ogUrl = config.locales?.length ? `${config.siteUrl}/${locale}${path}` : `${config.siteUrl}${path}`;
-  const ogImage = resolveOgImage(page.og ?? "static", config.ogImage, title);
+  const ogImage = resolveOgImage(page.og ?? "static", config.ogImage, title, config.ogBackend);
   const metadata = {
     title,
     description,

package/dist/og-image/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/og-image/url.ts","../../src/og-image/metadata.ts","../../src/og-image/metadata-factory.ts"],"sourcesContent":["import type { OGImageParams } from './types'\n\n/**\n * Resolves the base URL for og:image meta tags.\n * Must be publicly accessible by crawlers (Twitter, Facebook, etc).\n *\n * Priority:\n * 1. NEXT_PUBLIC_MEDIA_URL — explicit media domain (nginx proxy or CDN)\n * 2. NEXT_PUBLIC_API_URL   — direct Django API domain\n * 3. NEXT_PUBLIC_SITE_URL  — site domain (same-domain/static build)\n * 4. ''                    — relative URL (last resort)\n *\n * Use cases:\n * - Same domain (static build):   API_URL='' → relative /cfg/og/...\n * - Split domain (standalone):    API_URL=https://api.x.com → absolute\n * - Media via nginx proxy:        MEDIA_URL=https://x.com, API_URL=https://api.x.com\n * - CDN:                          MEDIA_URL=https://cdn.x.com\n */\nfunction resolveOgPublicBase(): string {\n  if (typeof process === 'undefined') return ''\n  return (\n    process.env.NEXT_PUBLIC_MEDIA_URL?.replace(/\\/$/, '') ??\n    process.env.NEXT_PUBLIC_API_URL?.replace(/\\/$/, '') ??\n    process.env.NEXT_PUBLIC_SITE_URL?.replace(/\\/$/, '') ??\n    ''\n  )\n}\n\nfunction encodeBase64(str: string): string {\n  if (typeof Buffer !== 'undefined') {\n    return Buffer.from(str).toString('base64url')\n  }\n  // Browser fallback\n  return btoa(unescape(encodeURIComponent(str)))\n    .replace(/\\+/g, '-')\n    .replace(/\\//g, '_')\n    .replace(/=+$/, '')\n}\n\nfunction cleanParams(params: OGImageParams): Record<string, unknown> {\n  return Object.fromEntries(\n    Object.entries(params).filter(\n      ([, v]) => v !== undefined && v !== null && v !== ''\n    )\n  )\n}\n\n/**\n * Builds an absolute (or relative) OG image URL pointing to Django's\n * django_ogimage endpoint: /cfg/og/<base64params>/\n *\n * The URL is suitable for use in og:image and twitter:image meta tags.\n */\nexport function buildOgUrl(params: OGImageParams): string {\n  const b64 = encodeBase64(JSON.stringify(cleanParams(params)))\n  const base = resolveOgPublicBase()\n  return `${base}/cfg/og/${b64}/`\n}\n","import type { Metadata } from 'next'\nimport type { OGImageParams, OgSpec } from './types'\nimport { buildOgUrl } from './url'\n\nconst OG_WIDTH = 1200\nconst OG_HEIGHT = 630\n\n/** A Next.js OG image entry. */\nfunction imageEntry(url: string, alt: string) {\n  return { url, width: OG_WIDTH, height: OG_HEIGHT, alt }\n}\n\n/**\n * Builds the og/twitter image fragment for a given image URL — the one place\n * that knows the shape Next.js expects. Both static URLs and the dynamic\n * renderer funnel through here, so there's a single source of truth.\n */\nfunction ogImageFragment(url: string, alt: string): Pick<Metadata, 'openGraph' | 'twitter'> {\n  return {\n    openGraph: { images: [imageEntry(url, alt)] },\n    twitter: { card: 'summary_large_image', images: [url] },\n  }\n}\n\n/**\n * Metadata fragment whose OG image is rendered by Django's django_ogimage\n * endpoint (/cfg/og/). Low-level — most callers use `createMetadata`'s `og`\n * field instead.\n */\nexport function createOgMetadata(params: OGImageParams): Metadata {\n  return ogImageFragment(buildOgUrl(params), params.title)\n}\n\n/** Extract a plain title string from Next.js's title shapes. */\nexport function extractTitle(metadata: Metadata): string {\n  const t = metadata.title\n  if (!t) return ''\n  if (typeof t === 'string') return t\n  if (typeof t === 'object' && 'absolute' in t) return (t as { absolute: string }).absolute\n  if (typeof t === 'object' && 'default' in t) return (t as { default: string }).default\n  return ''\n}\n\n/**\n * Resolves an `OgSpec` against a base Metadata into a concrete og/twitter image\n * fragment. `staticUrl` is the site's brand image, used for the `'static'` case.\n * Returns `null` only if there's genuinely nothing to set.\n *\n * This is the single decision point for \"what is the OG image\" — no other code\n * branches on the spec.\n */\nexport function resolveOgImage(\n  spec: OgSpec,\n  staticUrl: string,\n  fallbackTitle: string\n): Pick<Metadata, 'openGraph' | 'twitter'> {\n  if (spec === 'static') {\n    return ogImageFragment(staticUrl, fallbackTitle)\n  }\n  if (spec === 'dynamic') {\n    return ogImageFragment(buildOgUrl({ title: fallbackTitle }), fallbackTitle)\n  }\n  if ('image' in spec) {\n    return ogImageFragment(spec.image, spec.alt ?? fallbackTitle)\n  }\n  // { render: {...} } — dynamic with explicit params; title defaults to page title.\n  const title = spec.render.title ?? fallbackTitle\n  return ogImageFragment(buildOgUrl({ ...spec.render, title }), title)\n}\n\n/**\n * Merges OG image metadata (dynamic render) into existing Metadata. Kept for\n * low-level/manual use; `createMetadata` is the recommended entry point.\n *\n *   return withOgImage({ title: 'Page' }, { preset: 'DARK_BLUE' })\n */\nexport function withOgImage(\n  metadata: Metadata,\n  params: Omit<OGImageParams, 'title'> & { title?: string } = {}\n): Metadata {\n  const title = params.title ?? extractTitle(metadata)\n  const frag = createOgMetadata({ ...params, title })\n  return {\n    ...metadata,\n    openGraph: { ...metadata.openGraph, ...frag.openGraph },\n    twitter: { ...metadata.twitter, ...frag.twitter },\n  }\n}\n","import type { Metadata } from 'next'\nimport type { OgSpec } from './types'\nimport { resolveOgImage } from './metadata'\n\n/**\n * Site-wide identity the metadata factory needs. Config-agnostic on purpose —\n * the package doesn't know about any app's `settings` object, so the consumer\n * passes these once (typically derived from their own settings module).\n */\nexport interface SiteMetaConfig {\n  /** Brand / app name, e.g. \"CMDOP\". Used in titles, siteName, alt text. */\n  name: string\n  /** Default description used when a page doesn't supply its own. */\n  description: string\n  /** Absolute site origin, e.g. \"https://cmdop.com\". Used for canonical/og url. */\n  siteUrl: string\n  /** Ready-made static brand OG image URL (absolute or root-relative). */\n  ogImage: string\n  /** Optional favicon / apple-touch icons forwarded to Metadata.icons. */\n  icons?: Metadata['icons']\n  /** Locales for hreflang alternates. Omit for single-locale sites. */\n  locales?: readonly string[]\n  /** Locale used for x-default hreflang (defaults to \"en\" or first locale). */\n  defaultLocale?: string\n}\n\n/**\n * Per-page inputs. Only `title` is really worth setting per page; everything\n * else falls back to the site config.\n */\nexport interface PageMeta {\n  /** Page title (without the brand suffix). Falls back to the site name. */\n  title?: string\n  /** Page description; falls back to the site description. */\n  description?: string\n  keywords?: string[]\n  /** Current locale, used for canonical + openGraph.locale + alternates. */\n  locale?: string\n  /** Path without locale prefix, e.g. \"/skills\". '' for home. */\n  path?: string\n  /**\n   * What the OG image should be. Defaults to `'static'` (the brand image).\n   * - `'static'`          brand image from config (default)\n   * - `'dynamic'`         render the page title onto the card\n   * - `{ render: {...} }` render with explicit preset/layout/colors\n   * - `{ image, alt? }`   an exact image URL (e.g. a content screenshot)\n   */\n  og?: OgSpec\n  /** Escape hatch: extra Metadata fields merged last (robots, authors, etc.). */\n  extra?: Metadata\n}\n\nfunction buildAlternates(\n  config: SiteMetaConfig,\n  path: string,\n  locale: string\n): Metadata['alternates'] {\n  if (!config.locales?.length) {\n    return { canonical: `${config.siteUrl}/${path}`.replace(/\\/+$/, '') || config.siteUrl }\n  }\n  const languages: Record<string, string> = {}\n  for (const loc of config.locales) {\n    languages[loc] = `${config.siteUrl}/${loc}${path}`\n  }\n  const xDefault =\n    config.defaultLocale ?? (config.locales.includes('en') ? 'en' : config.locales[0])\n  languages['x-default'] = `${config.siteUrl}/${xDefault}${path}`\n  return { canonical: `${config.siteUrl}/${locale}${path}`, languages }\n}\n\n/**\n * Builds a complete Next.js `Metadata` from a one-time site config plus per-page\n * inputs — title-template, description, openGraph, twitter, canonical + hreflang,\n * icons, and the OG image — so pages only declare what's unique.\n *\n * The OG image is chosen by the single `og` field (defaults to the static brand\n * image). There is exactly one way to do each thing.\n *\n *   // app/_core/metadata.ts\n *   export const createMetadata = makeMetadataFactory({\n *     name: settings.app.name,\n *     description: settings.app.description,\n *     siteUrl: settings.app.siteUrl,\n *     ogImage: settings.app.media.ogimage,\n *     icons: { icon: settings.app.media.favicon },\n *     locales: LOCALES,\n *   })\n *\n *   // landing page — static brand image (default)\n *   export const metadata = createMetadata({ title: 'Pricing', path: '/pricing' })\n *   // content page — title rendered onto the card\n *   export const metadata = createMetadata({ title: post.title, path, og: 'dynamic' })\n *   // content page with its own image\n *   export const metadata = createMetadata({ title: p.name, og: { image: p.image } })\n */\nexport function createMetadata(config: SiteMetaConfig, page: PageMeta = {}): Metadata {\n  const title = page.title ?? config.name\n  const description = page.description ?? config.description\n  const locale = page.locale ?? config.defaultLocale ?? 'en'\n  const path = page.path ?? ''\n  const ogUrl = config.locales?.length\n    ? `${config.siteUrl}/${locale}${path}`\n    : `${config.siteUrl}${path}`\n\n  const ogImage = resolveOgImage(page.og ?? 'static', config.ogImage, title)\n\n  const metadata: Metadata = {\n    title,\n    description,\n    keywords: page.keywords,\n    alternates: buildAlternates(config, path, locale),\n    openGraph: {\n      type: 'website',\n      locale,\n      url: ogUrl,\n      siteName: config.name,\n      title,\n      description,\n      ...ogImage.openGraph,\n    },\n    twitter: {\n      title,\n      description,\n      ...ogImage.twitter,\n    },\n    icons: config.icons,\n  }\n\n  if (!page.extra) return metadata\n  // Shallow-merge the escape hatch, but deep-merge the nested og/twitter so the\n  // image we just set isn't clobbered by a partial `extra.openGraph`.\n  return {\n    ...metadata,\n    ...page.extra,\n    openGraph: { ...metadata.openGraph, ...page.extra.openGraph },\n    twitter: { ...metadata.twitter, ...page.extra.twitter },\n  }\n}\n\n/**\n * Curries `createMetadata` with a fixed site config so pages call a zero-config\n * factory. This is the single recommended entry point for app metadata.\n */\nexport function makeMetadataFactory(config: SiteMetaConfig) {\n  return (page: PageMeta = {}): Metadata => createMetadata(config, page)\n}\n"],"mappings":";AAkBA,SAAS,sBAA8B;AACrC,MAAI,OAAO,YAAY,YAAa,QAAO;AAC3C,SACE,QAAQ,IAAI,uBAAuB,QAAQ,OAAO,EAAE,KACpD,QAAQ,IAAI,qBAAqB,QAAQ,OAAO,EAAE,KAClD,QAAQ,IAAI,sBAAsB,QAAQ,OAAO,EAAE,KACnD;AAEJ;AAEA,SAAS,aAAa,KAAqB;AACzC,MAAI,OAAO,WAAW,aAAa;AACjC,WAAO,OAAO,KAAK,GAAG,EAAE,SAAS,WAAW;AAAA,EAC9C;AAEA,SAAO,KAAK,SAAS,mBAAmB,GAAG,CAAC,CAAC,EAC1C,QAAQ,OAAO,GAAG,EAClB,QAAQ,OAAO,GAAG,EAClB,QAAQ,OAAO,EAAE;AACtB;AAEA,SAAS,YAAY,QAAgD;AACnE,SAAO,OAAO;AAAA,IACZ,OAAO,QAAQ,MAAM,EAAE;AAAA,MACrB,CAAC,CAAC,EAAE,CAAC,MAAM,MAAM,UAAa,MAAM,QAAQ,MAAM;AAAA,IACpD;AAAA,EACF;AACF;AAQO,SAAS,WAAW,QAA+B;AACxD,QAAM,MAAM,aAAa,KAAK,UAAU,YAAY,MAAM,CAAC,CAAC;AAC5D,QAAM,OAAO,oBAAoB;AACjC,SAAO,GAAG,IAAI,WAAW,GAAG;AAC9B;;;ACrDA,IAAM,WAAW;AACjB,IAAM,YAAY;AAGlB,SAAS,WAAW,KAAa,KAAa;AAC5C,SAAO,EAAE,KAAK,OAAO,UAAU,QAAQ,WAAW,IAAI;AACxD;AAOA,SAAS,gBAAgB,KAAa,KAAsD;AAC1F,SAAO;AAAA,IACL,WAAW,EAAE,QAAQ,CAAC,WAAW,KAAK,GAAG,CAAC,EAAE;AAAA,IAC5C,SAAS,EAAE,MAAM,uBAAuB,QAAQ,CAAC,GAAG,EAAE;AAAA,EACxD;AACF;AAOO,SAAS,iBAAiB,QAAiC;AAChE,SAAO,gBAAgB,WAAW,MAAM,GAAG,OAAO,KAAK;AACzD;AAGO,SAAS,aAAa,UAA4B;AACvD,QAAM,IAAI,SAAS;AACnB,MAAI,CAAC,EAAG,QAAO;AACf,MAAI,OAAO,MAAM,SAAU,QAAO;AAClC,MAAI,OAAO,MAAM,YAAY,cAAc,EAAG,QAAQ,EAA2B;AACjF,MAAI,OAAO,MAAM,YAAY,aAAa,EAAG,QAAQ,EAA0B;AAC/E,SAAO;AACT;AAUO,SAAS,eACd,MACA,WACA,eACyC;AACzC,MAAI,SAAS,UAAU;AACrB,WAAO,gBAAgB,WAAW,aAAa;AAAA,EACjD;AACA,MAAI,SAAS,WAAW;AACtB,WAAO,gBAAgB,WAAW,EAAE,OAAO,cAAc,CAAC,GAAG,aAAa;AAAA,EAC5E;AACA,MAAI,WAAW,MAAM;AACnB,WAAO,gBAAgB,KAAK,OAAO,KAAK,OAAO,aAAa;AAAA,EAC9D;AAEA,QAAM,QAAQ,KAAK,OAAO,SAAS;AACnC,SAAO,gBAAgB,WAAW,EAAE,GAAG,KAAK,QAAQ,MAAM,CAAC,GAAG,KAAK;AACrE;AAQO,SAAS,YACd,UACA,SAA4D,CAAC,GACnD;AACV,QAAM,QAAQ,OAAO,SAAS,aAAa,QAAQ;AACnD,QAAM,OAAO,iBAAiB,EAAE,GAAG,QAAQ,MAAM,CAAC;AAClD,SAAO;AAAA,IACL,GAAG;AAAA,IACH,WAAW,EAAE,GAAG,SAAS,WAAW,GAAG,KAAK,UAAU;AAAA,IACtD,SAAS,EAAE,GAAG,SAAS,SAAS,GAAG,KAAK,QAAQ;AAAA,EAClD;AACF;;;ACnCA,SAAS,gBACP,QACA,MACA,QACwB;AACxB,MAAI,CAAC,OAAO,SAAS,QAAQ;AAC3B,WAAO,EAAE,WAAW,GAAG,OAAO,OAAO,IAAI,IAAI,GAAG,QAAQ,QAAQ,EAAE,KAAK,OAAO,QAAQ;AAAA,EACxF;AACA,QAAM,YAAoC,CAAC;AAC3C,aAAW,OAAO,OAAO,SAAS;AAChC,cAAU,GAAG,IAAI,GAAG,OAAO,OAAO,IAAI,GAAG,GAAG,IAAI;AAAA,EAClD;AACA,QAAM,WACJ,OAAO,kBAAkB,OAAO,QAAQ,SAAS,IAAI,IAAI,OAAO,OAAO,QAAQ,CAAC;AAClF,YAAU,WAAW,IAAI,GAAG,OAAO,OAAO,IAAI,QAAQ,GAAG,IAAI;AAC7D,SAAO,EAAE,WAAW,GAAG,OAAO,OAAO,IAAI,MAAM,GAAG,IAAI,IAAI,UAAU;AACtE;AA2BO,SAAS,eAAe,QAAwB,OAAiB,CAAC,GAAa;AACpF,QAAM,QAAQ,KAAK,SAAS,OAAO;AACnC,QAAM,cAAc,KAAK,eAAe,OAAO;AAC/C,QAAM,SAAS,KAAK,UAAU,OAAO,iBAAiB;AACtD,QAAM,OAAO,KAAK,QAAQ;AAC1B,QAAM,QAAQ,OAAO,SAAS,SAC1B,GAAG,OAAO,OAAO,IAAI,MAAM,GAAG,IAAI,KAClC,GAAG,OAAO,OAAO,GAAG,IAAI;AAE5B,QAAM,UAAU,eAAe,KAAK,MAAM,UAAU,OAAO,SAAS,KAAK;AAEzE,QAAM,WAAqB;AAAA,IACzB;AAAA,IACA;AAAA,IACA,UAAU,KAAK;AAAA,IACf,YAAY,gBAAgB,QAAQ,MAAM,MAAM;AAAA,IAChD,WAAW;AAAA,MACT,MAAM;AAAA,MACN;AAAA,MACA,KAAK;AAAA,MACL,UAAU,OAAO;AAAA,MACjB;AAAA,MACA;AAAA,MACA,GAAG,QAAQ;AAAA,IACb;AAAA,IACA,SAAS;AAAA,MACP;AAAA,MACA;AAAA,MACA,GAAG,QAAQ;AAAA,IACb;AAAA,IACA,OAAO,OAAO;AAAA,EAChB;AAEA,MAAI,CAAC,KAAK,MAAO,QAAO;AAGxB,SAAO;AAAA,IACL,GAAG;AAAA,IACH,GAAG,KAAK;AAAA,IACR,WAAW,EAAE,GAAG,SAAS,WAAW,GAAG,KAAK,MAAM,UAAU;AAAA,IAC5D,SAAS,EAAE,GAAG,SAAS,SAAS,GAAG,KAAK,MAAM,QAAQ;AAAA,EACxD;AACF;AAMO,SAAS,oBAAoB,QAAwB;AAC1D,SAAO,CAAC,OAAiB,CAAC,MAAgB,eAAe,QAAQ,IAAI;AACvE;","names":[]}
+{"version":3,"sources":["../../src/og-image/url.ts","../../src/og-image/metadata.ts","../../src/og-image/metadata-factory.ts"],"sourcesContent":["import type { OGImageParams } from './types'\n\n/**\n * Resolves the base URL for og:image meta tags.\n * Must be publicly accessible by crawlers (Twitter, Facebook, etc).\n *\n * Priority:\n * 1. NEXT_PUBLIC_MEDIA_URL — explicit media domain (nginx proxy or CDN)\n * 2. NEXT_PUBLIC_API_URL   — direct Django API domain\n * 3. NEXT_PUBLIC_SITE_URL  — site domain (same-domain/static build)\n * 4. ''                    — relative URL (last resort)\n *\n * Use cases:\n * - Same domain (static build):   API_URL='' → relative /cfg/og/...\n * - Split domain (standalone):    API_URL=https://api.x.com → absolute\n * - Media via nginx proxy:        MEDIA_URL=https://x.com, API_URL=https://api.x.com\n * - CDN:                          MEDIA_URL=https://cdn.x.com\n */\nfunction resolveOgPublicBase(): string {\n  if (typeof process === 'undefined') return ''\n  return (\n    process.env.NEXT_PUBLIC_MEDIA_URL?.replace(/\\/$/, '') ??\n    process.env.NEXT_PUBLIC_API_URL?.replace(/\\/$/, '') ??\n    process.env.NEXT_PUBLIC_SITE_URL?.replace(/\\/$/, '') ??\n    ''\n  )\n}\n\nfunction encodeBase64(str: string): string {\n  if (typeof Buffer !== 'undefined') {\n    return Buffer.from(str).toString('base64url')\n  }\n  // Browser fallback\n  return btoa(unescape(encodeURIComponent(str)))\n    .replace(/\\+/g, '-')\n    .replace(/\\//g, '_')\n    .replace(/=+$/, '')\n}\n\nfunction cleanParams(params: OGImageParams): Record<string, unknown> {\n  return Object.fromEntries(\n    Object.entries(params).filter(\n      ([, v]) => v !== undefined && v !== null && v !== ''\n    )\n  )\n}\n\n/**\n * Builds an absolute (or relative) OG image URL pointing to Django's\n * django_ogimage endpoint: /cfg/og/<base64params>/\n *\n * The URL is suitable for use in og:image and twitter:image meta tags.\n *\n * @param base Optional explicit backend origin (e.g. \"https://api.example.com\").\n *   When omitted, it's resolved from env (MEDIA_URL → API_URL → SITE_URL → '').\n *   Pass the `ogBackend` from your site config to avoid relying on env.\n */\nexport function buildOgUrl(params: OGImageParams, base?: string): string {\n  const b64 = encodeBase64(JSON.stringify(cleanParams(params)))\n  const origin = (base ?? resolveOgPublicBase()).replace(/\\/$/, '')\n  return `${origin}/cfg/og/${b64}/`\n}\n","import type { Metadata } from 'next'\nimport type { OGImageParams, OgSpec } from './types'\nimport { buildOgUrl } from './url'\n\nconst OG_WIDTH = 1200\nconst OG_HEIGHT = 630\n\n/** A Next.js OG image entry. */\nfunction imageEntry(url: string, alt: string) {\n  return { url, width: OG_WIDTH, height: OG_HEIGHT, alt }\n}\n\n/**\n * Builds the og/twitter image fragment for a given image URL — the one place\n * that knows the shape Next.js expects. Both static URLs and the dynamic\n * renderer funnel through here, so there's a single source of truth.\n */\nfunction ogImageFragment(url: string, alt: string): Pick<Metadata, 'openGraph' | 'twitter'> {\n  return {\n    openGraph: { images: [imageEntry(url, alt)] },\n    twitter: { card: 'summary_large_image', images: [url] },\n  }\n}\n\n/**\n * Metadata fragment whose OG image is rendered by Django's django_ogimage\n * endpoint (/cfg/og/). Low-level — most callers use `createMetadata`'s `og`\n * field instead.\n */\nexport function createOgMetadata(params: OGImageParams): Metadata {\n  return ogImageFragment(buildOgUrl(params), params.title)\n}\n\n/** Extract a plain title string from Next.js's title shapes. */\nexport function extractTitle(metadata: Metadata): string {\n  const t = metadata.title\n  if (!t) return ''\n  if (typeof t === 'string') return t\n  if (typeof t === 'object' && 'absolute' in t) return (t as { absolute: string }).absolute\n  if (typeof t === 'object' && 'default' in t) return (t as { default: string }).default\n  return ''\n}\n\n/**\n * Resolves an `OgSpec` against a base Metadata into a concrete og/twitter image\n * fragment. `staticUrl` is the site's brand image, used for the `'static'` case.\n *\n * `backend` is the Django origin that serves the dynamic renderer. The dynamic\n * cases (`'dynamic'`, `{ render }`) require it: when it's `undefined`/empty —\n * e.g. a frontend with no Django backend — they **fall back to the static brand\n * image** instead of emitting a broken `/cfg/og/` URL. (`undefined` still lets\n * `buildOgUrl` fall back to env vars; pass `''` to force the static fallback.)\n *\n * This is the single decision point for \"what is the OG image\" — no other code\n * branches on the spec.\n */\nexport function resolveOgImage(\n  spec: OgSpec,\n  staticUrl: string,\n  fallbackTitle: string,\n  backend?: string\n): Pick<Metadata, 'openGraph' | 'twitter'> {\n  const canRenderDynamic = backend === undefined || backend !== ''\n\n  if (spec === 'static') {\n    return ogImageFragment(staticUrl, fallbackTitle)\n  }\n  if (spec === 'dynamic') {\n    return canRenderDynamic\n      ? ogImageFragment(buildOgUrl({ title: fallbackTitle }, backend), fallbackTitle)\n      : ogImageFragment(staticUrl, fallbackTitle)\n  }\n  if ('image' in spec) {\n    return ogImageFragment(spec.image, spec.alt ?? fallbackTitle)\n  }\n  // { render: {...} } — dynamic with explicit params; title defaults to page title.\n  const title = spec.render.title ?? fallbackTitle\n  return canRenderDynamic\n    ? ogImageFragment(buildOgUrl({ ...spec.render, title }, backend), title)\n    : ogImageFragment(staticUrl, title)\n}\n\n/**\n * Merges OG image metadata (dynamic render) into existing Metadata. Kept for\n * low-level/manual use; `createMetadata` is the recommended entry point.\n *\n *   return withOgImage({ title: 'Page' }, { preset: 'DARK_BLUE' })\n */\nexport function withOgImage(\n  metadata: Metadata,\n  params: Omit<OGImageParams, 'title'> & { title?: string } = {}\n): Metadata {\n  const title = params.title ?? extractTitle(metadata)\n  const frag = createOgMetadata({ ...params, title })\n  return {\n    ...metadata,\n    openGraph: { ...metadata.openGraph, ...frag.openGraph },\n    twitter: { ...metadata.twitter, ...frag.twitter },\n  }\n}\n","import type { Metadata } from 'next'\nimport type { OgSpec } from './types'\nimport { resolveOgImage } from './metadata'\n\n/**\n * Site-wide identity the metadata factory needs. Config-agnostic on purpose —\n * the package doesn't know about any app's `settings` object, so the consumer\n * passes these once (typically derived from their own settings module).\n */\nexport interface SiteMetaConfig {\n  /** Brand / app name, e.g. \"CMDOP\". Used in titles, siteName, alt text. */\n  name: string\n  /** Default description used when a page doesn't supply its own. */\n  description: string\n  /** Absolute site origin, e.g. \"https://cmdop.com\". Used for canonical/og url. */\n  siteUrl: string\n  /** Ready-made static brand OG image URL (absolute or root-relative). */\n  ogImage: string\n  /**\n   * Django origin that serves the dynamic OG renderer (`/cfg/og/`), e.g.\n   * \"https://api.example.com\". Required for `og: 'dynamic'` / `{ render }`.\n   *\n   * - set    → dynamic OG images render against this origin\n   * - `''`   → no backend: dynamic specs fall back to the static brand image\n   *            (use this for a frontend with no Django, so no broken URLs)\n   * - omit   → fall back to env vars (MEDIA_URL → API_URL → SITE_URL)\n   */\n  ogBackend?: string\n  /** Optional favicon / apple-touch icons forwarded to Metadata.icons. */\n  icons?: Metadata['icons']\n  /** Locales for hreflang alternates. Omit for single-locale sites. */\n  locales?: readonly string[]\n  /** Locale used for x-default hreflang (defaults to \"en\" or first locale). */\n  defaultLocale?: string\n}\n\n/**\n * Per-page inputs. Only `title` is really worth setting per page; everything\n * else falls back to the site config.\n */\nexport interface PageMeta {\n  /** Page title (without the brand suffix). Falls back to the site name. */\n  title?: string\n  /** Page description; falls back to the site description. */\n  description?: string\n  keywords?: string[]\n  /** Current locale, used for canonical + openGraph.locale + alternates. */\n  locale?: string\n  /** Path without locale prefix, e.g. \"/skills\". '' for home. */\n  path?: string\n  /**\n   * What the OG image should be. Defaults to `'static'` (the brand image).\n   * - `'static'`          brand image from config (default)\n   * - `'dynamic'`         render the page title onto the card\n   * - `{ render: {...} }` render with explicit preset/layout/colors\n   * - `{ image, alt? }`   an exact image URL (e.g. a content screenshot)\n   */\n  og?: OgSpec\n  /** Escape hatch: extra Metadata fields merged last (robots, authors, etc.). */\n  extra?: Metadata\n}\n\nfunction buildAlternates(\n  config: SiteMetaConfig,\n  path: string,\n  locale: string\n): Metadata['alternates'] {\n  if (!config.locales?.length) {\n    return { canonical: `${config.siteUrl}/${path}`.replace(/\\/+$/, '') || config.siteUrl }\n  }\n  const languages: Record<string, string> = {}\n  for (const loc of config.locales) {\n    languages[loc] = `${config.siteUrl}/${loc}${path}`\n  }\n  const xDefault =\n    config.defaultLocale ?? (config.locales.includes('en') ? 'en' : config.locales[0])\n  languages['x-default'] = `${config.siteUrl}/${xDefault}${path}`\n  return { canonical: `${config.siteUrl}/${locale}${path}`, languages }\n}\n\n/**\n * Builds a complete Next.js `Metadata` from a one-time site config plus per-page\n * inputs — title-template, description, openGraph, twitter, canonical + hreflang,\n * icons, and the OG image — so pages only declare what's unique.\n *\n * The OG image is chosen by the single `og` field (defaults to the static brand\n * image). There is exactly one way to do each thing.\n *\n *   // app/_core/metadata.ts\n *   export const createMetadata = makeMetadataFactory({\n *     name: settings.app.name,\n *     description: settings.app.description,\n *     siteUrl: settings.app.siteUrl,\n *     ogImage: settings.app.media.ogimage,\n *     icons: { icon: settings.app.media.favicon },\n *     locales: LOCALES,\n *   })\n *\n *   // landing page — static brand image (default)\n *   export const metadata = createMetadata({ title: 'Pricing', path: '/pricing' })\n *   // content page — title rendered onto the card\n *   export const metadata = createMetadata({ title: post.title, path, og: 'dynamic' })\n *   // content page with its own image\n *   export const metadata = createMetadata({ title: p.name, og: { image: p.image } })\n */\nexport function createMetadata(config: SiteMetaConfig, page: PageMeta = {}): Metadata {\n  const title = page.title ?? config.name\n  const description = page.description ?? config.description\n  const locale = page.locale ?? config.defaultLocale ?? 'en'\n  const path = page.path ?? ''\n  const ogUrl = config.locales?.length\n    ? `${config.siteUrl}/${locale}${path}`\n    : `${config.siteUrl}${path}`\n\n  const ogImage = resolveOgImage(page.og ?? 'static', config.ogImage, title, config.ogBackend)\n\n  const metadata: Metadata = {\n    title,\n    description,\n    keywords: page.keywords,\n    alternates: buildAlternates(config, path, locale),\n    openGraph: {\n      type: 'website',\n      locale,\n      url: ogUrl,\n      siteName: config.name,\n      title,\n      description,\n      ...ogImage.openGraph,\n    },\n    twitter: {\n      title,\n      description,\n      ...ogImage.twitter,\n    },\n    icons: config.icons,\n  }\n\n  if (!page.extra) return metadata\n  // Shallow-merge the escape hatch, but deep-merge the nested og/twitter so the\n  // image we just set isn't clobbered by a partial `extra.openGraph`.\n  return {\n    ...metadata,\n    ...page.extra,\n    openGraph: { ...metadata.openGraph, ...page.extra.openGraph },\n    twitter: { ...metadata.twitter, ...page.extra.twitter },\n  }\n}\n\n/**\n * Curries `createMetadata` with a fixed site config so pages call a zero-config\n * factory. This is the single recommended entry point for app metadata.\n */\nexport function makeMetadataFactory(config: SiteMetaConfig) {\n  return (page: PageMeta = {}): Metadata => createMetadata(config, page)\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/nextjs",
-  "version": "2.1.439",
+  "version": "2.1.440",
   "description": "Next.js server utilities: sitemap, health, OG images, contact forms, navigation, config",
   "keywords": [
     "nextjs",
@@ -143,9 +143,9 @@
     "ai-docs": "tsx src/ai/cli.ts"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.439",
-    "@djangocfg/monitor": "^2.1.439",
-    "@djangocfg/ui-core": "^2.1.439",
+    "@djangocfg/i18n": "^2.1.440",
+    "@djangocfg/monitor": "^2.1.440",
+    "@djangocfg/ui-core": "^2.1.440",
     "next": "^16.2.2"
   },
   "peerDependenciesMeta": {
@@ -167,11 +167,11 @@
     "serwist": "^9.2.3"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.439",
-    "@djangocfg/monitor": "^2.1.439",
-    "@djangocfg/ui-core": "^2.1.439",
-    "@djangocfg/layouts": "^2.1.439",
-    "@djangocfg/typescript-config": "^2.1.439",
+    "@djangocfg/i18n": "^2.1.440",
+    "@djangocfg/monitor": "^2.1.440",
+    "@djangocfg/ui-core": "^2.1.440",
+    "@djangocfg/layouts": "^2.1.440",
+    "@djangocfg/typescript-config": "^2.1.440",
     "@types/node": "^25.2.3",
     "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",

package/src/og-image/README.md

@@ -52,6 +52,26 @@ way to express each case:
 | `{ render: { preset, layout, … } }` | dynamic render with explicit params |
 | `{ image, alt? }` | an exact image URL (content screenshot, cover) |
 
+### No backend? Dynamic falls back to static
+
+The `'dynamic'` and `{ render }` cases need a Django renderer. Tell the factory
+where it is — or that there isn't one — via `ogBackend`:
+
+```typescript
+// has a backend → dynamic OG renders against it
+makeMetadataFactory({ ..., ogBackend: 'https://api.example.com' })
+
+// frontend with NO Django backend → og:'dynamic' silently becomes the static
+// brand image, so you never emit a broken /cfg/og/ URL
+makeMetadataFactory({ ..., ogBackend: '' })
+
+// omit → resolve from env (MEDIA_URL → API_URL → SITE_URL)
+makeMetadataFactory({ ... })
+```
+
+So a static-only site can leave `og: 'dynamic'` on content pages without breaking
+anything — set `ogBackend: ''` once and every dynamic spec degrades to static.
+
 ---
 
 ## How It Works
@@ -136,6 +156,7 @@ export const metadata = createMetadata({ title: 'About', path: '/about' })
 | `description` | `string` | default description |
 | `siteUrl` | `string` | absolute origin, e.g. `https://example.com` |
 | `ogImage` | `string` | static brand OG image URL |
+| `ogBackend?` | `string` | Django origin for the dynamic renderer (see below) |
 | `icons?` | `Metadata['icons']` | favicon / apple-touch |
 | `locales?` | `readonly string[]` | for hreflang; omit for single-locale |
 | `defaultLocale?` | `string` | x-default locale (defaults `en` / first) |

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

@@ -16,6 +16,16 @@ export interface SiteMetaConfig {
   siteUrl: string
   /** Ready-made static brand OG image URL (absolute or root-relative). */
   ogImage: string
+  /**
+   * Django origin that serves the dynamic OG renderer (`/cfg/og/`), e.g.
+   * "https://api.example.com". Required for `og: 'dynamic'` / `{ render }`.
+   *
+   * - set    → dynamic OG images render against this origin
+   * - `''`   → no backend: dynamic specs fall back to the static brand image
+   *            (use this for a frontend with no Django, so no broken URLs)
+   * - omit   → fall back to env vars (MEDIA_URL → API_URL → SITE_URL)
+   */
+  ogBackend?: string
   /** Optional favicon / apple-touch icons forwarded to Metadata.icons. */
   icons?: Metadata['icons']
   /** Locales for hreflang alternates. Omit for single-locale sites. */
@@ -102,7 +112,7 @@ export function createMetadata(config: SiteMetaConfig, page: PageMeta = {}): Met
     ? `${config.siteUrl}/${locale}${path}`
     : `${config.siteUrl}${path}`
 
-  const ogImage = resolveOgImage(page.og ?? 'static', config.ogImage, title)
+  const ogImage = resolveOgImage(page.og ?? 'static', config.ogImage, title, config.ogBackend)
 
   const metadata: Metadata = {
     title,

package/src/og-image/metadata.ts

@@ -44,7 +44,12 @@ export function extractTitle(metadata: Metadata): string {
 /**
  * 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.
+ *
+ * `backend` is the Django origin that serves the dynamic renderer. The dynamic
+ * cases (`'dynamic'`, `{ render }`) require it: when it's `undefined`/empty —
+ * e.g. a frontend with no Django backend — they **fall back to the static brand
+ * image** instead of emitting a broken `/cfg/og/` URL. (`undefined` still lets
+ * `buildOgUrl` fall back to env vars; pass `''` to force the static fallback.)
  *
  * This is the single decision point for "what is the OG image" — no other code
  * branches on the spec.
@@ -52,20 +57,27 @@ export function extractTitle(metadata: Metadata): string {
 export function resolveOgImage(
   spec: OgSpec,
   staticUrl: string,
-  fallbackTitle: string
+  fallbackTitle: string,
+  backend?: string
 ): Pick<Metadata, 'openGraph' | 'twitter'> {
+  const canRenderDynamic = backend === undefined || backend !== ''
+
   if (spec === 'static') {
     return ogImageFragment(staticUrl, fallbackTitle)
   }
   if (spec === 'dynamic') {
-    return ogImageFragment(buildOgUrl({ title: fallbackTitle }), fallbackTitle)
+    return canRenderDynamic
+      ? ogImageFragment(buildOgUrl({ title: fallbackTitle }, backend), fallbackTitle)
+      : ogImageFragment(staticUrl, fallbackTitle)
   }
   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)
+  return canRenderDynamic
+    ? ogImageFragment(buildOgUrl({ ...spec.render, title }, backend), title)
+    : ogImageFragment(staticUrl, title)
 }
 
 /**

package/src/og-image/url.ts

@@ -50,9 +50,13 @@ function cleanParams(params: OGImageParams): Record<string, unknown> {
  * django_ogimage endpoint: /cfg/og/<base64params>/
  *
  * The URL is suitable for use in og:image and twitter:image meta tags.
+ *
+ * @param base Optional explicit backend origin (e.g. "https://api.example.com").
+ *   When omitted, it's resolved from env (MEDIA_URL → API_URL → SITE_URL → '').
+ *   Pass the `ogBackend` from your site config to avoid relying on env.
  */
-export function buildOgUrl(params: OGImageParams): string {
+export function buildOgUrl(params: OGImageParams, base?: string): string {
   const b64 = encodeBase64(JSON.stringify(cleanParams(params)))
-  const base = resolveOgPublicBase()
-  return `${base}/cfg/og/${b64}/`
+  const origin = (base ?? resolveOgPublicBase()).replace(/\/$/, '')
+  return `${origin}/cfg/og/${b64}/`
 }