@djangocfg/nextjs 1.0.6 → 2.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/nextjs",
-  "version": "1.0.6",
+  "version": "2.1.1",
   "description": "Next.js server utilities: sitemap, health, OG images, contact forms, navigation, config",
   "keywords": [
     "nextjs",
@@ -95,21 +95,22 @@
     "check-links": "tsx src/scripts/check-links.ts"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^1.4.36",
-    "next": "^15.4.4"
+    "@djangocfg/api": "^2.1.1",
+    "next": "^15.5.7"
   },
   "devDependencies": {
-    "@djangocfg/imgai": "^1.0.22",
-    "@djangocfg/layouts": "^2.0.6",
-    "@djangocfg/typescript-config": "^1.4.36",
+    "@djangocfg/imgai": "^2.1.1",
+    "@djangocfg/layouts": "^2.1.1",
+    "@djangocfg/typescript-config": "^2.1.1",
     "@types/node": "^24.7.2",
     "@types/react": "19.2.2",
     "@types/react-dom": "19.2.1",
+    "@types/semver": "^7.7.1",
     "@types/webpack": "^5.28.5",
     "@vercel/og": "^0.8.5",
     "eslint": "^9.37.0",
     "linkinator": "^7.5.0",
-    "lucide-react": "^0.469.0",
+    "lucide-react": "^0.545.0",
     "picocolors": "^1.1.1",
     "prompts": "^2.4.2",
     "tsup": "^8.0.1",
@@ -120,6 +121,9 @@
     "access": "public"
   },
   "dependencies": {
-    "chalk": "^5.3.0"
+    "chalk": "^5.3.0",
+    "conf": "^15.0.2",
+    "consola": "^3.4.2",
+    "semver": "^7.7.3"
   }
 }

