@djangocfg/nextjs 1.0.4 → 1.0.6

package/README.md

@@ -1,6 +1,6 @@
 # @djangocfg/nextjs
 
-> Comprehensive Next.js utilities and components: sitemap generation, health checks, OG images, legal pages, error pages, and more
+> Server-side Next.js utilities: sitemap generation, health checks, OG images, contact forms, 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,7 +11,9 @@
 
 ## Overview
 
-`@djangocfg/nextjs` provides a comprehensive set of utilities and components for Next.js applications. From SEO optimization with sitemaps to health monitoring, from dynamic OG images to ready-to-use legal pages, this package covers common Next.js needs out of the box.
+`@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, contact form handling, navigation utilities, and configuration management.
+
+> **Note:** Client components (legal pages, error pages, redirect components) have been moved to `@djangocfg/layouts` to keep this package server-only.
 
 ## Features
 
@@ -19,12 +21,10 @@
 - **Sitemap Generation** - Dynamic XML sitemap generation for SEO
 - **Health Checks** - Production-ready health monitoring endpoints
 - **OG Images** - Dynamic Open Graph image generation with templates
+- **Contact Forms** - Server-side contact form submission handlers
 - **Navigation Utilities** - Route definitions, menu generation, and navigation helpers
-- **Legal Pages** - Pre-built privacy, terms, cookies, and security pages
-- **Error Pages** - Reusable 404 and 500 error layouts
-- **HomePage Component** - Smart authentication redirect component
 - **TypeScript** - Full type safety throughout
-- **Self-Contained** - No external dependencies beyond Next.js
+- **Server-Only** - No client-side code, pure server utilities
 
 ## Installation
 
@@ -147,77 +147,55 @@ Automatically add OG images to page metadata:
 
 ```tsx
 // app/page.tsx
-import { generateMetadata } from '@core/metadata';
+import { generateOgImageMetadata } from '@djangocfg/nextjs/og-image/utils';
 
