@djangocfg/nextjs 1.0.1

package/src/og-image/route.tsx

@@ -0,0 +1,253 @@
+/**
+ * OG Image Route Handler
+ *
+ * Factory function to create OG Image route handler for Next.js App Router
+ *
+ * Usage:
+ * ```tsx
+ * // app/api/og/route.tsx
+ * import { createOgImageHandler } from '@djangocfg/nextjs/og-image';
+ * import { MyTemplate } from './templates';
+ *
+ * export const { GET, runtime } = createOgImageHandler({
+ *   template: MyTemplate,
+ *   defaultProps: {
+ *     siteName: 'My Site',
+ *   },
+ *   fonts: [{ family: 'Manrope', weight: 700 }],
+ * });
+ * ```
+ */
+
+import { ImageResponse } from 'next/og';
+import { NextRequest } from 'next/server';
+import type { ReactElement } from 'react';
+import { loadGoogleFonts } from './utils';
+import { parseOgImageData } from './utils/url';
+import { DefaultTemplate } from './components/DefaultTemplate';
+import type { OgImageTemplateProps } from './types';
+
+export interface OgImageHandlerConfig {
+  /** Custom template component (optional, defaults to DefaultTemplate) */
+  template?: (props: OgImageTemplateProps) => ReactElement;
+  /** Default props to merge with query params */
+  defaultProps?: Partial<OgImageTemplateProps>;
+  /** Google Fonts to load */
+  fonts?: Array<{ family: string; weight: 400 | 500 | 600 | 700 | 800 | 900 }>;
+  /** Image size */
+  size?: { width: number; height: number };
+  /** Enable debug mode */
+  debug?: boolean;
+}
+
+/**
+ * Factory function to create OG Image route handler
+ * 
+ * @example
+ * ```tsx
+ * // app/api/og/route.tsx
+ * import { createOgImageHandler } from '@djangocfg/nextjs/og-image';
+ * import { MyTemplate } from '@/components/MyTemplate';
+ * 
+ * export const { GET, runtime } = createOgImageHandler({
+ *   template: MyTemplate,
+ *   defaultProps: { siteName: 'My Site' },
+ *   fonts: [{ family: 'Inter', weight: 700 }],
+ * });
+ * ```
+ */
+export function createOgImageHandler(config: OgImageHandlerConfig) {
+  const {
+    template: Template = DefaultTemplate,
+    defaultProps = {},
+    fonts: fontConfig = [],
+    size = { width: 1200, height: 630 },
+    debug = false,
+  } = config;
+
+  async function GET(req: NextRequest) {
+    let searchParams: URLSearchParams = new URLSearchParams();
+    
+    // Try to get searchParams from multiple sources
+    if (req.nextUrl?.searchParams && req.nextUrl.searchParams.size > 0) {
+      searchParams = req.nextUrl.searchParams;
+    } else if (req.nextUrl?.search && req.nextUrl.search.length > 1) {
+      searchParams = new URLSearchParams(req.nextUrl.search);
+    } else {
+      try {
+        const url = new URL(req.url);
+        if (url.searchParams.size > 0) {
+          searchParams = url.searchParams;
+        }
+      } catch (error) {
+        // Ignore
+      }
+      
+      if (searchParams.size === 0 && req.url) {
+        const queryIndex = req.url.indexOf('?');
+        if (queryIndex !== -1) {
+          const queryString = req.url.substring(queryIndex + 1);
+          searchParams = new URLSearchParams(queryString);
+        }
+      }
+      
+      if (searchParams.size === 0) {
+        const customParams = req.headers.get('x-og-search-params');
+        if (customParams) {
+          searchParams = new URLSearchParams(customParams);
+        }
+      }
+    }
+
+    // Initialize with defaults
+    let title = defaultProps.title || 'Untitled';
+    let subtitle = defaultProps.subtitle || '';
+    let description = defaultProps.description || subtitle;
+
+    // Support base64 data parameter (priority: base64 > query params > defaults)
+    const dataParam = searchParams.get('data');
+    
+    if (dataParam) {
+      try {
+        const paramsObj: Record<string, string> = { data: dataParam };
+        for (const [key, value] of searchParams.entries()) {
+          if (key !== 'data') {
+            paramsObj[key] = value;
+          }
+        }
+        const decodedData = parseOgImageData(paramsObj);
+        
+        // Base64 data takes precedence - apply all decoded values
+        if (decodedData.title && typeof decodedData.title === 'string' && decodedData.title.trim() !== '') {
+          title = decodedData.title.trim();
+        }
+        if (decodedData.subtitle && typeof decodedData.subtitle === 'string' && decodedData.subtitle.trim() !== '') {
+          subtitle = decodedData.subtitle.trim();
+        }
+        if (decodedData.description && typeof decodedData.description === 'string' && decodedData.description.trim() !== '') {
+          description = decodedData.description.trim();
+        }
+      } catch (error) {
+        // Silently fall back to defaults
+      }
+    }
+
+    // Fallback to query params if not set from base64
+    if (!title || title === 'Untitled') {
+      const titleParam = searchParams.get('title');
+      if (titleParam) {
+        title = titleParam;
+      }
+    }
+    if (!subtitle) {
+      const subtitleParam = searchParams.get('subtitle');
+      if (subtitleParam) {
+        subtitle = subtitleParam;
+      }
+    }
+    if (!description || description === subtitle) {
+      const descParam = searchParams.get('description');
+      if (descParam) {
+        description = descParam;
+      }
+    }
+
+    // Load fonts if configured
+    let fonts: any[] = [];
+    if (fontConfig.length > 0) {
+      fonts = await loadGoogleFonts(fontConfig);
+    }
+
+    // Merge props
+    const templateProps: OgImageTemplateProps = {
+      ...defaultProps,
+      title,
+      subtitle,
+      description,
+    };
+
+
+    return new ImageResponse(
+      <Template {...templateProps} />,
+      {
+        width: size.width,
+        height: size.height,
+        fonts,
+        debug: debug || process.env.NODE_ENV === 'development',
+      }
+    );
+  }
+
+  return {
+    GET,
+    runtime: 'edge' as const,
+  };
+}
+
+/**
+ * Create OG Image route handler for dynamic route with path parameter
+ * 
+ * This is a convenience wrapper for Next.js dynamic routes like `/api/og/[data]/route.tsx`.
+ * It extracts the `data` parameter from the path and passes it to the handler as a query parameter.
+ * Also handles static export mode automatically.
+ * 
+ * @example
+ * ```tsx
+ * // app/api/og/[data]/route.tsx
+ * import { createOgImageDynamicRoute } from '@djangocfg/nextjs/og-image';
+ * import { OgImageTemplate } from '@/components/OgImageTemplate';
+ * 
+ * export const runtime = 'nodejs';
+ * export const dynamic = 'force-static';
+ * export const revalidate = false;
+ * 
+ * const handler = createOgImageDynamicRoute({
+ *   template: OgImageTemplate,
+ *   defaultProps: {
+ *     siteName: 'My App',
+ *     logo: '/logo.svg',
+ *   },
+ * });
+ * 
+ * export async function GET(
+ *   request: NextRequest,
+ *   { params }: { params: { data: string } }
+ ) {
+ *   return handler(request, params);
+ * }
+ * ```
+ */
+export function createOgImageDynamicRoute(config: OgImageHandlerConfig) {
+  const handler = createOgImageHandler(config);
+  const isStaticBuild = typeof process !== 'undefined' && process.env.NEXT_PUBLIC_STATIC_BUILD === 'true';
+
+  return async function GET(
+    request: NextRequest,
+    context: { params: Promise<{ data: string }> }
+  ) {
+    // In static export mode, return a simple error response
+    if (isStaticBuild) {
+      return new Response('OG Image generation is not available in static export mode', {
+        status: 404,
+        headers: { 'Content-Type': 'text/plain' },
+      });
+    }
+
+    // Await params (Next.js 15+ uses Promise)
+    const params = await context.params;
+    
+    // Extract data from path parameter
+    const dataParam = params.data;
+    
+    // Create a request with the data parameter as a query param for the handler
+    const url = new URL(request.url);
+    url.searchParams.set('data', dataParam);
+    
+    const modifiedRequest = new NextRequest(url.toString(), {
+      method: request.method,
+      headers: request.headers,
+    });
+
+    return handler.GET(modifiedRequest);
+  };
+}

