@djangocfg/nextjs 1.0.1

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

@@ -0,0 +1,262 @@
+/**
+ * Base Next.js Configuration Factory
+ *
+ * Universal, reusable Next.js config for all DjangoCFG projects
+ * Provides standard settings that can be extended per project
+ *
+ * @example
+ * ```typescript
+ * // In your project's next.config.ts
+ * import { createBaseNextConfig } from '@djangocfg/nextjs/config';
+ * import bundleAnalyzer from '@next/bundle-analyzer';
+ *
+ * const withBundleAnalyzer = bundleAnalyzer({
+ *   enabled: process.env.ANALYZE === 'true',
+ * });
+ *
+ * export default withBundleAnalyzer(createBaseNextConfig({
+ *   // Your project-specific overrides
+ *   transpilePackages: ['my-custom-package'],
+ * }));
+ * ```
+ */
+
+import type { NextConfig } from 'next';
+import type { Configuration as WebpackConfig } from 'webpack';
+
+// ─────────────────────────────────────────────────────────────────────────
+// Standard Environment Variables
+// ─────────────────────────────────────────────────────────────────────────
+
+const isStaticBuild = process.env.NEXT_PUBLIC_STATIC_BUILD === 'true';
+const isDev = process.env.NODE_ENV === 'development';
+
+// ─────────────────────────────────────────────────────────────────────────
+// Configuration Options
+// ─────────────────────────────────────────────────────────────────────────
+
+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;
+  /** Additional transpile packages (merged with defaults) */
+  transpilePackages?: string[];
+  /** Additional optimize package imports (merged with defaults) */
+  optimizePackageImports?: string[];
+  /** Custom webpack configuration function (called after base webpack logic) */
+  webpack?: (
+    config: WebpackConfig,
+    options: { isServer: boolean; dev: boolean; [key: string]: any }
+  ) => WebpackConfig | void;
+  /** Custom experimental options (merged with defaults) */
+  experimental?: NextConfig['experimental'];
+  /** Custom env variables (merged with defaults) */
+  env?: Record<string, string | undefined>;
+  /** Override any Next.js config option */
+  [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
+// ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * Create base Next.js configuration with standard DjangoCFG settings
+ *
+ * @param options - Custom configuration options to merge with base config
+ * @returns Next.js configuration function
+ */
+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 || '');
+
+  // Base configuration
+  const baseConfig: NextConfig = {
+    reactStrictMode: true,
+    trailingSlash: true,
+
+    // Static export configuration
+    ...(isStaticBuild && {
+      output: 'export' as const,
+      distDir: 'out',
+      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')
+      // and cannot be statically exported as 500.html. Next.js tries to create
+      // and move 500.html during static export, causing ENOENT error.
+      //
+      // SOLUTION: Use generateBuildId to work around the issue.
+      // The error.tsx component will still work in development/runtime mode.
+      generateBuildId: async () => {
+        return 'static-build';
+      },
+    }),
+
+    // Standalone output for Docker (only in production, not dev)
+    ...(!isStaticBuild && !isDev && {
+      output: 'standalone' as const,
+    }),
+
+    // Environment variables
+    env: {
+      NEXT_PUBLIC_BASE_PATH: basePath,
+      NEXT_PUBLIC_API_URL: isStaticBuild ? '' : process.env.NEXT_PUBLIC_API_URL,
+      ...options.env,
+    },
+
+    // Images configuration
+    images: {
+      unoptimized: true,
+    },
+
+    // Transpile packages (merge with user-provided)
+    transpilePackages: [
+      '@djangocfg/ui',
+      '@djangocfg/layouts',
+      '@djangocfg/nextjs',
+      '@djangocfg/api',
+      '@djangocfg/centrifugo',
+      ...(options.transpilePackages || []),
+    ],
+
+    // Experimental features
+    // Base optimizations first, then user options (user can override base settings)
+    experimental: {
+      // Optimize package imports (only in production)
+      ...(!isDev && {
+        optimizePackageImports: [
+          '@djangocfg/ui',
+          '@djangocfg/layouts',
+          'lucide-react',
+          'recharts',
+          ...(options.optimizePackageImports || []),
+        ],
+      }),
+      // Dev mode optimizations
+      ...(isDev && {
+        optimizeCss: false,
+      }),
+      // User experimental options applied last (can override base settings)
+      ...options.experimental,
+    },
+
+    // Webpack configuration
+    webpack: (config: WebpackConfig, webpackOptions: { isServer: boolean; dev: boolean; [key: string]: any }) => {
+      const { isServer, dev } = webpackOptions;
+
+      // Dev mode optimizations
+      if (dev) {
+        config.optimization = {
+          ...config.optimization,
+          removeAvailableModules: false,
+          removeEmptyChunks: false,
+          splitChunks: false, // Disable code splitting in dev for faster compilation
+        };
+      }
+
+      // Filesystem cache (dev and production)
+      config.cache = {
+        type: 'filesystem',
+        buildDependencies: {},
+      };
+
+      // 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({
+              filename: '[path][base].gz',
+              algorithm: 'gzip',
+              test: /\.(js|css|html|svg|json)$/,
+              threshold: 8192,
+              minRatio: 0.8,
+            })
+          );
+
+          // Brotli compression (balanced level for speed/size)
+          config.plugins.push(
+            new CompressionPlugin({
+              filename: '[path][base].br',
+              algorithm: 'brotliCompress',
+              test: /\.(js|css|html|svg|json)$/,
+              threshold: 8192,
+              minRatio: 0.8,
+              compressionOptions: {
+                level: 8, // Balanced: good compression without excessive build time
+              },
+            })
+          );
+        } catch (error) {
+          // compression-webpack-plugin not installed, skip compression
+          console.warn('compression-webpack-plugin not found, skipping compression');
+        }
+      }
+
+      // Call user's webpack function if provided
+      if (options.webpack) {
+        return options.webpack(config, webpackOptions);
+      }
+
+      return config;
+    },
+
+  };
+
+  // Deep merge user options with base config
+  const finalConfig = deepMerge(baseConfig, options);
+
+  // 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
+
+  // Return clean NextConfig object (user should wrap with withBundleAnalyzer in their next.config.ts)
+  return finalConfig;
+}
+

