@djangocfg/nextjs 2.1.225 → 2.1.227

package/README.md

@@ -1,6 +1,6 @@
 # @djangocfg/nextjs
 
-> Server-side Next.js utilities: sitemap generation, health checks, OG images, navigation, and config
+> Server-side Next.js utilities: OG images, sitemap, health checks, i18n, PWA, navigation, and config
 
 [![npm version](https://img.shields.io/npm/v/@djangocfg/nextjs.svg)](https://www.npmjs.com/package/@djangocfg/nextjs)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
@@ -11,22 +11,20 @@
 
 ## Overview
 
-`@djangocfg/nextjs` provides server-side utilities for Next.js applications. This package focuses on server-only functionality: SEO optimization with sitemaps, health monitoring, dynamic OG images, navigation utilities, and configuration management.
+`@djangocfg/nextjs` provides server-side utilities for Next.js applications built on top of Django-CFG.
 
-> **Note:** Client components (legal pages, error pages, redirect components) have been moved to `@djangocfg/layouts` to keep this package server-only.
+> **Note:** Client components (legal pages, error pages, redirect components) are in `@djangocfg/layouts`.
 
 ## Features
 
-- **i18n (Internationalization)** - Full next-intl integration with routing, middleware, and components
-- **Dev Server with Browser Auto-Open** - Cross-platform CLI that works with Turbopack and webpack
-- **Zero-Config PWA** - Progressive Web App out of the box (service worker, offline support, manifest)
-- **Base Next.js Config** - Universal, reusable Next.js configuration factory for monorepos
-- **AI Documentation** - Search DjangoCFG docs via MCP server and CLI
-- **Sitemap Generation** - Dynamic XML sitemap with i18n hreflang support
-- **Health Checks** - Production-ready health monitoring endpoints
-- **OG Images** - Dynamic Open Graph image generation with templates
-- **Navigation Utilities** - Route definitions, menu generation, and navigation helpers
-- **TypeScript** - Full type safety throughout
+- **OG Images** — typed URL builder for Django's `django_ogimage` renderer (`@djangocfg/nextjs/og-image`)
+- **i18n** — full next-intl integration with routing, middleware, and components
+- **PWA** — zero-config service worker and manifest
+- **Base Next.js Config** — reusable `createBaseNextConfig()` factory for monorepos
+- **Sitemap** — dynamic XML sitemap with i18n hreflang support
+- **Health Checks** — production-ready health monitoring endpoints
+- **Navigation** — route definitions, menu generation, and active-state helpers
+- **AI Documentation** — search DjangoCFG docs via MCP server and CLI
 
 ## Installation
 
@@ -358,44 +356,21 @@ export const GET = createHealthHandler({
 
 ### OG Image Generation
 
-Generate dynamic Open Graph images with custom templates:
+Builds typed URLs pointing to Django's `django_ogimage` renderer — no Edge Runtime, no `@vercel/og`:
 
 ```tsx
-// app/api/og/route.tsx
-import { createOgImageHandler } from '@djangocfg/nextjs/og-image';
-import { OgImageTemplate } from '@/components/OgImageTemplate';
-
-export const runtime = 'edge';
-
-const handler = createOgImageHandler({
-  template: OgImageTemplate,
-  defaultProps: {
-    siteName: 'My App',
-    logo: '/logo.svg',
-  },
-  fonts: [
-    { family: 'Manrope', weight: 700 },
-    { family: 'Manrope', weight: 500 },
-  ],
-  size: { width: 1200, height: 630 },
-});
+// app/page.tsx
+import { withOgImage } from '@djangocfg/nextjs/og-image'
 
-export async function GET(request: NextRequest) {
-  return handler.GET(request);
+export async function generateMetadata(): Promise<Metadata> {
+  return withOgImage(
+    { title: 'My Page', description: 'Description' },
+    { preset: 'DARK_BLUE', layout: 'HERO' }
+  )
 }
 ```
 
-Automatically add OG images to page metadata:
-
-```tsx
-// app/page.tsx
-import { generateAppMetadata } from '@djangocfg/nextjs/og-image/utils';
-
-export const metadata = generateAppMetadata({
-  title: 'My Page',
-  description: 'Page description',
-});
-```
+The URL is resolved automatically from `NEXT_PUBLIC_MEDIA_URL` → `NEXT_PUBLIC_API_URL` → `NEXT_PUBLIC_SITE_URL`. Django renders and caches the PNG — no Edge Runtime or `@vercel/og` required.
 
 ### Navigation Utilities
 
@@ -445,9 +420,7 @@ import { RedirectPage } from '@djangocfg/layouts/components/RedirectPage';
 | `@djangocfg/nextjs/pwa/worker` | Service worker creation helpers |
 | `@djangocfg/nextjs/sitemap` | Sitemap generation with i18n hreflang support |
 | `@djangocfg/nextjs/health` | Health check handlers |
-| `@djangocfg/nextjs/og-image` | OG image generation |
-| `@djangocfg/nextjs/og-image/utils` | OG image URL and metadata utilities |
-| `@djangocfg/nextjs/og-image/components` | OG image template components |
+| `@djangocfg/nextjs/og-image` | OG image URL builder for Django's `django_ogimage` renderer |
 | `@djangocfg/nextjs/navigation` | Route definitions, menu generation, navigation helpers |
 
 ## API Reference
@@ -609,54 +582,50 @@ createHealthHandler({
 
 ### OG Image
 
-#### `createOgImageHandler(config)`
+`@djangocfg/nextjs/og-image` builds typed URLs pointing to Django's `django_ogimage` renderer.
+No Edge Runtime, no `@vercel/og`, no JSX templates — Django renders and caches the PNG.
 
-Creates an OG image generation handler with custom template component.
+See [`src/og-image/README.md`](./src/og-image/README.md) for full docs including URL resolution logic and deployment examples.
+
+#### `withOgImage(metadata, params)`
+
+Merges OG image into an existing `Metadata` object. Auto-extracts `title` if not in params.
 
 ```tsx
-createOgImageHandler({
-  template: (props: OgImageTemplateProps) => ReactElement; // Template component
-  defaultProps?: Partial<OgImageTemplateProps>;            // Default props
-  fonts?: Array<{ family: string; weight: number }>;       // Google Fonts to load
-  size?: { width: number; height: number };                 // Image dimensions
-  debug?: boolean;                                          // Enable debug mode
-})
+import { withOgImage } from '@djangocfg/nextjs/og-image'
+
+export async function generateMetadata(): Promise<Metadata> {
+  return withOgImage(
+    { title: 'My Page', description: 'Description' },
+    { preset: 'DARK_BLUE', layout: 'HERO' }
+  )
+}
 ```
 
-#### `generateAppMetadata(metadata, params?, options?)`
+#### `createOgMetadata(params)`
 
-Automatically adds OG image to Next.js metadata.
+Returns a `Metadata` fragment with `openGraph.images` + `twitter.images`.
 
 ```tsx
-generateAppMetadata(
-  metadata: Metadata,                    // Base metadata
-  ogImageParams?: Partial<OgImageUrlParams>, // Optional explicit params
-  options?: {
-    ogImageBaseUrl?: string;             // Default: '/api/og'
-    siteUrl?: string;                    // Auto-detected if not provided
-    defaultParams?: Partial<OgImageUrlParams>; // Default params
-    useBase64?: boolean;                  // Default: true
-  }
-)
-```
+import { createOgMetadata } from '@djangocfg/nextjs/og-image'
 
-#### `generateOgImageUrl(baseUrl, params, useBase64?)`
+export async function generateMetadata() {
+  return createOgMetadata({ title: 'Page', preset: 'DARK_BLUE' })
+}
+```
 
-> **Note:** This utility has been moved to `@djangocfg/layouts/utils/og-image` for client-side usage.
+#### `buildOgUrl(params)`
 
-For server-side usage, you can still use it from `@djangocfg/nextjs/og-image/utils`, but for client components, import from layouts:
+Returns the raw URL string. Useful when you need the URL outside of metadata.
 
 ```tsx
-// Client component
-import { generateOgImageUrl } from '@djangocfg/layouts/utils/og-image';
+import { buildOgUrl } from '@djangocfg/nextjs/og-image'
 
-const url = generateOgImageUrl('/api/og', {
-  title: 'My Page',
-  description: 'Page description',
-  siteName: 'My Site',
-});
+const url = buildOgUrl({ title: 'Hello', preset: 'DARK_BLUE' })
 ```
 
+**URL resolution** (`NEXT_PUBLIC_MEDIA_URL` → `NEXT_PUBLIC_API_URL` → `NEXT_PUBLIC_SITE_URL` → relative).
+
 ### Navigation
 
 #### `defineRoute(path, metadata, config?)`

package/dist/config/index.mjs

@@ -14,7 +14,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@djangocfg/nextjs",
-      version: "2.1.225",
+      version: "2.1.227",
       description: "Next.js server utilities: sitemap, health, OG images, contact forms, navigation, config",
       keywords: [
         "nextjs",
@@ -58,21 +58,6 @@ var require_package = __commonJS({
           import: "./dist/health/index.mjs",
           default: "./dist/health/index.mjs"
         },
-        "./og-image": {
-          types: "./dist/og-image/index.d.mts",
-          import: "./dist/og-image/index.mjs",
-          default: "./dist/og-image/index.mjs"
-        },
-        "./og-image/utils": {
-          types: "./dist/og-image/utils/index.d.mts",
-          import: "./dist/og-image/utils/index.mjs",
-          default: "./dist/og-image/utils/index.mjs"
-        },
-        "./og-image/components": {
-          types: "./dist/og-image/components/index.d.mts",
-          import: "./dist/og-image/components/index.mjs",
-          default: "./dist/og-image/components/index.mjs"
-        },
         "./navigation": {
           types: "./dist/navigation/index.d.mts",
           import: "./dist/navigation/index.mjs",
@@ -103,6 +88,11 @@ var require_package = __commonJS({
           import: "./dist/pwa/worker/index.mjs",
           default: "./dist/pwa/worker/index.mjs"
         },
+        "./og-image": {
+          types: "./dist/og-image/index.d.mts",
+          import: "./dist/og-image/index.mjs",
+          default: "./dist/og-image/index.mjs"
+        },
         "./monitor": {
           types: "./dist/monitor/index.d.mts",
           import: "./dist/monitor/index.mjs",
@@ -201,7 +191,6 @@ var require_package = __commonJS({
         "@types/react-dom": "^19.1.0",
         "@types/semver": "^7.7.1",
         "@types/webpack": "^5.28.5",
-        "@vercel/og": "^0.8.5",
         eslint: "^9.37.0",
         "lucide-react": "^0.545.0",
         tsup: "^8.0.1",