-export const metadata = generateMetadata({
+export const metadata = generateOgImageMetadata({
   title: 'My Page',
   description: 'Page description',
 });
 ```
 
-### Legal Pages
+### Contact Form
 
-Use pre-built legal pages:
+Create a contact form API route:
 
 ```tsx
-// app/legal/privacy/page.tsx
-import { PrivacyPage } from '@djangocfg/nextjs/legal';
+// app/api/contact/route.ts
+import { createContactRoute } from '@djangocfg/nextjs/contact';
 
-export default PrivacyPage;
+export const POST = createContactRoute();
 ```
 
-Available pages:
-- `PrivacyPage` - Privacy policy
-- `TermsPage` - Terms of service
-- `CookiesPage` - Cookie policy
-- `SecurityPage` - Security policy
-
-### Error Pages
-
-Use reusable error layouts:
+The route handler accepts form data and submits it to your API endpoint. The `apiUrl` can be passed in the request body or configured via environment variables.
 
-```tsx
-// app/not-found.tsx
-import { ErrorLayout } from '@djangocfg/nextjs/errors';
+### Navigation Utilities
 
-export default function NotFound() {
-  return <ErrorLayout code={404} supportEmail="support@example.com" />;
-}
-```
+Define routes and generate navigation menus:
 
 ```tsx
-// app/error.tsx
-'use client';
+import { defineRoute, routesToMenuItems } from '@djangocfg/nextjs/navigation';
 
-import { useEffect } from 'react';
-import { ErrorLayout } from '@djangocfg/nextjs/errors';
+const routes = [
+  defineRoute('/dashboard', { title: 'Dashboard' }),
+  defineRoute('/settings', { title: 'Settings' }),
+];
 
-export default function Error({ error, reset }: { error: Error; reset: () => void }) {
-  useEffect(() => {
-    console.error('Error:', error);
-  }, [error]);
-
-  return <ErrorLayout code={500} supportEmail="support@example.com" />;
-}
+const menuItems = routesToMenuItems(routes);
 ```
 
-### HomePage Component
+### Client Components
 
-Smart authentication redirect component:
+Client-side components (legal pages, error pages, redirect components) are available in `@djangocfg/layouts`:
 
 ```tsx
-// app/page.tsx
-import { HomePage } from '@djangocfg/nextjs/components';
-
-export default function Page() {
-  return (
-    <HomePage
-      authenticatedPath="/dashboard"
-      unauthenticatedPath="/auth"
-      loadingText="Loading..."
-    />
-  );
-}
+// Legal pages
+import { PrivacyPage, TermsPage } from '@djangocfg/layouts/pages/legal';
+
+// Error pages
+import { ErrorLayout } from '@djangocfg/layouts/components/errors';
+
+// Redirect component
+import { RedirectPage } from '@djangocfg/layouts/components/RedirectPage';
 ```
 
 ## Exports
@@ -230,10 +208,10 @@ export default function Page() {
 | `@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/contact` | Contact form route handlers |
 | `@djangocfg/nextjs/navigation` | Route definitions, menu generation, navigation helpers |
-| `@djangocfg/nextjs/legal` | Legal page components |
-| `@djangocfg/nextjs/errors` | Error page layouts |
-| `@djangocfg/nextjs/components` | Reusable components |
+| `@djangocfg/nextjs/scripts` | Utility scripts (e.g., link checking) |
 
 ## API Reference
 
@@ -326,17 +304,35 @@ generateOgImageMetadata(
 
 #### `generateOgImageUrl(baseUrl, params, useBase64?)`
 
-Generates OG image URL with base64-encoded parameters.
+> **Note:** This utility has been moved to `@djangocfg/layouts/utils/og-image` for client-side usage.
+
+For server-side usage, you can still use it from `@djangocfg/nextjs/og-image/utils`, but for client components, import from layouts:
 
 ```tsx
-generateOgImageUrl('/api/og', {
+// Client component
+import { generateOgImageUrl } from '@djangocfg/layouts/utils/og-image';
+
+const url = generateOgImageUrl('/api/og', {
   title: 'My Page',
   description: 'Page description',
   siteName: 'My Site',
-  logo: '/logo.svg',
-}, true) // useBase64 = true (default)
+});
+```
+
+### Contact Form
+
+#### `createContactRoute(options?)`
+
+Creates a Next.js API route handler for contact form submissions.
+
+```tsx
+createContactRoute({
+  // Options are handled via request body or environment variables
+})
 ```
 
+The route accepts POST requests with form data and submits to the API endpoint specified in the request body (`_apiUrl` field) or environment variables.
+
 ### Navigation
 
 #### `defineRoute(path, metadata, config?)`
@@ -371,57 +367,6 @@ Converts route definitions to menu items.
 const menuItems = routesToMenuItems(allRoutes);
 ```
 
-### Legal Pages
-
-#### `PrivacyPage`, `TermsPage`, `CookiesPage`, `SecurityPage`
-
-Pre-built legal page components with default content. Can be customized:
-
-```tsx
-import { PrivacyPage, privacyConfig } from '@djangocfg/nextjs/legal';
-
-// Use default
-export default PrivacyPage;
-
-// Or customize
-export default function CustomPrivacy() {
-  return <PrivacyPage config={{
-    ...privacyConfig,
-    lastUpdated: '2024-01-01',
-  }} />;
-}
-```
-
-### Error Pages
-
-#### `ErrorLayout`
-
-Reusable error page layout component.
-
-```tsx
-<ErrorLayout
-  code={404 | 500 | string | number}
-  title?: string
-  description?: string
-  supportEmail?: string
-  actions?: React.ReactNode
-  showDefaultActions?: boolean
-/>
-```
-
-### Components
-
-#### `HomePage`
-
-Authentication redirect component.
-
-```tsx
-<HomePage
-  authenticatedPath?: string      // Default: '/private'
-  unauthenticatedPath?: string    // Default: '/auth'
-  loadingText?: string             // Default: 'Loading...'
-/>
-```
 
 ## Requirements
 
@@ -431,9 +376,8 @@ Authentication redirect component.
 
 ## Peer Dependencies
 
-- `@djangocfg/layouts` - For auth context in HomePage
-- `@djangocfg/ui` - For UI components in legal/error pages
-- `lucide-react` - For icons
+- `@djangocfg/api` - For API client functionality
+- `next` - Next.js framework (^15.4.4)
 
 ## Documentation
 

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@djangocfg/nextjs",
-  "version": "1.0.4",
-  "description": "Next.js utilities and components: sitemap, health, OG images, legal pages, error pages",
+  "version": "1.0.6",
+  "description": "Next.js server utilities: sitemap, health, OG images, contact forms, navigation, config",
   "keywords": [
     "nextjs",
     "sitemap",
     "health",
     "og-image",
-    "legal-pages",
-    "error-pages",
+    "contact",
+    "navigation",
+    "config",
     "react",
     "typescript"
   ],
@@ -59,21 +60,6 @@
       "import": "./src/og-image/components/index.ts",
       "default": "./src/og-image/components/index.ts"
     },
-    "./legal": {
-      "types": "./src/legal/index.ts",
-      "import": "./src/legal/index.ts",
-      "default": "./src/legal/index.ts"
-    },
-    "./errors": {
-      "types": "./src/errors/index.ts",
-      "import": "./src/errors/index.ts",
-      "default": "./src/errors/index.ts"
-    },
-    "./components": {
-      "types": "./src/components/index.ts",
-      "import": "./src/components/index.ts",
-      "default": "./src/components/index.ts"
-    },
     "./contact": {
       "types": "./src/contact/index.ts",
       "import": "./src/contact/index.ts",
@@ -88,6 +74,11 @@
       "types": "./src/config/index.ts",
       "import": "./src/config/index.ts",
       "default": "./src/config/index.ts"
+    },
+    "./scripts": {
+      "types": "./src/scripts/index.ts",
+      "import": "./src/scripts/index.ts",
+      "default": "./src/scripts/index.ts"
     }
   },
   "files": [
@@ -100,34 +91,35 @@
     "dev": "tsup --watch",
     "clean": "rm -rf dist",
     "lint": "eslint .",
-    "check": "tsc --noEmit"
-  },
-  "dependencies": {
-    "@vercel/og": "^0.8.5"
+    "check": "tsc --noEmit",
+    "check-links": "tsx src/scripts/check-links.ts"
   },
   "peerDependencies": {
-    "next": "^15.4.4",
-    "react": "^19.1.0",
-    "react-dom": "^19.1.0",
-    "@djangocfg/ui": "^1.4.34",
-    "@djangocfg/layouts": "^2.0.4",
-    "@djangocfg/api": "^1.4.34",
-    "lucide-react": "^0.469.0"
+    "@djangocfg/api": "^1.4.36",
+    "next": "^15.4.4"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^1.4.34",
-    "@djangocfg/layouts": "^2.0.4",
+    "@djangocfg/imgai": "^1.0.22",
+    "@djangocfg/layouts": "^2.0.6",
+    "@djangocfg/typescript-config": "^1.4.36",
     "@types/node": "^24.7.2",
     "@types/react": "19.2.2",
     "@types/react-dom": "19.2.1",
     "@types/webpack": "^5.28.5",
+    "@vercel/og": "^0.8.5",
     "eslint": "^9.37.0",
+    "linkinator": "^7.5.0",
     "lucide-react": "^0.469.0",
+    "picocolors": "^1.1.1",
+    "prompts": "^2.4.2",
     "tsup": "^8.0.1",
+    "tsx": "^4.19.2",
     "typescript": "^5.9.3"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0"
   }