package/src/config/constants.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared Constants for DjangoCFG Next.js Configuration
+ */
+
+// Package name for version checks
+export const PACKAGE_NAME = '@djangocfg/nextjs';
+
+// Version cache TTL (1 hour)
+export const VERSION_CACHE_TTL_MS = 60 * 60 * 1000;
+
+// ASCII Art Banner for Django CFG
+export 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"
+`;
+
+// All @djangocfg packages that can be updated together
+export const DJANGOCFG_PACKAGES = [
+  '@djangocfg/ui-core',
+  '@djangocfg/ui-nextjs',
+  '@djangocfg/layouts',
+  '@djangocfg/nextjs',
+  '@djangocfg/api',
+  '@djangocfg/centrifugo',
+  '@djangocfg/eslint-config',
+  '@djangocfg/typescript-config',
+] as const;
+
+// Default packages to transpile
+export const DEFAULT_TRANSPILE_PACKAGES = [
+  '@djangocfg/ui-core',
+  '@djangocfg/ui-nextjs',
+  '@djangocfg/layouts',
+  '@djangocfg/nextjs',
+  '@djangocfg/api',
+  '@djangocfg/centrifugo',
+] as const;
+
+// Default packages to optimize imports
+export const DEFAULT_OPTIMIZE_PACKAGES = [
+  '@djangocfg/ui-core',
+  '@djangocfg/ui-nextjs',
+  '@djangocfg/layouts',
+  'lucide-react',
+  'recharts',
+] as const;

package/src/config/createNextConfig.ts

@@ -0,0 +1,209 @@
+/**
+ * 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';
+
+import { DEFAULT_TRANSPILE_PACKAGES, DEFAULT_OPTIMIZE_PACKAGES } from './constants';
+import { deepMerge } from './utils/deepMerge';
+import { isStaticBuild, isDev, getBasePath, getApiUrl, getSiteUrl } from './utils/env';
+import { DevStartupPlugin } from './plugins/devStartup';
+import { addCompressionPlugins } from './plugins/compression';
+
+// ─────────────────────────────────────────────────────────────────────────
+// Configuration Options
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface BaseNextConfigOptions {
+  /** 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) */
+  optimizePackageImports?: string[];
+  /** Automatically open browser in dev mode (default: false) */
+  openBrowser?: boolean;
+  /** Check for @djangocfg/* package updates on startup (default: true) */
+  checkUpdates?: boolean;
+  /** Auto-update outdated packages without prompting (default: false) */
+  autoUpdate?: boolean;
+  /** Force check workspace:* packages for updates (for testing in monorepo) */
+  forceCheckWorkspace?: boolean;
+  /** Check for missing optional packages on startup (default: true) */
+  checkPackages?: boolean;
+  /** Auto-install missing packages without prompting (default: false) */
+  autoInstall?: boolean;
+  /** 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;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// 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 {
+
+  const basePath = getBasePath(options.isDefaultCfgAdmin);
+  const apiUrl = getApiUrl();
+  const siteUrl = getSiteUrl();
+
+  // Base configuration
+  const baseConfig: NextConfig = {
+    reactStrictMode: true,
+    trailingSlash: true,
+
+    // Static export configuration
+    ...(isStaticBuild && {
+      output: 'export' as const,
+      distDir: 'out',
+      basePath: basePath,
+      // Fix for Next.js 15.5.4: prevent 500.html generation issue
+      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: apiUrl,
+      NEXT_PUBLIC_SITE_URL: siteUrl,
+      ...options.env,
+    },
+
+    // Images configuration
+    images: {
+      unoptimized: true,
+    },
+
+    // Transpile packages (merge with user-provided)
+    transpilePackages: [
+      ...DEFAULT_TRANSPILE_PACKAGES,
+      ...(options.transpilePackages || []),
+    ],
+
+    // Experimental features
+    experimental: {
+      // Optimize package imports (only in production)
+      ...(!isDev && {
+        optimizePackageImports: [
+          ...DEFAULT_OPTIMIZE_PACKAGES,
+          ...(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;
+
+      // Add dev startup plugin (client-side only in dev)
+      if (dev && !isServer) {
+        if (!config.plugins) {
+          config.plugins = [];
+        }
+        config.plugins.push(
+          new DevStartupPlugin({
+            openBrowser: options.openBrowser,
+            checkUpdates: options.checkUpdates,
+            autoUpdate: options.autoUpdate,
+            forceCheckWorkspace: options.forceCheckWorkspace,
+            checkPackages: options.checkPackages,
+            autoInstall: options.autoInstall,
+          })
+        );
+      }
+
+      // 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, client-side)
+      if (!isServer && isStaticBuild && !dev) {
+        addCompressionPlugins(config);
+      }
+
+      // 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 custom options that are not part of NextConfig
+  delete (finalConfig as any).optimizePackageImports;
+  delete (finalConfig as any).isDefaultCfgAdmin;
+  delete (finalConfig as any).openBrowser;
+  delete (finalConfig as any).checkUpdates;
+  delete (finalConfig as any).autoUpdate;
+  delete (finalConfig as any).forceCheckWorkspace;
+  delete (finalConfig as any).checkPackages;
+  delete (finalConfig as any).autoInstall;
+
+  return finalConfig;
+}

package/src/config/index.ts

@@ -1,6 +1,91 @@
 /**
  * Next.js Configuration Utilities
+ *
+ * @example
+ * ```typescript
+ * import { createBaseNextConfig } from '@djangocfg/nextjs/config';
+ *
+ * export default createBaseNextConfig({
+ *   openBrowser: true,
+ *   checkPackages: true,
+ * });
+ * ```
  */
 
-export { createBaseNextConfig, type BaseNextConfigOptions } from './base-next-config';
+// Main config factory
+export { createBaseNextConfig, type BaseNextConfigOptions } from './createNextConfig';
 
+// Constants
+export {
+  PACKAGE_NAME,
+  DJANGOCFG_PACKAGES,
+  DEFAULT_TRANSPILE_PACKAGES,
+  DEFAULT_OPTIMIZE_PACKAGES,
+  DJANGO_CFG_BANNER,
+} from './constants';
+
+// Utils
+export { deepMerge } from './utils/deepMerge';
+export {
+  isStaticBuild,
+  isDev,
+  isProduction,
+  isCI,
+  getBasePath,
+  getApiUrl,
+  getSiteUrl,
+} from './utils/env';
+export {
+  getCurrentVersion,
+  fetchLatestVersion,
+  checkForUpdate,
+  getUpdateCommand,
+  printVersionInfo,
+} from './utils/version';
+
+// Package management
+export {
+  OPTIONAL_PACKAGES,
+  PEER_DEPENDENCIES,
+  getPackagesForContext,
+  type PackageDefinition,
+} from './packages/definitions';
+export {
+  isPackageInstalled,
+  getMissingPackages,
+  checkPackages,
+  type MissingPackage,
+} from './packages/checker';
+export {
+  detectPackageManager,
+  buildSingleInstallCommand,
+  buildInstallCommand,
+  installPackages,
+  installPackagesWithProgress,
+  checkAndInstallPackages,
+  resetInstallerPreferences,
+  type InstallOptions,
+  type InstallProgress,
+} from './packages/installer';
+export {
+  getInstalledVersion,
+  checkForUpdates,
+  getOutdatedPackages,
+  updatePackagesWithProgress,
+  checkAndUpdatePackages,
+  resetUpdaterPreferences,
+  type PackageVersion,
+  type UpdateOptions,
+} from './packages/updater';
+
+// Plugins
+export {
+  DevStartupPlugin,
+  resetDevStartupState,
+  type DevStartupPluginOptions,
+} from './plugins/devStartup';
+export {
+  addCompressionPlugins,
+  isCompressionAvailable,
+  type CompressionPluginOptions,
+} from './plugins/compression';

package/src/config/packages/checker.ts

@@ -0,0 +1,94 @@
+/**
+ * Package Checker
+ *
+ * Checks which optional packages are missing and need to be installed.
+ */
+
+import { createRequire } from 'module';
+import { join } from 'path';
+import type { PackageDefinition } from './definitions';
+import { getPackagesForContext, OPTIONAL_PACKAGES } from './definitions';
+import { isStaticBuild, isDev } from '../utils/env';
+
+export interface MissingPackage extends PackageDefinition {
+  /** Why is this package needed? */
+  reason: string;
+}
+
+/**
+ * Check if a package is installed in the consumer's project
+ * Uses process.cwd() to check from the consumer's context, not the library's
+ */
+export function isPackageInstalled(packageName: string): boolean {
+  try {
+    // Create require from consumer's cwd to check their node_modules
+    const consumerRequire = createRequire(join(process.cwd(), 'package.json'));
+    consumerRequire.resolve(packageName);
+    return true;
+  } catch {
+    // Fallback: try regular require (for packages hoisted to root)
+    try {
+      require.resolve(packageName);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/**
+ * Get all missing packages for current context
+ */
+export function getMissingPackages(): MissingPackage[] {
+  const neededPackages = getPackagesForContext({ isStaticBuild, isDev });
+  const missing: MissingPackage[] = [];
+
+  for (const pkg of neededPackages) {
+    if (!isPackageInstalled(pkg.name)) {
+      missing.push({
+        ...pkg,
+        reason: getReasonText(pkg),
+      });
+    }
+  }
+
+  return missing;
+}
+
+/**
+ * Check specific packages
+ */
+export function checkPackages(packageNames: string[]): MissingPackage[] {
+  const missing: MissingPackage[] = [];
+
+  for (const name of packageNames) {
+    if (!isPackageInstalled(name)) {
+      const definition = OPTIONAL_PACKAGES.find(p => p.name === name);
+      missing.push({
+        name,
+        description: definition?.description || 'Optional package',
+        condition: definition?.condition || 'always',
+        devDependency: definition?.devDependency ?? true,
+        reason: definition ? getReasonText(definition) : 'Requested by configuration',
+      });
+    }
+  }
+
+  return missing;
+}
+
+/**
+ * Get human-readable reason for package requirement
+ */
+function getReasonText(pkg: PackageDefinition): string {
+  switch (pkg.condition) {
+    case 'static-build':
+      return 'Required for static build (NEXT_PUBLIC_STATIC_BUILD=true)';
+    case 'dev':
+      return 'Required for development mode';
+    case 'always':
+      return 'Required for all builds';
+    default:
+      return 'Optional feature';
+  }
+}

package/src/config/packages/definitions.ts

@@ -0,0 +1,67 @@
+/**
+ * Package Definitions
+ *
+ * Defines optional packages that can be auto-installed when needed.
+ */
+
+export interface PackageDefinition {
+  /** npm package name */
+  name: string;
+  /** Human-readable description */
+  description: string;
+  /** When is this package needed? */
+  condition: 'static-build' | 'dev' | 'always';
+  /** Is this a dev dependency? */
+  devDependency: boolean;
+  /** Feature flag that enables this package */
+  featureFlag?: string;
+}
+
+/**
+ * Optional packages that can be auto-installed
+ */
+export const OPTIONAL_PACKAGES: PackageDefinition[] = [
+  {
+    name: 'compression-webpack-plugin',
+    description: 'Gzip and Brotli compression for static builds',
+    condition: 'static-build',
+    devDependency: true,
+  },
+  {
+    name: '@next/bundle-analyzer',
+    description: 'Bundle analyzer for analyzing build output',
+    condition: 'dev',
+    devDependency: true,
+    featureFlag: 'ANALYZE',
+  },
+];
+
+/**
+ * Required peer dependencies (should already be installed)
+ */
+export const PEER_DEPENDENCIES = [
+  'next',
+  'react',
+  'react-dom',
+] as const;
+
+/**
+ * Get packages needed for current build context
+ */
+export function getPackagesForContext(options: {
+  isStaticBuild: boolean;
+  isDev: boolean;
+}): PackageDefinition[] {
+  return OPTIONAL_PACKAGES.filter(pkg => {
+    switch (pkg.condition) {
+      case 'static-build':
+        return options.isStaticBuild;
+      case 'dev':
+        return options.isDev;
+      case 'always':
+        return true;
+      default:
+        return false;
+    }
+  });
+}

package/src/config/packages/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Packages module exports
+ */
+
+export * from './definitions';
+export * from './checker';
+export {
+  detectPackageManager,
+  buildSingleInstallCommand,
+  buildInstallCommand,
+  installPackages,
+  installPackagesWithProgress,
+  checkAndInstallPackages,
+  resetInstallerPreferences,
+  type InstallOptions,
+  type InstallProgress,
+} from './installer';
+export {
+  getInstalledVersion,
+  checkForUpdates,
+  getOutdatedPackages,
+  updatePackagesWithProgress,
+  checkAndUpdatePackages,
+  resetUpdaterPreferences,
+  type PackageVersion,
+  type UpdateOptions,
+} from './updater';