@djangocfg/nextjs 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Reforms.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,449 @@
+# @djangocfg/nextjs
+
+> Comprehensive Next.js utilities and components: sitemap generation, health checks, OG images, legal pages, error pages, and more
+
+[![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)
+
+**Part of [DjangoCFG](https://djangocfg.com)** — a modern Django framework for building production-ready SaaS applications. All `@djangocfg/*` packages are designed to work together, providing type-safe configuration, real-time features, and beautiful admin interfaces out of the box.
+
+---
+
+## 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.
+
+## Features
+
+- **Base Next.js Config** - Universal, reusable Next.js configuration factory for monorepos
+- **Sitemap Generation** - Dynamic XML sitemap generation for SEO
+- **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
+- **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
+
+## Installation
+
+```bash
+npm install @djangocfg/nextjs
+# or
+pnpm add @djangocfg/nextjs
+# or
+yarn add @djangocfg/nextjs
+```
+
+## Quick Start
+
+### Base Next.js Configuration
+
+Create a reusable base configuration for all your Next.js projects:
+
+```tsx
+// 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({
+  // Base path for static builds
+  basePath: process.env.NEXT_PUBLIC_STATIC_BUILD === 'true' ? '/cfg/admin' : undefined,
+  
+  // Add custom transpile packages
+  transpilePackages: ['my-custom-package'],
+  
+  // Custom webpack configuration (called after base webpack logic)
+  webpack: (config, options) => {
+    // Your custom webpack rules
+    return config;
+  },
+}));
+```
+
+### Sitemap Generation
+
+Generate dynamic XML sitemaps for SEO:
+
+```tsx
+// app/sitemap.ts
+import { createSitemapHandler } from '@djangocfg/nextjs/sitemap';
+
+export default createSitemapHandler({
+  siteUrl: 'https://example.com',
+  staticPages: [
+    { loc: '/', changefreq: 'daily', priority: 1.0 },
+    { loc: '/about', changefreq: 'monthly', priority: 0.8 },
+  ],
+  dynamicPages: async () => {
+    const posts = await fetchPosts();
+    return posts.map(post => ({
+      loc: `/posts/${post.slug}`,
+      lastmod: post.updatedAt,
+      changefreq: 'weekly',
+      priority: 0.7,
+    }));
+  },
+});
+```
+
+### Health Check Endpoint
+
+Create a health monitoring endpoint:
+
+```tsx
+// app/api/health/route.ts
+import { createHealthHandler } from '@djangocfg/nextjs/health';
+
+export const GET = createHealthHandler({
+  version: process.env.NEXT_PUBLIC_APP_VERSION || '1.0.0',
+  checks: [
+    {
+      name: 'database',
+      check: async () => {
+        // Check database connection
+        return await checkDatabase();
+      },
+    },
+  ],
+});
+```
+
+### OG Image Generation
+
+Generate dynamic Open Graph images with custom templates:
+
+```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 },
+});
+
+export async function GET(request: NextRequest) {
+  return handler.GET(request);
+}
+```
+
+Automatically add OG images to page metadata:
+
+```tsx
+// app/page.tsx
+import { generateMetadata } from '@core/metadata';
+
+export const metadata = generateMetadata({
+  title: 'My Page',
+  description: 'Page description',
+});
+```
+
+### Legal Pages
+
+Use pre-built legal pages:
+
+```tsx
+// app/legal/privacy/page.tsx
+import { PrivacyPage } from '@djangocfg/nextjs/legal';
+
+export default PrivacyPage;
+```
+
+Available pages:
+- `PrivacyPage` - Privacy policy
+- `TermsPage` - Terms of service
+- `CookiesPage` - Cookie policy
+- `SecurityPage` - Security policy
+
+### Error Pages
+
+Use reusable error layouts:
+
+```tsx
+// app/not-found.tsx
+import { ErrorLayout } from '@djangocfg/nextjs/errors';
+
+export default function NotFound() {
+  return <ErrorLayout code={404} supportEmail="support@example.com" />;
+}
+```
+
+```tsx
+// app/error.tsx
+'use client';
+
+import { useEffect } from 'react';
+import { ErrorLayout } from '@djangocfg/nextjs/errors';
+
+export default function Error({ error, reset }: { error: Error; reset: () => void }) {
+  useEffect(() => {
+    console.error('Error:', error);
+  }, [error]);
+
+  return <ErrorLayout code={500} supportEmail="support@example.com" />;
+}
+```
+
+### HomePage Component
+
+Smart authentication redirect component:
+
+```tsx
+// app/page.tsx
+import { HomePage } from '@djangocfg/nextjs/components';
+
+export default function Page() {
+  return (
+    <HomePage
+      authenticatedPath="/dashboard"
+      unauthenticatedPath="/auth"
+      loadingText="Loading..."
+    />
+  );
+}
+```
+
+## Exports
+
+| Path | Description |
+|------|-------------|
+| `@djangocfg/nextjs` | Main exports (all modules) |
+| `@djangocfg/nextjs/config` | Base Next.js configuration factory |
+| `@djangocfg/nextjs/sitemap` | Sitemap generation utilities |
+| `@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/navigation` | Route definitions, menu generation, navigation helpers |
+| `@djangocfg/nextjs/legal` | Legal page components |
+| `@djangocfg/nextjs/errors` | Error page layouts |
+| `@djangocfg/nextjs/components` | Reusable components |
+
+## API Reference
+
+### Base Configuration
+
+#### `createBaseNextConfig(options)`
+
+Creates a reusable base Next.js configuration with standard DjangoCFG settings.
+
+```tsx
+createBaseNextConfig({
+  basePath?: string;                    // Base path for static builds
+  transpilePackages?: string[];          // Additional packages to transpile
+  optimizePackageImports?: string[];     // Additional packages to optimize
+  webpack?: (config, options) => config; // Custom webpack configuration
+  experimental?: NextConfig['experimental']; // Custom experimental options
+  env?: Record<string, string>;         // Custom environment variables
+  // ... any other NextConfig options
+})
+```
+
+**Features:**
+- Automatic dev/production optimizations
+- Filesystem caching for faster rebuilds
+- Compression plugins for static builds (Gzip + Brotli)
+- Standard transpile packages for monorepo
+- Type-safe configuration merging
+
+### Sitemap
+
+#### `createSitemapHandler(options)`
+
+Creates a Next.js route handler for sitemap generation.
+
+```tsx
+createSitemapHandler({
+  siteUrl: string;
+  staticPages?: SitemapUrl[];
+  dynamicPages?: SitemapUrl[] | (() => Promise<SitemapUrl[]>);
+  cacheControl?: string;
+})
+```
+
+### Health
+
+#### `createHealthHandler(config)`
+
+Creates a health check route handler.
+
+```tsx
+createHealthHandler({
+  version?: string;
+  checks?: Array<{ name: string; check: () => Promise<boolean> }>;
+  customData?: Record<string, any>;
+})
+```
+
+### OG Image
+
+#### `createOgImageHandler(config)`
+
+Creates an OG image generation handler with custom template component.
+
+```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
+})
+```
+
+#### `generateOgImageMetadata(metadata, params?, options?)`
+
+Automatically adds OG image to Next.js metadata.
+
+```tsx
+generateOgImageMetadata(
+  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
+  }
+)
+```
+
+#### `generateOgImageUrl(baseUrl, params, useBase64?)`
+
+Generates OG image URL with base64-encoded parameters.
+
+```tsx
+generateOgImageUrl('/api/og', {
+  title: 'My Page',
+  description: 'Page description',
+  siteName: 'My Site',
+  logo: '/logo.svg',
+}, true) // useBase64 = true (default)
+```
+
+### Navigation
+
+#### `defineRoute(path, metadata, config?)`
+
+Defines a route with metadata.
+
+```tsx
+defineRoute('/dashboard', {
+  title: 'Dashboard',
+  description: 'Dashboard overview',
+}, {
+  basePath: '/admin',
+  isStaticBuild: false,
+})
+```
+
+#### `isActive(current, target, allRoutes?)`
+
+Checks if a route is currently active.
+
+```tsx
+isActive('/admin/dashboard', '/admin/dashboard') // true
+isActive('/admin/dashboard/settings', '/admin/dashboard') // true
+isActive('/admin/dashboard', '/admin/settings') // false
+```
+
+#### `routesToMenuItems(routes)`
+
+Converts route definitions to menu items.
+
+```tsx
+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
+
+- Next.js >= 13.0.0 (App Router)
+- React >= 18.0.0
+- TypeScript >= 5.0.0
+
+## Peer Dependencies
+
+- `@djangocfg/layouts` - For auth context in HomePage
+- `@djangocfg/ui` - For UI components in legal/error pages
+- `lucide-react` - For icons
+
+## Documentation
+
+Full documentation available at [djangocfg.com](https://djangocfg.com)
+
+## Contributing
+
+Issues and pull requests are welcome at [GitHub](https://github.com/markolofsen/django-cfg)
+
+## License
+
+MIT - see [LICENSE](./LICENSE) for details
+

package/package.json

@@ -0,0 +1,133 @@
+{
+  "name": "@djangocfg/nextjs",
+  "version": "1.0.1",
+  "description": "Next.js utilities and components: sitemap, health, OG images, legal pages, error pages",
+  "keywords": [
+    "nextjs",
+    "sitemap",
+    "health",
+    "og-image",
+    "legal-pages",
+    "error-pages",
+    "react",
+    "typescript"
+  ],
+  "author": {
+    "name": "DjangoCFG",
+    "url": "https://djangocfg.com"
+  },
+  "homepage": "https://djangocfg.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/markolofsen/django-cfg.git",
+    "directory": "packages/nextjs"
+  },
+  "bugs": {
+    "url": "https://github.com/markolofsen/django-cfg/issues"
+  },
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./sitemap": {
+      "types": "./src/sitemap/index.ts",
+      "import": "./src/sitemap/index.ts",
+      "default": "./src/sitemap/index.ts"
+    },
+    "./health": {
+      "types": "./src/health/index.ts",
+      "import": "./src/health/index.ts",
+      "default": "./src/health/index.ts"
+    },
+    "./og-image": {
+      "types": "./src/og-image/index.ts",
+      "import": "./src/og-image/index.ts",
+      "default": "./src/og-image/index.ts"
+    },
+    "./og-image/utils": {
+      "types": "./src/og-image/utils/index.ts",
+      "import": "./src/og-image/utils/index.ts",
+      "default": "./src/og-image/utils/index.ts"
+    },
+    "./og-image/components": {
+      "types": "./src/og-image/components/index.ts",
+      "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",
+      "default": "./src/contact/index.ts"
+    },
+    "./navigation": {
+      "types": "./src/navigation/index.ts",
+      "import": "./src/navigation/index.ts",
+      "default": "./src/navigation/index.ts"
+    },
+    "./config": {
+      "types": "./src/config/index.ts",
+      "import": "./src/config/index.ts",
+      "default": "./src/config/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rm -rf dist",
+    "lint": "eslint .",
+    "check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@vercel/og": "^0.8.5"
+  },
+  "peerDependencies": {
+    "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",
+    "lucide-react": "^0.469.0"
+  },
+  "devDependencies": {
+    "@djangocfg/typescript-config": "^1.4.31",
+    "@djangocfg/layouts": "^2.0.1",
+    "@types/node": "^24.7.2",
+    "@types/react": "19.2.2",
+    "@types/react-dom": "19.2.1",
+    "@types/webpack": "^5.28.5",
+    "eslint": "^9.37.0",
+    "lucide-react": "^0.469.0",
+    "tsup": "^8.0.1",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
+

package/src/components/HomePage.tsx

@@ -0,0 +1,73 @@
+'use client';
+
+import { useEffect } from 'react';
+import { useRouter } from 'next/navigation';
+import { useAuth } from '@djangocfg/layouts';
+import { Loader2 } from 'lucide-react';
+
+export interface HomePageProps {
+  /**
+   * Path to redirect to when user is authenticated
+   * @default '/private'
+   */
+  authenticatedPath?: string;
+  /**
+   * Path to redirect to when user is not authenticated
+   * @default '/auth'
+   */
+  unauthenticatedPath?: string;
+  /**
+   * Custom loading text
+   * @default 'Loading...'
+   */
+  loadingText?: string;
+}
+
+/**
+ * HomePage - Root page component that handles authentication redirect
+ *
+ * Redirects authenticated users to authenticatedPath, otherwise to unauthenticatedPath
+ *
+ * Usage:
+ * ```tsx
+ * // app/page.tsx
+ * import { HomePage } from '@djangocfg/nextjs/components';
+ *
+ * export default function Page() {
+ *   return (
+ *     <HomePage
+ *       authenticatedPath="/private"
+ *       unauthenticatedPath="/auth"
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function HomePage({
+  authenticatedPath = '/private',
+  unauthenticatedPath = '/auth',
+  loadingText = 'Loading...',
+}: HomePageProps) {
+  const { isAuthenticated } = useAuth();
+  const router = useRouter();
+
+  useEffect(() => {
+    if (!isAuthenticated) {
+      router.push(unauthenticatedPath);
+    } else {
+      router.push(authenticatedPath);
+    }
+  }, [isAuthenticated, router, authenticatedPath, unauthenticatedPath]);
+
+  return (
+    <div className="flex items-center justify-center min-h-screen bg-background">
+      <div className="flex flex-col items-center gap-4">
+        <Loader2 className="animate-spin text-primary" style={{ width: '48px', height: '48px' }} />
+        <span className="text-lg font-medium text-muted-foreground">
+          {loadingText}
+        </span>
+      </div>
+    </div>
+  );
+}
+

package/src/components/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Components exports
+ */
+
+export { HomePage } from './HomePage';
+export type { HomePageProps } from './HomePage';
+