-}
-
+}

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

@@ -23,6 +23,7 @@
 
 import type { NextConfig } from 'next';
 import type { Configuration as WebpackConfig } from 'webpack';
+import chalk from 'chalk';
 import { deepMerge } from './deepMerge';
 
 // ─────────────────────────────────────────────────────────────────────────
@@ -32,6 +33,25 @@ import { deepMerge } from './deepMerge';
 const isStaticBuild = process.env.NEXT_PUBLIC_STATIC_BUILD === 'true';
 const isDev = process.env.NODE_ENV === 'development';
 
+// Global flag to track if browser was already opened (persists across hot reloads)
+let browserOpened = false;
+let bannerPrinted = false;
+
+// ASCII Art Banner for Django CFG
+const DJANGO_CFG_BANNER = `
+     888  d8b                                               .d888         
+     888  Y8P                                              d88P"          
+     888                                                   888            
+ .d88888 8888  8888b.  88888b.   .d88b.   .d88b.   .d8888b 888888 .d88b.  
+d88" 888 "888     "88b 888 "88b d88P"88b d88""88b d88P"    888   d88P"88b 
+888  888  888 .d888888 888  888 888  888 888  888 888      888   888  888 
+Y88b 888  888 888  888 888  888 Y88b 888 Y88..88P Y88b.    888   Y88b 888 
+ "Y88888  888 "Y888888 888  888  "Y88888  "Y88P"   "Y8888P 888    "Y88888 
+          888                        888                              888 
+         d88P                   Y8b d88P                         Y8b d88P 
+       888P"                     "Y88P"                           "Y88P"  
+`;
+
 // ─────────────────────────────────────────────────────────────────────────
 // Configuration Options
 // ─────────────────────────────────────────────────────────────────────────
