@djangocfg/nextjs 1.0.1 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/nextjs",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Next.js utilities and components: sitemap, health, OG images, legal pages, error pages",
   "keywords": [
     "nextjs",
@@ -109,14 +109,14 @@
     "next": "^15.4.4",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
-    "@djangocfg/ui": "^1.4.31",
-    "@djangocfg/layouts": "^2.0.1",
-    "@djangocfg/api": "^1.4.31",
+    "@djangocfg/ui": "^1.4.33",
+    "@djangocfg/layouts": "^2.0.3",
+    "@djangocfg/api": "^1.4.33",
     "lucide-react": "^0.469.0"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^1.4.31",
-    "@djangocfg/layouts": "^2.0.1",
+    "@djangocfg/typescript-config": "^1.4.33",
+    "@djangocfg/layouts": "^2.0.3",
     "@types/node": "^24.7.2",
     "@types/react": "19.2.2",
     "@types/react-dom": "19.2.1",

package/src/components/HomePage.tsx

@@ -1,8 +1,8 @@
 'use client';
 
 import { useEffect } from 'react';
-import { useRouter } from 'next/navigation';
 import { useAuth } from '@djangocfg/layouts';
+import { useRouter } from '@djangocfg/ui/hooks';
 import { Loader2 } from 'lucide-react';
 
 export interface HomePageProps {

package/src/config/base-next-config.ts

@@ -23,6 +23,7 @@
 
 import type { NextConfig } from 'next';
 import type { Configuration as WebpackConfig } from 'webpack';
+import { deepMerge } from './deepMerge';
 
 // ─────────────────────────────────────────────────────────────────────────
 // Standard Environment Variables
@@ -36,10 +37,8 @@ const isDev = process.env.NODE_ENV === 'development';
 // ─────────────────────────────────────────────────────────────────────────
 
 export interface BaseNextConfigOptions {
-  /** Base path for static builds (default: '/cfg/admin') */
-  basePath?: string;
-  /** Static build path - used when NEXT_PUBLIC_STATIC_BUILD=true (overrides basePath for static builds) */
-  staticBuildPath?: string;
+  /** Static build path (used when NEXT_PUBLIC_STATIC_BUILD=true) */
+  isDefaultCfgAdmin?: boolean;
   /** Additional transpile packages (merged with defaults) */
   transpilePackages?: string[];
   /** Additional optimize package imports (merged with defaults) */
@@ -47,7 +46,7 @@ export interface BaseNextConfigOptions {
   /** Custom webpack configuration function (called after base webpack logic) */
   webpack?: (
     config: WebpackConfig,
-    options: { isServer: boolean; dev: boolean; [key: string]: any }
+    options: { isServer: boolean; dev: boolean;[key: string]: any }
   ) => WebpackConfig | void;
   /** Custom experimental options (merged with defaults) */
   experimental?: NextConfig['experimental'];
@@ -57,38 +56,6 @@ export interface BaseNextConfigOptions {
   [key: string]: any;
 }
 
-// ─────────────────────────────────────────────────────────────────────────
-// Deep Merge Helper (simple implementation)
-// ─────────────────────────────────────────────────────────────────────────
-
-function deepMerge<T extends Record<string, any>>(target: T, source: Partial<T>): T {
-  const output = { ...target };
-  
-  for (const key in source) {
-    if (source[key] === undefined) continue;
-    
-    // Arrays: replace (don't merge arrays)
-    if (Array.isArray(source[key])) {
-      output[key] = source[key] as any;
-    }
-    // Objects: deep merge
-    else if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])) {
-      const targetValue = output[key];
-      if (targetValue && typeof targetValue === 'object' && !Array.isArray(targetValue)) {
-        output[key] = deepMerge(targetValue, source[key] as any);
-      } else {
-        output[key] = source[key] as any;
-      }
-    }
-    // Primitives: replace
-    else {
-      output[key] = source[key] as any;
-    }
-  }
-  
-  return output;
-}
-
 // ─────────────────────────────────────────────────────────────────────────
 // Base Configuration Factory
 // ─────────────────────────────────────────────────────────────────────────
@@ -102,10 +69,12 @@ function deepMerge<T extends Record<string, any>>(target: T, source: Partial<T>)
 export function createBaseNextConfig(
   options: BaseNextConfigOptions = {}
 ): NextConfig {
-  // Determine basePath: staticBuildPath takes precedence for static builds, then basePath, then default
-  const basePath = isStaticBuild 
-    ? (options.staticBuildPath || options.basePath)
-    : (options.basePath || '');
+
+  // If static build not provided, use default for nextjs-admin development
+  const staticBuildPath = options.isDefaultCfgAdmin ? '/cfg/admin' : '/cfg/nextjs-admin';
+  const basePath = isStaticBuild ? staticBuildPath : '';
+  const apiUrl = isStaticBuild ? '' : process.env.NEXT_PUBLIC_API_URL || '';
+  const siteUrl = isStaticBuild ? '' : process.env.NEXT_PUBLIC_SITE_URL || '';
 
   // Base configuration
   const baseConfig: NextConfig = {
@@ -116,8 +85,8 @@ export function createBaseNextConfig(
     ...(isStaticBuild && {
       output: 'export' as const,
       distDir: 'out',
-      basePath,
-      assetPrefix: basePath,
+      basePath: basePath,
+      // assetPrefix: basePath,
       // Fix for Next.js 15.5.4: prevent 500.html generation issue
       // 
       // PROBLEM: In App Router, error.tsx is a client component ('use client')
@@ -139,7 +108,8 @@ export function createBaseNextConfig(
     // Environment variables
     env: {
       NEXT_PUBLIC_BASE_PATH: basePath,
-      NEXT_PUBLIC_API_URL: isStaticBuild ? '' : process.env.NEXT_PUBLIC_API_URL,
+      NEXT_PUBLIC_API_URL: apiUrl,
+      NEXT_PUBLIC_SITE_URL: siteUrl,
       ...options.env,
     },
 
@@ -180,7 +150,7 @@ export function createBaseNextConfig(
     },
 
     // Webpack configuration
-    webpack: (config: WebpackConfig, webpackOptions: { isServer: boolean; dev: boolean; [key: string]: any }) => {
+    webpack: (config: WebpackConfig, webpackOptions: { isServer: boolean; dev: boolean;[key: string]: any }) => {
       const { isServer, dev } = webpackOptions;
 
       // Dev mode optimizations
@@ -199,13 +169,17 @@ export function createBaseNextConfig(
         buildDependencies: {},
       };
 
+      // Note: Dynamic API routes should use `export const dynamic = 'force-dynamic'`
+      // in the route file itself to exclude them from static export.
+      // This is simpler than using webpack plugins.
+
       // Compression plugins (only for static build in production)
       // Note: compression-webpack-plugin should be installed in the consuming project
       if (!isServer && isStaticBuild && !dev) {
         try {
           // Dynamic import to avoid bundling compression-webpack-plugin
           const CompressionPlugin = require('compression-webpack-plugin');
-          
+
           // Gzip compression
           config.plugins.push(
             new CompressionPlugin({
@@ -251,7 +225,6 @@ export function createBaseNextConfig(
 
   // Cleanup: Remove our custom options that are not part of NextConfig
   // These are internal to BaseNextConfigOptions and should not be in the final config
-  delete (finalConfig as any).basePath;
   delete (finalConfig as any).optimizePackageImports;
   // Note: We don't delete transpilePackages, experimental, env, webpack
   // as they are valid NextConfig keys and may have been overridden by user

package/src/config/deepMerge.ts

@@ -0,0 +1,33 @@
+
+// ─────────────────────────────────────────────────────────────────────────
+// Deep Merge Helper (simple implementation)
+// ─────────────────────────────────────────────────────────────────────────
+
+export function deepMerge<T extends Record<string, any>>(target: T, source: Partial<T>): T {
+    const output = { ...target };
+  
+    for (const key in source) {
+      if (source[key] === undefined) continue;
+  
+      // Arrays: replace (don't merge arrays)
+      if (Array.isArray(source[key])) {
+        output[key] = source[key] as any;
+      }
+      // Objects: deep merge
+      else if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])) {
+        const targetValue = output[key];
+        if (targetValue && typeof targetValue === 'object' && !Array.isArray(targetValue)) {
+          output[key] = deepMerge(targetValue, source[key] as any);
+        } else {
+          output[key] = source[key] as any;
+        }
+      }
+      // Primitives: replace
+      else {
+        output[key] = source[key] as any;
+      }
+    }
+  
+    return output;
+  }
+  

package/src/navigation/index.ts

@@ -6,4 +6,3 @@
 
 export * from './types';
 export * from './utils';
-

package/src/navigation/utils.ts

@@ -10,40 +10,24 @@ import type { RouteDefinition, RouteMetadata, MenuItem } from './types';
 // Route Definition Helper
 // ─────────────────────────────────────────────────────────────────────────
 
-export interface RouteConfig {
-  /** Base path for static builds (optional) */
-  basePath?: string;
-  /** Whether this is a static build (optional, defaults to false) */
-  isStaticBuild?: boolean;
-}
-
 /**
- * Manage base path for routes
- */
-function manageBasePath(path: string, config?: RouteConfig): string {
-  if (!config?.isStaticBuild || !config?.basePath) {
-    return path;
-  }
-  return `${config.basePath}${path}`;
-}
-
-/**
- * Define a route with automatic basePath injection
+ * Define a route with metadata
  *
- * NOTE: For static builds, Next.js automatically prepends basePath to <Link> hrefs,
- * so we don't add it here. For dev mode, we need to add it manually.
+ * IMPORTANT: Next.js automatically handles basePath for <Link> components when
+ * basePath is set in next.config.ts. We should NOT add basePath manually here,
+ * as it would cause double-prefixing in static builds.
+ *
+ * @param path - Route path (e.g., '/dashboard', '/admin/users')
+ * @param metadata - Route metadata (label, icon, etc.)
  */
 export function defineRoute(
   path: string,
   metadata: RouteMetadata,
-  config?: RouteConfig
 ): RouteDefinition {
-  // In static builds, Next.js handles basePath automatically
-  // In dev mode, we need to add it manually for consistency
-  const fullPath = manageBasePath(path, config);
-
+  // Always return path as-is. Next.js will handle basePath automatically
+  // for <Link> components when basePath is set in next.config.ts
   return {
-    path: fullPath,
+    path,
     metadata,
   };
 }
@@ -58,11 +42,11 @@ export function defineRoute(
 export function getUnauthenticatedRedirect(
   path: string,
   authPath: string = '/auth',
-  config?: RouteConfig
 ): string | null {
   if (path.startsWith('/private') || path.startsWith('/admin')) {
-    // In static builds, Next.js handles basePath automatically
-    return manageBasePath(authPath, config);
+    // Return path as-is. Next.js will handle basePath automatically for router.push()
+    // when basePath is set in next.config.ts
+    return authPath;
   }
   return null;
 }
@@ -72,10 +56,10 @@ export function getUnauthenticatedRedirect(
  */
 export function redirectToAuth(
   authPath: string = '/auth',
-  config?: RouteConfig
 ): string {
-  // In static builds, Next.js handles basePath automatically
-  return manageBasePath(authPath, config);
+  // Return path as-is. Next.js will handle basePath automatically for router.push()
+  // when basePath is set in next.config.ts
+  return authPath;
 }
 
 // ─────────────────────────────────────────────────────────────────────────

package/src/og-image/route.tsx

@@ -105,7 +105,9 @@ export function createOgImageHandler(config: OgImageHandlerConfig) {
     let description = defaultProps.description || subtitle;
 
     // Support base64 data parameter (priority: base64 > query params > defaults)
+    // All template props can be encoded in base64, including styling params
     const dataParam = searchParams.get('data');
+    let decodedParams: Record<string, any> = {};
     
     if (dataParam) {
       try {
@@ -115,17 +117,17 @@ export function createOgImageHandler(config: OgImageHandlerConfig) {
             paramsObj[key] = value;
           }
         }
-        const decodedData = parseOgImageData(paramsObj);
+        decodedParams = 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 (decodedParams.title && typeof decodedParams.title === 'string' && decodedParams.title.trim() !== '') {
+          title = decodedParams.title.trim();
         }
-        if (decodedData.subtitle && typeof decodedData.subtitle === 'string' && decodedData.subtitle.trim() !== '') {
-          subtitle = decodedData.subtitle.trim();
+        if (decodedParams.subtitle && typeof decodedParams.subtitle === 'string' && decodedParams.subtitle.trim() !== '') {
+          subtitle = decodedParams.subtitle.trim();
         }
-        if (decodedData.description && typeof decodedData.description === 'string' && decodedData.description.trim() !== '') {
-          description = decodedData.description.trim();
+        if (decodedParams.description && typeof decodedParams.description === 'string' && decodedParams.description.trim() !== '') {
+          description = decodedParams.description.trim();
         }
       } catch (error) {
         // Silently fall back to defaults
@@ -158,12 +160,56 @@ export function createOgImageHandler(config: OgImageHandlerConfig) {
       fonts = await loadGoogleFonts(fontConfig);
     }
 
-    // Merge props
+    // Helper function to parse numeric/boolean values from decoded params
+    const parseValue = (value: any, type: 'number' | 'boolean' | 'string' = 'string'): any => {
+      if (value === undefined || value === null || value === '') {
+        return undefined;
+      }
+      if (type === 'number') {
+        const num = Number(value);
+        return isNaN(num) ? undefined : num;
+      }
+      if (type === 'boolean') {
+        if (typeof value === 'boolean') return value;
+        if (typeof value === 'string') {
+          return value.toLowerCase() === 'true' || value === '1';
+        }
+        return Boolean(value);
+      }
+      return String(value);
+    };
+
+    // Merge props: decoded params from URL override defaultProps
     const templateProps: OgImageTemplateProps = {
       ...defaultProps,
+      // Content
       title,
       subtitle,
       description,
+      // Override with decoded params if present
+      siteName: decodedParams.siteName || defaultProps.siteName,
+      logo: decodedParams.logo || defaultProps.logo,
+      // Background
+      backgroundType: (decodedParams.backgroundType as 'gradient' | 'solid') || defaultProps.backgroundType,
+      gradientStart: decodedParams.gradientStart || defaultProps.gradientStart,
+      gradientEnd: decodedParams.gradientEnd || defaultProps.gradientEnd,
+      backgroundColor: decodedParams.backgroundColor || defaultProps.backgroundColor,
+      // Typography - Title
+      titleSize: parseValue(decodedParams.titleSize, 'number') ?? defaultProps.titleSize,
+      titleWeight: parseValue(decodedParams.titleWeight, 'number') ?? defaultProps.titleWeight,
+      titleColor: decodedParams.titleColor || defaultProps.titleColor,
+      // Typography - Description
+      descriptionSize: parseValue(decodedParams.descriptionSize, 'number') ?? defaultProps.descriptionSize,
+      descriptionColor: decodedParams.descriptionColor || defaultProps.descriptionColor,
+      // Typography - Site Name
+      siteNameSize: parseValue(decodedParams.siteNameSize, 'number') ?? defaultProps.siteNameSize,
+      siteNameColor: decodedParams.siteNameColor || defaultProps.siteNameColor,
+      // Layout
+      padding: parseValue(decodedParams.padding, 'number') ?? defaultProps.padding,
+      logoSize: parseValue(decodedParams.logoSize, 'number') ?? defaultProps.logoSize,
+      // Visibility flags
+      showLogo: parseValue(decodedParams.showLogo, 'boolean') ?? defaultProps.showLogo,
+      showSiteName: parseValue(decodedParams.showSiteName, 'boolean') ?? defaultProps.showSiteName,
     };
 
 
@@ -221,7 +267,7 @@ 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(
+  async function GET(
     request: NextRequest,
     context: { params: Promise<{ data: string }> }
   ) {
@@ -249,5 +295,16 @@ export function createOgImageDynamicRoute(config: OgImageHandlerConfig) {
     });
 
     return handler.GET(modifiedRequest);
+  }
+
+  // For static export, provide generateStaticParams that returns empty array
+  // This allows the route to be excluded from static build
+  async function generateStaticParams(): Promise<Array<{ data: string }>> {
+    return [];
+  }
+
+  return {
+    GET,
+    generateStaticParams,
   };
 }

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

@@ -93,13 +93,8 @@ function getSiteUrl(): string {
     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';
+  return '';
 }
 
 export function generateOgImageMetadata(
@@ -108,7 +103,7 @@ export function generateOgImageMetadata(
   options: OgImageMetadataOptions = {}
 ): Metadata {
   const {
-    ogImageBaseUrl = '/api/og',
+    ogImageBaseUrl = 'https://djangocfg.com/api/og',
     siteUrl: providedSiteUrl,
     defaultParams = {},
     useBase64 = true,
@@ -161,8 +156,8 @@ export function generateOgImageMetadata(
       : [metadata.twitter.images]
     : [];
 
-  // Merge with existing metadata
-  return {
+  // Build final metadata object
+  const finalMetadata: Metadata = {
     ...metadata,
     openGraph: {
       ...metadata.openGraph,
@@ -188,6 +183,23 @@ export function generateOgImageMetadata(
       ],
     },
   };
+
+  // Automatically add metadataBase if siteUrl is an absolute URL
+  // metadataBase requires absolute URL - skip if siteUrl is relative path (like /cfg/admin)
+  // Only add if not already set in input metadata
+  if (!finalMetadata.metadataBase && siteUrl) {
+    // Check if siteUrl is an absolute URL (starts with http:// or https://)
+    if (siteUrl.startsWith('http://') || siteUrl.startsWith('https://')) {
+      try {
+        finalMetadata.metadataBase = new URL(siteUrl);
+      } catch (e) {
+        // If URL construction fails, skip metadataBase
+        // This shouldn't happen if we check for http/https, but just in case
+      }
+    }
+  }
+
+  return finalMetadata;
 }
 
 /**

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

@@ -45,6 +45,7 @@ function decodeBase64(str: string): string {
 
 /**
  * OG Image URL parameters
+ * All parameters can be encoded in URL via base64
  */
 export interface OgImageUrlParams {
   /** Page title */
@@ -55,6 +56,36 @@ export interface OgImageUrlParams {
   siteName?: string;
   /** Logo URL (optional) */
   logo?: string;
+  /** Background type: 'gradient' or 'solid' */
+  backgroundType?: 'gradient' | 'solid';
+  /** Gradient start color (hex) */
+  gradientStart?: string;
+  /** Gradient end color (hex) */
+  gradientEnd?: string;
+  /** Background color (for solid type) */
+  backgroundColor?: string;
+  /** Title font size (px) */
+  titleSize?: number;
+  /** Title font weight */
+  titleWeight?: number;
+  /** Title text color */
+  titleColor?: string;
+  /** Description font size (px) */
+  descriptionSize?: number;
+  /** Description text color */
+  descriptionColor?: string;
+  /** Site name font size (px) */
+  siteNameSize?: number;
+  /** Site name text color */
+  siteNameColor?: string;
+  /** Padding (px) */
+  padding?: number;
+  /** Logo size (px) */
+  logoSize?: number;
+  /** Show logo flag */
+  showLogo?: boolean;
+  /** Show site name flag */
+  showSiteName?: boolean;
   /** Additional custom parameters */
   [key: string]: string | number | boolean | undefined;
 }
@@ -69,12 +100,26 @@ export interface OgImageUrlParams {
  *
  * @example
  * ```typescript
- * // Base64 encoding (safe, default)
+ * // Base64 encoding (safe, default) - all parameters can be encoded
  * const url = generateOgImageUrl('/api/og', {
  *   title: 'My Page Title',
  *   description: 'Page description here',
+ *   siteName: 'My Site',
+ *   logo: '/logo.svg',
+ *   backgroundType: 'gradient',
+ *   gradientStart: '#0f172a',
+ *   gradientEnd: '#334155',
+ *   titleSize: 80,
+ *   titleWeight: 800,
+ *   titleColor: 'white',
+ *   descriptionSize: 36,
+ *   descriptionColor: 'rgba(226, 232, 240, 0.9)',
+ *   siteNameSize: 32,
+ *   siteNameColor: 'rgba(255, 255, 255, 0.95)',
+ *   padding: 80,
+ *   logoSize: 56,
  * });
- * // Result: /api/og?data=eyJ0aXRsZSI6Ik15IFBhZ2UgVGl0bGUiLCJkZXNjcmlwdGlvbiI6IlBhZ2UgZGVzY3JpcHRpb24gaGVyZSJ9
+ * // Result: /api/og/[base64-encoded-json]
  *
  * // Query params (legacy)
  * const url = generateOgImageUrl('/api/og', { title: 'Hello' }, false);