package/src/config/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Next.js Configuration Utilities
+ */
+
+export { createBaseNextConfig, type BaseNextConfigOptions } from './base-next-config';
+

package/src/contact/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Contact Form Utilities
+ * 
+ * Server-side utilities for contact form submission
+ */
+
+export { submitContactForm } from './submit';
+export type { SubmitContactFormOptions, SubmitContactFormResult } from './submit';
+
+// Route handler
+export { POST, createContactRoute } from './route';
+export type { ContactRouteOptions } from './route';
+

package/src/contact/route.ts

@@ -0,0 +1,102 @@
+/**
+ * Contact Form API Route Handler
+ * 
+ * Ready-to-use Next.js API route handler for contact form submissions.
+ * Proxies requests to backend API to avoid CORS issues.
+ * 
+ * @example
+ * ```ts
+ * // In app/api/contact/route.ts
+ * export { POST } from '@djangocfg/nextjs/contact/route';
+ * ```
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { submitContactForm } from './submit';
+import type { Schemas } from '@djangocfg/api';
+
+export interface ContactRouteOptions {
+  /** Backend API base URL (defaults to process.env.NEXT_PUBLIC_API_URL) */
+  apiUrl?: string;
+}
+
+/**
+ * Create contact form route handler with custom options
+ */
+export function createContactRoute(options?: ContactRouteOptions) {
+  return async function POST(request: NextRequest) {
+    try {
+      // Parse request body
+      const body: any = await request.json();
+
+      // Extract apiUrl from request body (passed from ContactFormProvider)
+      // or use from options/environment as fallback
+      const apiUrl = (body._apiUrl && body._apiUrl !== '') 
+        ? body._apiUrl 
+        : (options?.apiUrl || process.env.NEXT_PUBLIC_API_URL || '');
+      
+      if (!apiUrl) {
+        return NextResponse.json(
+          {
+            success: false,
+            message: 'API URL not configured. Set NEXT_PUBLIC_API_URL, provide apiUrl option, or pass _apiUrl in request body.',
+          },
+          { status: 500 }
+        );
+      }
+
+      // Remove _apiUrl from body before submitting
+      const { _apiUrl, ...submissionData } = body;
+
+      // Submit using smart wrapper from @djangocfg/nextjs
+      const response = await submitContactForm({
+        data: submissionData as Schemas.LeadSubmissionRequest,
+        apiUrl,
+        siteUrl: request.headers.get('origin') || undefined,
+      });
+
+      return NextResponse.json(response);
+    } catch (error) {
+      console.error('Contact form submission error:', error);
+
+      // Handle validation errors (400)
+      if (error instanceof Error && error.message.includes('Missing required fields')) {
+        return NextResponse.json(
+          {
+            success: false,
+            message: error.message,
+          },
+          { status: 400 }
+        );
+      }
+
+      // Handle API errors
+      if (error instanceof Error) {
+        return NextResponse.json(
+          {
+            success: false,
+            message: error.message || 'Failed to submit contact form',
+          },
+          { status: 500 }
+        );
+      }
+
+      return NextResponse.json(
+        {
+          success: false,
+          message: 'An unexpected error occurred',
+        },
+        { status: 500 }
+      );
+    }
+  };
+}
+
+/**
+ * Default POST handler (uses process.env.NEXT_PUBLIC_API_URL)
+ */
+export async function POST(request: NextRequest) {
+  const handler = createContactRoute();
+  return handler(request);
+}
+