package/src/og-image/types.ts

@@ -0,0 +1,46 @@
+/**
+ * OG Image Types
+ * 
+ * Shared types for OG image templates and handlers
+ * This file is safe to import in client components
+ */
+
+export interface OgImageTemplateProps {
+  // Content
+  title: string;
+  description?: string;
+  subtitle?: string;
+  siteName?: string;
+  logo?: string;
+  
+  // Visibility flags
+  showLogo?: boolean;
+  showSiteName?: boolean;
+  
+  // Background customization
+  backgroundType?: 'gradient' | 'solid';
+  gradientStart?: string;
+  gradientEnd?: string;
+  backgroundColor?: string;
+  
+  // Typography - Title
+  titleSize?: number;
+  titleWeight?: number;
+  titleColor?: string;
+  
+  // Typography - Description
+  descriptionSize?: number;
+  descriptionColor?: string;
+  
+  // Typography - Site Name
+  siteNameSize?: number;
+  siteNameColor?: string;
+  
+  // Layout
+  padding?: number;
+  logoSize?: number;
+  
+  // Dev mode (for debugging)
+  devMode?: boolean;
+}
+

package/src/og-image/utils/fonts.ts

@@ -0,0 +1,150 @@
+/**
+ * Font Utilities for OG Image Generation
+ *
+ * Provides dynamic font loading from Google Fonts without requiring files in public/
+ * Based on Vercel's official @vercel/og documentation
+ */
+
+export interface FontConfig {
+  name: string;
+  weight?: 400 | 500 | 600 | 700 | 800 | 900;
+  style?: 'normal' | 'italic';
+  data: ArrayBuffer;
+}
+
+/**
+ * Load a Google Font dynamically
+ *
+ * @param font - Font family name (e.g., "Inter", "Roboto", "Manrope")
+ * @param text - Text to optimize font for (optional, reduces file size)
+ * @param weight - Font weight (default: 700)
+ * @returns ArrayBuffer of font data
+ *
+ * @example
+ * const fontData = await loadGoogleFont('Manrope', 'Hello World', 700);
+ */
+export async function loadGoogleFont(
+  font: string,
+  text?: string,
+  weight: number = 700
+): Promise<ArrayBuffer> {
+  // Construct Google Fonts API URL
+  let url = `https://fonts.googleapis.com/css2?family=${font}:wght@${weight}`;
+
+  // Add text parameter to optimize font subset (reduces size)
+  if (text) {
+    url += `&text=${encodeURIComponent(text)}`;
+  }
+
+  try {
+    // Fetch CSS containing font URL
+    const css = await fetch(url, {
+      headers: {
+        // Required to get TTF format instead of WOFF2
+        'User-Agent':
+          'Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_8; de-at) AppleWebKit/533.21.1 (KHTML, like Gecko) Version/5.0.5 Safari/533.21.1',
+      },
+    }).then((res) => res.text());
+
+    // Extract font URL from CSS
+    const resource = css.match(/src: url\((.+)\) format\('(opentype|truetype)'\)/);
+
+    if (!resource || !resource[1]) {
+      throw new Error(`Failed to parse font URL from CSS for font: ${font}`);
+    }
+
+    // Fetch actual font file
+    const response = await fetch(resource[1]);
+
+    if (response.status !== 200) {
+      throw new Error(`Failed to fetch font data: HTTP ${response.status}`);
+    }
+
+    return await response.arrayBuffer();
+  } catch (error) {
+    console.error(`Error loading Google Font "${font}":`, error);
+    throw new Error(`Failed to load font "${font}": ${error instanceof Error ? error.message : 'Unknown error'}`);
+  }
+}
+
+/**
+ * Load multiple Google Fonts
+ *
+ * @param fonts - Array of font configurations to load
+ * @returns Array of FontConfig objects ready for ImageResponse
+ *
+ * @example
+ * const fonts = await loadGoogleFonts([
+ *   { family: 'Manrope', weight: 700 },
+ *   { family: 'Inter', weight: 400 }
+ * ]);
+ */
+export async function loadGoogleFonts(
+  fonts: Array<{
+    family: string;
+    weight?: 400 | 500 | 600 | 700 | 800 | 900;
+    style?: 'normal' | 'italic';
+    text?: string;
+  }>
+): Promise<FontConfig[]> {
+  const fontConfigs = await Promise.all(
+    fonts.map(async ({ family, weight = 700, style = 'normal', text }) => {
+      const data = await loadGoogleFont(family, text, weight);
+      return {
+        name: family,
+        weight,
+        style,
+        data,
+      };
+    })
+  );
+
+  return fontConfigs;
+}
+
+/**
+ * Create a font loader with caching
+ *
+ * Useful for reusing font data across multiple OG image requests
+ *
+ * @example
+ * const fontLoader = createFontLoader();
+ * const font = await fontLoader.load('Manrope', 700);
+ */
+export function createFontLoader() {
+  const cache = new Map<string, Promise<ArrayBuffer>>();
+
+  return {
+    /**
+     * Load a font with caching
+     */
+    async load(
+      family: string,
+      weight: number = 700,
+      text?: string
+    ): Promise<ArrayBuffer> {
+      const cacheKey = `${family}-${weight}-${text || 'all'}`;
+
+      if (!cache.has(cacheKey)) {
+        cache.set(cacheKey, loadGoogleFont(family, text, weight));
+      }
+
+      return cache.get(cacheKey)!;
+    },
+
+    /**
+     * Clear the cache
+     */
+    clear() {
+      cache.clear();
+    },
+
+    /**
+     * Get cache size
+     */
+    size() {
+      return cache.size;
+    },
+  };
+}
+