@@ -43,6 +63,8 @@ export interface BaseNextConfigOptions {
   transpilePackages?: string[];
   /** Additional optimize package imports (merged with defaults) */
   optimizePackageImports?: string[];
+  /** Automatically open browser in dev mode (default: false) */
+  openBrowser?: boolean;
   /** Custom webpack configuration function (called after base webpack logic) */
   webpack?: (
     config: WebpackConfig,
@@ -153,6 +175,50 @@ export function createBaseNextConfig(
     webpack: (config: WebpackConfig, webpackOptions: { isServer: boolean; dev: boolean;[key: string]: any }) => {
       const { isServer, dev } = webpackOptions;
 
+      // Print banner and auto-open browser in dev mode (client-side only)
+      if (dev && !isServer) {
+        // Create a simple plugin to print banner and open browser after first compilation
+        const DevStartupPlugin = class {
+          apply(compiler: any) {
+            compiler.hooks.done.tap('DevStartupPlugin', () => {
+              // Print banner only once
+              if (!bannerPrinted) {
+                bannerPrinted = true;
+                console.log('\n' + chalk.yellowBright.bold(DJANGO_CFG_BANNER) + '\n');
+              }
+
+              // Auto-open browser if enabled
+              if (options.openBrowser && !browserOpened) {
+                browserOpened = true;
+                // Delay to ensure server is ready
+                setTimeout(() => {
+                  const { exec } = require('child_process');
+                  const port = process.env.PORT || '3000';
+                  const url = `http://localhost:${port}`;
+                  
+                  const command = process.platform === 'darwin'
+                    ? 'open'
+                    : process.platform === 'win32'
+                    ? 'start'
+                    : 'xdg-open';
+                  
+                  exec(`${command} ${url}`, (error: Error | null) => {
+                    if (error) {
+                      console.warn(`Failed to open browser: ${error.message}`);
+                    }
+                  });
+                }, 2000); // Wait 2 seconds for server to be ready
+              }
+            });
+          }
+        };
+        
+        if (!config.plugins) {
+          config.plugins = [];
+        }
+        config.plugins.push(new DevStartupPlugin());
+      }
+
       // Dev mode optimizations
       if (dev) {
         config.optimization = {
@@ -226,6 +292,8 @@ 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).optimizePackageImports;
+  delete (finalConfig as any).isDefaultCfgAdmin;
+  delete (finalConfig as any).openBrowser;
   // Note: We don't delete transpilePackages, experimental, env, webpack
   // as they are valid NextConfig keys and may have been overridden by user
 

package/src/contact/submit.ts

@@ -4,6 +4,8 @@
  * Server-side function to submit contact form data to backend API.
  * Can be used in Next.js API routes to avoid CORS issues.
  * 
+ * Uses Fetchers with server-side API instance for type safety and Zod validation.
+ * 
  * @example
  * ```ts
  * import { submitContactForm } from '@djangocfg/nextjs/contact';
@@ -17,8 +19,9 @@
  * ```
  */
 
-import { API, MemoryStorageAdapter, Fetchers } from '@djangocfg/api';
-import type { Schemas } from '@djangocfg/api';
+// Use server-only exports to avoid loading React hooks (useSWRConfig)
+import { API, MemoryStorageAdapter, Fetchers } from '@djangocfg/api/server';
+import type { Schemas } from '@djangocfg/api/server';
 
 export interface SubmitContactFormOptions {
   /** Lead submission data */
@@ -38,8 +41,8 @@ export interface SubmitContactFormResult {
 /**
  * Submit contact form data to backend API
  * 
- * Server-side function that uses the typed fetcher for type safety
- * and runtime validation via Zod schemas.
+ * Server-side function that uses Fetchers with server-side API instance.
+ * This provides type safety, Zod validation, and proper error handling.
  */
 export async function submitContactForm({
   data,
@@ -56,7 +59,7 @@ export async function submitContactForm({
   }
 
   // Create server-side API instance with MemoryStorageAdapter
-  // This works on the server because MemoryStorageAdapter is not client-only
+  // This works on server-side and doesn't require browser APIs
   const serverApi = new API(apiUrl, {
     storage: new MemoryStorageAdapter(),
   });
@@ -67,14 +70,24 @@ export async function submitContactForm({
     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);
+  try {
+    // Use typed fetcher with server API instance
+    // This provides type safety and runtime validation via Zod
+    // Using Fetchers namespace to avoid loading hooks
+    const result = await Fetchers.createLeadsSubmitCreate(submissionData, serverApi);
 
-  return {
-    success: result.success,
-    message: result.message,
-    lead_id: result.lead_id,
-  };
+    // Return formatted result
+    return {
+      success: result.success ?? true,
+      message: result.message || 'Contact form submitted successfully',
+      lead_id: result.lead_id,
+    };
+  } catch (error) {
+    // Handle API errors (including validation errors from Zod)
+    if (error instanceof Error) {
+      throw new Error(`Failed to submit contact form: ${error.message}`);
+    }
+    throw new Error('An unexpected error occurred while submitting the contact form');
+  }
 }
 

package/src/index.ts

@@ -13,15 +13,6 @@ export * from './health';
 // OG Image
 export * from './og-image';
 
-// Legal pages
-export * from './legal';
-
-// Error pages
-export * from './errors';
-
-// Components
-export * from './components';
-
 // Contact form
 export * from './contact';