package/src/contact/submit.ts

@@ -0,0 +1,80 @@
+/**
+ * Contact Form Submission - Server-side function
+ * 
+ * Server-side function to submit contact form data to backend API.
+ * Can be used in Next.js API routes to avoid CORS issues.
+ * 
+ * @example
+ * ```ts
+ * import { submitContactForm } from '@djangocfg/nextjs/contact';
+ * 
+ * const result = await submitContactForm({
+ *   name: 'John Doe',
+ *   email: 'john@example.com',
+ *   message: 'Hello!',
+ *   apiUrl: 'https://api.example.com'
+ * });
+ * ```
+ */
+
+import { API, MemoryStorageAdapter, Fetchers } from '@djangocfg/api';
+import type { Schemas } from '@djangocfg/api';
+
+export interface SubmitContactFormOptions {
+  /** Lead submission data */
+  data: Schemas.LeadSubmissionRequest;
+  /** Backend API base URL */
+  apiUrl: string;
+  /** Optional site URL (auto-detected from origin if not provided) */
+  siteUrl?: string;
+}
+
+export interface SubmitContactFormResult {
+  success: boolean;
+  message: string;
+  lead_id?: number;
+}
+
+/**
+ * Submit contact form data to backend API
+ * 
+ * Server-side function that uses the typed fetcher for type safety
+ * and runtime validation via Zod schemas.
+ */
+export async function submitContactForm({
+  data,
+  apiUrl,
+  siteUrl,
+}: SubmitContactFormOptions): Promise<SubmitContactFormResult> {
+  // Validate required fields
+  if (!data.name || !data.email || !data.message) {
+    throw new Error('Missing required fields: name, email, message');
+  }
+
+  if (!apiUrl) {
+    throw new Error('API URL is required');
+  }
+
+  // Create server-side API instance with MemoryStorageAdapter
+  // This works on the server because MemoryStorageAdapter is not client-only
+  const serverApi = new API(apiUrl, {
+    storage: new MemoryStorageAdapter(),
+  });
+
+  // Prepare submission data with site_url
+  const submissionData: Schemas.LeadSubmissionRequest = {
+    ...data,
+    site_url: data.site_url || siteUrl,
+  };
+
+  // Use typed fetcher with server API instance
+  // This provides type safety and runtime validation via Zod
+  const result = await Fetchers.createLeadsSubmitCreate(submissionData, serverApi);
+
+  return {
+    success: result.success,
+    message: result.message,
+    lead_id: result.lead_id,
+  };
+}
+

package/src/errors/ErrorLayout.tsx