package/src/og-image/utils/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Utilities for OG Image Generation
+ */
+
+export {
+  loadGoogleFont,
+  loadGoogleFonts,
+  createFontLoader,
+  type FontConfig,
+} from './fonts';
+
+export {
+  generateOgImageUrl,
+  getAbsoluteOgImageUrl,
+  createOgImageUrlBuilder,
+  parseOgImageUrl,
+  parseOgImageData,
+  encodeBase64,
+  decodeBase64,
+  type OgImageUrlParams,
+} from './url';
+
+export {
+  generateOgImageMetadata,
+  createOgImageMetadataGenerator,
+  type OgImageMetadataOptions,
+} from './metadata';
+

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

@@ -0,0 +1,235 @@
+/**
+ * Metadata Utilities for OG Images
+ *
+ * Helpers to automatically add og:image to Next.js metadata
+ */
+
+import type { Metadata } from 'next';
+import { generateOgImageUrl, getAbsoluteOgImageUrl, type OgImageUrlParams } from './url';
+
+/**
+ * Options for generating OG image metadata
+ */
+export interface OgImageMetadataOptions {
+  /** Base URL of the OG image API route (e.g., '/api/og') */
+  ogImageBaseUrl?: string;
+  /** Site URL for absolute URLs (e.g., 'https://example.com') */
+  siteUrl?: string;
+  /** Default parameters to merge with page-specific params */
+  defaultParams?: Partial<OgImageUrlParams>;
+  /** Whether to use base64 encoding (default: true) */
+  useBase64?: boolean;
+}
+
+/**
+ * Extract title from metadata
+ */
+function extractTitle(metadata: Metadata): string {
+  if (typeof metadata.title === 'string') {
+    return metadata.title;
+  }
+  if (metadata.title) {
+    if ('default' in metadata.title) {
+      return metadata.title.default;
+    }
+    if ('absolute' in metadata.title) {
+      return metadata.title.absolute;
+    }
+  }
+  return '';
+}
+
+/**
+ * Extract description from metadata
+ */
+function extractDescription(metadata: Metadata): string {
+  if (typeof metadata.description === 'string') {
+    return metadata.description;
+  }
+  return '';
+}
+
+/**
+ * Generate Next.js metadata with OG image
+ *
+ * Automatically adds og:image, twitter:image, and other OG meta tags
+ * Automatically extracts title and description from metadata if not provided
+ *
+ * @param metadata - Base metadata object
+ * @param ogImageParams - Optional parameters for OG image generation (if not provided, extracted from metadata)
+ * @param options - Configuration options
+ * @returns Enhanced metadata with OG image
+ *
+ * @example
+ * ```typescript
+ * // In page.tsx or layout.tsx
+ * import { generateOgImageMetadata } from '@djangocfg/nextjs/og-image';
+ * import { settings } from '@/core/settings';
+ *
+ * export const metadata = generateOgImageMetadata(
+ *   {
+ *     title: 'My Page',
+ *     description: 'Page description',
+ *   },
+ *   undefined, // Will auto-extract from metadata
+ *   {
+ *     ogImageBaseUrl: '/api/og',
+ *     siteUrl: settings.app.siteUrl,
+ *     defaultParams: {
+ *       siteName: settings.app.name,
+ *       logo: settings.app.icons.logoVector,
+ *     },
+ *   }
+ * );
+ * ```
+ */
+/**
+ * Get site URL automatically from environment
+ * Priority: NEXT_PUBLIC_SITE_URL > VERCEL_URL > fallback
+ */
+function getSiteUrl(): string {
+  // Try NEXT_PUBLIC_SITE_URL first (most reliable)
+  if (typeof process !== 'undefined' && process.env.NEXT_PUBLIC_SITE_URL) {
+    return process.env.NEXT_PUBLIC_SITE_URL;
+  }
+  
+  // Fallback to VERCEL_URL if available
+  if (typeof process !== 'undefined' && process.env.VERCEL_URL) {
+    return `https://${process.env.VERCEL_URL}`;
+  }
+  
+  // Development fallback
+  return 'http://localhost:3000';
+}
+
+export function generateOgImageMetadata(
+  metadata: Metadata,
+  ogImageParams?: Partial<OgImageUrlParams>,
+  options: OgImageMetadataOptions = {}
+): Metadata {
+  const {
+    ogImageBaseUrl = '/api/og',
+    siteUrl: providedSiteUrl,
+    defaultParams = {},
+    useBase64 = true,
+  } = options;
+
+  // Automatically determine siteUrl if not provided or is undefined
+  const siteUrl = providedSiteUrl && providedSiteUrl !== 'undefined' 
+    ? providedSiteUrl 
+    : getSiteUrl();
+
+  // Auto-extract title and description from metadata if not provided
+  const extractedTitle = extractTitle(metadata);
+  const extractedDescription = extractDescription(metadata);
+
+  // Merge with provided params (provided params take precedence)
+  const finalOgImageParams: OgImageUrlParams = {
+    ...defaultParams,
+    title: ogImageParams?.title || extractedTitle || defaultParams.title || '',
+    description: ogImageParams?.description || extractedDescription || defaultParams.description || '',
+    ...ogImageParams,
+  };
+
+  // Get alt text for image (title or siteName as fallback)
+  const imageAlt = finalOgImageParams.title || finalOgImageParams.siteName;
+
+  // Generate relative OG image URL
+  const relativeOgImageUrl = generateOgImageUrl(
+    ogImageBaseUrl,
+    finalOgImageParams,
+    useBase64
+  );
+
+  // CRITICAL: Use absolute URL to ensure query params are preserved
+  // Next.js might strip query params from relative URLs in some cases
+  // Absolute URLs ensure the full URL with params is used
+  const ogImageUrl = siteUrl
+    ? getAbsoluteOgImageUrl(relativeOgImageUrl, siteUrl)
+    : relativeOgImageUrl;
+
+  // Normalize existing images to arrays
+  const existingOgImages = metadata.openGraph?.images
+    ? Array.isArray(metadata.openGraph.images)
+      ? metadata.openGraph.images
+      : [metadata.openGraph.images]
+    : [];
+
+  const existingTwitterImages = metadata.twitter?.images
+    ? Array.isArray(metadata.twitter.images)
+      ? metadata.twitter.images
+      : [metadata.twitter.images]
+    : [];
+
+  // Merge with existing metadata
+  return {
+    ...metadata,
+    openGraph: {
+      ...metadata.openGraph,
+      images: [
+        ...existingOgImages,
+        {
+          url: ogImageUrl,
+          width: 1200,
+          height: 630,
+          alt: imageAlt,
+        },
+      ],
+    },
+    twitter: {
+      ...metadata.twitter,
+      card: 'summary_large_image',
+      images: [
+        ...existingTwitterImages,
+        {
+          url: ogImageUrl,
+          alt: imageAlt,
+        },
+      ],
+    },
+  };
+}
+
+/**
+ * Create OG image metadata generator with preset configuration
+ *
+ * Useful when you want to reuse the same configuration across multiple pages
+ *
+ * @param options - Configuration options
+ * @returns Metadata generator function
+ *
+ * @example
+ * ```typescript
+ * // In a shared file (e.g., lib/metadata.ts)
+ * import { createOgImageMetadataGenerator } from '@djangocfg/nextjs/og-image';
+ * import { settings } from '@/core/settings';
+ *
+ * export const generateMetadata = createOgImageMetadataGenerator({
+ *   ogImageBaseUrl: '/api/og',
+ *   siteUrl: settings.app.siteUrl,
+ *   defaultParams: {
+ *     siteName: settings.app.name,
+ *     logo: settings.app.icons.logoVector,
+ *   },
+ * });
+ *
+ * // In page.tsx
+ * import { generateMetadata } from '@/lib/metadata';
+ *
+ * export const metadata = generateMetadata({
+ *   title: 'My Page',
+ *   description: 'Description',
+ * });
+ * ```
+ */
+export function createOgImageMetadataGenerator(
+  options: OgImageMetadataOptions
+) {
+  return (
+    metadata: Metadata,
+    ogImageParams?: Partial<OgImageUrlParams>
+  ): Metadata => {
+    return generateOgImageMetadata(metadata, ogImageParams, options);
+  };
+}
+