@@ -0,0 +1,228 @@
+/**
+ * ErrorLayout - Universal Error Display
+ *
+ * Minimalist error page with customizable content
+ * Works with Next.js error pages (404.tsx, 500.tsx, error.tsx)
+ *
+ * Usage:
+ * ```tsx
+ * // app/not-found.tsx
+ * import { ErrorLayout } from '@djangocfg/nextjs/errors';
+ *
+ * export default function NotFound() {
+ *   return <ErrorLayout code={404} supportEmail={settings.contact.email} />;
+ * }
+ * ```
+ */
+
+'use client';
+
+import React from 'react';
+import { Button } from '@djangocfg/ui/components';
+import { getErrorContent } from './errorConfig';
+
+export interface ErrorLayoutProps {
+  /** Error code (e.g., "404", "500", "403") - if provided, auto-configures title/description/icon */
+  code?: string | number;
+  /** Error title (auto-generated from code if not provided) */
+  title?: string;
+  /** Error description (auto-generated from code if not provided) */
+  description?: string;
+  /** Custom action buttons */
+  actions?: React.ReactNode;
+  /** Show default actions (back, home) */
+  showDefaultActions?: boolean;
+  /** Custom illustration/icon (auto-generated from code if not provided) */
+  illustration?: React.ReactNode;
+  /** Support email for contact link */
+  supportEmail?: string;
+}
+
+// Local function to select the icon based on the code. 
+// This is safe as it's defined and used inside a Client Component.
+function getErrorIcon(code?: string | number): React.ReactNode {
+  const c = code ? String(code) : '';
+  
+  // NOTE: You can replace these SVG paths with imported Lucid Icons 
+  // (e.g., <AlertTriangle />) if you prefer.
+  switch (c) {
+    case '404':
+      return (
+        <svg
+          className="w-24 h-24 mx-auto text-muted-foreground/50"
+          fill="none"
+          stroke="currentColor"
+          viewBox="0 0 24 24"
+          aria-hidden="true"
+        >
+          {/* Missing Page Icon */}
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            strokeWidth={1.5}
+            d="M9.343 3.07a7.227 7.227 0 0111.558 0c.806.515 1.393 1.39 1.393 2.37v6.636c0 .98-.587 1.855-1.393 2.37a7.227 7.227 0 01-11.558 0c-.806-.515-1.393-1.39-1.393-2.37V5.44c0-.98.587-1.855 1.393-2.37zM12 13a1 1 0 100-2 1 1 0 000 2z"
+          />
+        </svg>
+      );
+    case '500':
+      return (
+        <svg
+          className="w-24 h-24 mx-auto text-muted-foreground/50"
+          fill="none"
+          stroke="currentColor"
+          viewBox="0 0 24 24"
+          aria-hidden="true"
+        >
+          {/* Server Error Icon */}
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            strokeWidth={1.5}
+            d="M18.364 18.364A9 9 0 005.636 5.636m12.728 0l-6.849 6.849m0 0l-6.849-6.849m6.849 6.849V21m0 0h7.5M12 21v-7.5M7.5 21H3m7.5 0h7.5M3 18V9a4.5 4.5 0 014.5-4.5h9A4.5 4.5 0 0121 9v9a4.5 4.5 0 01-4.5 4.5h-9A4.5 4.5 0 013 18z"
+          />
+        </svg>
+      );
+    case '403':
+      return (
+        <svg
+          className="w-24 h-24 mx-auto text-muted-foreground/50"
+          fill="none"
+          stroke="currentColor"
+          viewBox="0 0 24 24"
+          aria-hidden="true"
+        >
+          {/* Forbidden Icon */}
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            strokeWidth={1.5}
+            d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z"
+          />
+        </svg>
+      );
+    default:
+      return null;
+  }
+}
+
+/**
+ * ErrorLayout Component
+ */
+export function ErrorLayout({
+  code,
+  title,
+  description,
+  actions,
+  showDefaultActions = true,
+  illustration,
+  supportEmail = 'support@example.com',
+}: ErrorLayoutProps) {
+  
+  // Get content (Title/Description) from config. Note: Illustration check removed.
+  // The function getErrorContent MUST NOT return React components/functions.
+  const autoContent = code && (!title || !description)
+    ? getErrorContent(code)
+    : null;
+
+  // Fallback to auto-generated values
+  const finalTitle = title || autoContent?.title || 'Error';
+  const finalDescription = description || autoContent?.description;
+  
+  // ILLUSTRATION FIX: Use passed prop OR compute the icon locally using getErrorIcon.
+  const finalIllustration = illustration ?? getErrorIcon(code);
+
+
+  const handleGoBack = () => {
+    if (document.referrer && document.referrer !== window.location.href) {
+      window.location.href = document.referrer;
+    } else if (window.history.length > 1) {
+      window.history.back();
+    } else {
+      window.location.href = '/';
+    }
+  };
+
+  const handleGoHome = () => {
+    window.location.href = '/';
+  };
+
+  return (
+    <div className="min-h-screen flex items-center justify-center px-4 bg-background">
+      <div className="max-w-2xl w-full text-center space-y-8">
+        {/* Error Code */}
+        {code && (
+          <div className="relative">
+            <h1
+              className="text-[12rem] font-bold leading-none text-muted/20 select-none"
+              aria-hidden="true"
+            >
+              {code}
+            </h1>
+          </div>
+        )}
+
+        {/* Illustration */}
+        {finalIllustration && (
+          <div className="flex justify-center py-8">
+            {finalIllustration}
+          </div>
+        )}
+
+        {/* Error Content */}
+        <div className="space-y-4">
+          <h2 className="text-4xl font-bold text-foreground">
+            {finalTitle}
+          </h2>
+
+          {finalDescription && (
+            <p className="text-lg text-muted-foreground max-w-md mx-auto">
+              {finalDescription}
+            </p>
+          )}
+        </div>
+
+        {/* Actions */}
+        <div className="flex flex-col sm:flex-row items-center justify-center gap-4 pt-4">
+          {/* Custom actions */}
+          {actions}
+
+          {/* Default actions */}
+          {showDefaultActions && !actions && (
+            <>
+              <Button
+                variant="outline"
+                size="lg"
+                onClick={handleGoBack}
+                style={{ minWidth: '140px', padding: '12px 32px' }}
+              >
+                Go Back
+              </Button>
+              <Button
+                variant="default"
+                size="lg"
+                onClick={handleGoHome}
+                style={{ minWidth: '140px', padding: '12px 32px' }}
+              >
+                Go Home
+              </Button>
+            </>
+          )}
+        </div>
+
+        {/* Additional Info */}
+        <div className="pt-8 text-sm text-muted-foreground">
+          <p>
+            Need help? Contact{' '}
+            <a
+              href={`mailto:${supportEmail}`}
+              className="text-primary hover:underline"
+            >
+              support
+            </a>
+          </p>
+        </div>
+      </div>
+    </div>
+  );
+}
+