@djangocfg/nextjs 2.1.35 → 2.1.37

package/src/config/plugins/devStartup.ts

@@ -1,7 +1,7 @@
 /**
  * Dev Startup Webpack Plugin
  *
- * Handles banner display, version checking, package updates, and browser auto-open.
+ * Handles banner display, version checking, and package updates.
  */
 
 import type { Compiler } from 'webpack';
@@ -14,11 +14,8 @@ import { checkAndUpdatePackages } from '../packages/updater';
 
 // Track if startup tasks were already run (persists across HMR)
 let startupDone = false;
-let browserOpened = false;
 
 export interface DevStartupPluginOptions {
-  /** Auto-open browser */
-  openBrowser?: boolean;
   /** Check for missing optional packages (default: true) */
   checkPackages?: boolean;
   /** Auto-install missing packages without prompting */
@@ -49,12 +46,6 @@ export class DevStartupPlugin {
         startupDone = true;
         await this.runStartupTasks();
       }
-
-      // Auto-open browser if enabled
-      if (this.options.openBrowser && !browserOpened) {
-        browserOpened = true;
-        this.openBrowser();
-      }
     });
   }
 
@@ -68,10 +59,13 @@ export class DevStartupPlugin {
       console.log(chalk.dim(`  📦 @djangocfg/nextjs v${version}`));
     }
 
-    // 3. Print AI docs hint
+    // 3. Check PWA setup
+    this.checkPWASetup();
+
+    // 4. Print AI docs hint
     console.log(chalk.magenta(`  ${AI_DOCS_HINT}\n`));
 
-    // 4. Check for package updates
+    // 5. Check for package updates
     if (this.options.checkUpdates !== false) {
       try {
         await checkAndUpdatePackages({
@@ -84,7 +78,7 @@ export class DevStartupPlugin {
       }
     }
 
-    // 5. Check for missing optional packages
+    // 6. Check for missing optional packages
     if (this.options.checkPackages !== false) {
       await checkAndInstallPackages({
         autoInstall: this.options.autoInstall,
@@ -92,29 +86,35 @@ export class DevStartupPlugin {
     }
   }
 
-  private openBrowser(): void {
-    // Delay to ensure server is ready
-    setTimeout(async () => {
-      try {
-        const { exec } = await import('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) => {
-          if (error) {
-            console.warn(`Failed to open browser: ${error.message}`);
-          }
-        });
-      } catch (error) {
-        console.warn('Failed to open browser');
+  private checkPWASetup(): void {
+    const fs = require('fs');
+    const path = require('path');
+
+    const cwd = process.cwd();
+    const swPath = path.join(cwd, 'app', 'sw.ts');
+    const manifestPath = path.join(cwd, 'app', 'manifest.ts');
+
+    const hasSW = fs.existsSync(swPath);
+    const hasManifest = fs.existsSync(manifestPath);
+
+    if (hasSW || hasManifest) {
+      console.log(chalk.cyan('  📱 PWA Configuration:'));
+
+      if (hasSW) {
+        console.log(chalk.green('     ✓ Service Worker: app/sw.ts'));
+      } else {
+        console.log(chalk.yellow('     ⚠ Service Worker: not found'));
+      }
+
+      if (hasManifest) {
+        console.log(chalk.green('     ✓ Manifest: app/manifest.ts'));
+      } else {
+        console.log(chalk.yellow('     ⚠ Manifest: not found'));
       }
-    }, 2000);
+
+      console.log(chalk.dim('     → Check: DevTools → Application → Service Workers'));
+      console.log(chalk.dim('     → Test push: import from @djangocfg/nextjs/pwa'));
+    }
   }
 }
 
@@ -123,5 +123,4 @@ export class DevStartupPlugin {
  */
 export function resetDevStartupState(): void {
   startupDone = false;
-  browserOpened = false;
 }

package/src/config/plugins/index.ts

@@ -4,4 +4,4 @@
 
 export { DevStartupPlugin, resetDevStartupState, type DevStartupPluginOptions } from './devStartup';
 export { addCompressionPlugins, isCompressionAvailable, type CompressionPluginOptions } from './compression';
-export { withPWA, isPWAAvailable, defaultRuntimeCaching, type PWAPluginOptions } from './pwa';
+export { withPWA, defaultRuntimeCaching, type PWAPluginOptions } from '../../pwa/plugin';

package/src/config/utils/index.ts

@@ -5,4 +5,3 @@
 export { deepMerge } from './deepMerge';
 export * from './env';
 export * from './version';
-export * from './manifest';

package/src/index.ts

@@ -25,3 +25,7 @@ export * from './ai';
 // Types
 export type * from './types';
 
+// PWA worker utilities (separate export for tree-shaking)
+// Import via: import { createServiceWorker } from '@djangocfg/nextjs/worker'
+// Note: worker/ has its own package.json with "type": "module"
+

package/src/pwa/cli.ts

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+/**
+ * DjangoCFG PWA CLI
+ *
+ * Usage:
+ *   pnpm pwa vapid              # Generate VAPID keys
+ *   pnpm pwa send               # Send test push notification
+ *   pnpm pwa status             # Show PWA status
+ *   pnpm pwa info               # Show help
+ */
+
+import { consola } from 'consola';
+import webpush from 'web-push';
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+async function generateVapidKeys() {
+  consola.box('VAPID Keys Generator');
+  consola.info('Generating new VAPID key pair...\n');
+
+  const vapidKeys = webpush.generateVAPIDKeys();
+
+  consola.success('✅ VAPID keys generated!\n');
+  consola.log('Add these to your .env.local:\n');
+  consola.log(`NEXT_PUBLIC_VAPID_PUBLIC_KEY=${vapidKeys.publicKey}`);
+  consola.log(`VAPID_PRIVATE_KEY=${vapidKeys.privateKey}`);
+  consola.log(`VAPID_MAILTO=mailto:your-email@example.com\n`);
+
+  consola.info('Public key (share with clients):');
+  consola.log(`  ${vapidKeys.publicKey}\n`);
+  consola.info('Private key (keep secret):');
+  consola.log(`  ${vapidKeys.privateKey}\n`);
+}
+
+async function sendTestPush() {
+  consola.box('Send Test Push Notification');
+
+  const publicKey = process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY;
+  const privateKey = process.env.VAPID_PRIVATE_KEY;
+  const mailto = process.env.VAPID_MAILTO || 'mailto:test@example.com';
+
+  if (!publicKey || !privateKey) {
+    consola.error('❌ VAPID keys not configured!');
+    consola.info('\nGenerate keys with:');
+    consola.log('  pnpm pwa vapid\n');
+    consola.info('Then add to .env.local:');
+    consola.log('  NEXT_PUBLIC_VAPID_PUBLIC_KEY=...');
+    consola.log('  VAPID_PRIVATE_KEY=...');
+    process.exit(1);
+  }
+
+  // Get subscription from args or use example
+  const subscriptionArg = args[1];
+  if (!subscriptionArg) {
+    consola.error('❌ Subscription required!\n');
+    consola.info('Usage:');
+    consola.log('  pnpm pwa send \'{"endpoint":"...","keys":{...}}\'\n');
+    consola.info('To subscribe and get the JSON, visit the playground:');
+    consola.log('  http://djangocfg.com/layouts/a2hs-hint\n');
+    consola.info('Or use the helper command:');
+    consola.log('  pnpm exec djangocfg-pwa status\n');
+    process.exit(1);
+  }
+
+  try {
+    const subscription = JSON.parse(subscriptionArg);
+
+    webpush.setVapidDetails(mailto, publicKey, privateKey);
+
+    const payload = JSON.stringify({
+      title: 'Test Push from CLI',
+      body: 'This is a test notification sent from @djangocfg/nextjs CLI',
+      icon: '/static/logos/192x192.png',
+      badge: '/static/logos/192x192.png',
+    });
+
+    consola.info('Sending push notification...\n');
+    await webpush.sendNotification(subscription, payload);
+    consola.success('✅ Push notification sent successfully!');
+  } catch (err) {
+    consola.error('❌ Failed to send push:', err instanceof Error ? err.message : err);
+    process.exit(1);
+  }
+}
+
+async function showStatus() {
+  consola.box('PWA Status');
+
+  const publicKey = process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY;
+  const privateKey = process.env.VAPID_PRIVATE_KEY;
+  const mailto = process.env.VAPID_MAILTO;
+
+  consola.log('Environment Variables:');
+  consola.log(`  NEXT_PUBLIC_VAPID_PUBLIC_KEY: ${publicKey ? '✅ Set' : '❌ Not set'}`);
+  consola.log(`  VAPID_PRIVATE_KEY:            ${privateKey ? '✅ Set' : '❌ Not set'}`);
+  consola.log(`  VAPID_MAILTO:                 ${mailto || '⚠️  Not set (optional)'}\n`);
+
+  if (!publicKey || !privateKey) {
+    consola.warn('⚠️  VAPID keys not configured. Run: pnpm pwa vapid\n');
+  } else {
+    consola.success('✅ VAPID keys configured\n');
+    consola.log('Public Key:');
+    consola.log(`  ${publicKey.slice(0, 40)}...\n`);
+  }
+
+  consola.log('Quick Start:');
+  consola.log('  1. Generate VAPID keys:  pnpm pwa vapid');
+  consola.log('  2. Add to .env.local');
+  consola.log('  3. Visit playground:     http://djangocfg.com/layouts/a2hs-hint');
+  consola.log('  4. Send test push:       pnpm pwa send \'<subscription>\'\n');
+}
+
+async function showInfo() {
+  consola.box('DjangoCFG PWA CLI');
+  consola.log('Commands:');
+  consola.log('  vapid               Generate VAPID keys');
+  consola.log('  send <subscription> Send test push notification');
+  consola.log('  status              Show PWA configuration status');
+  consola.log('  info                Show this help\n');
+
+  consola.log('Examples:');
+  consola.log('  # Generate VAPID keys');
+  consola.log('  pnpm pwa vapid\n');
+
+  consola.log('  # Check status');
+  consola.log('  pnpm pwa status\n');
+
+  consola.log('  # Subscribe');
+  consola.log('  Visit: http://djangocfg.com/layouts/a2hs-hint\n');
+
+  consola.log('  # Send test push');
+  consola.log('  pnpm pwa send \'{"endpoint":"...","keys":{"p256dh":"...","auth":"..."}}\'\n');
+
+  consola.log('Documentation:');
+  consola.log('  https://djangocfg.com/docs/pwa');
+}
+
+async function main() {
+  switch (command) {
+    case 'vapid':
+    case 'v':
+    case 'keys':
+      await generateVapidKeys();
+      break;
+
+    case 'send':
+    case 's':
+    case 'push':
+      await sendTestPush();
+      break;
+
+    case 'status':
+    case 'st':
+      await showStatus();
+      break;
+
+    case 'info':
+    case 'i':
+    case 'help':
+    case 'h':
+      await showInfo();
+      break;
+
+    default:
+      await showInfo();
+      break;
+  }
+}
+
+main();

package/src/pwa/index.ts

@@ -0,0 +1,9 @@
+/**
+ * PWA Utilities
+ *
+ * Client-side utilities for Progressive Web Apps
+ */
+
+export * from './notifications';
+export * from './manifest';
+export * from './plugin';

package/src/pwa/manifest.ts

@@ -0,0 +1,355 @@
+/**
+ * PWA Manifest Metadata Utilities
+ *
+ * Helper functions for creating Next.js metadata for PWA manifest
+ */
+
+import type { Metadata, MetadataRoute, Viewport } from 'next';
+
+export interface ManifestConfig {
+  name: string;
+  shortName?: string;
+  description?: string;
+  themeColor?: string;
+  backgroundColor?: string;
+  display?: 'standalone' | 'fullscreen' | 'minimal-ui' | 'browser';
+  orientation?: 'portrait' | 'landscape' | 'any';
+  startUrl?: string;
+  scope?: string;
+  lang?: string;
+  dir?: 'ltr' | 'rtl' | 'auto';
+  icons?: {
+    src: string;
+    sizes: string;
+    type?: string;
+    purpose?: string;
+  }[];
+}
+
+/**
+ * Icon paths configuration
+ */
+export interface IconPaths {
+  logo192?: string;
+  logo384?: string;
+  logo512?: string;
+}
+
+/**
+ * Protocol handler configuration
+ * Allows your PWA to register as a handler for custom protocols
+ *
+ * @example
+ * ```typescript
+ * {
+ *   protocol: "web+music",
+ *   url: "/play?track=%s"
+ * }
+ * ```
+ */
+export interface ProtocolHandler {
+  /** Protocol scheme (e.g., "web+music", "mailto", "magnet") */
+  protocol: string;
+  /** URL template with %s placeholder for the protocol parameter */
+  url: string;
+}
+
+/**
+ * Create viewport configuration for Next.js app
+ *
+ * @example
+ * ```typescript
+ * export const viewport: Viewport = createViewport({
+ *   themeColor: '#ffffff',
+ * });
+ * ```
+ */
+export function createViewport(config: { themeColor?: string }): Viewport {
+  return {
+    width: 'device-width',
+    initialScale: 1,
+    maximumScale: 1,
+    themeColor: config.themeColor || '#000000',
+  };
+}
+
+/**
+ * Create manifest metadata for Next.js app
+ *
+ * Note: themeColor and viewport should be exported separately using createViewport()
+ *
+ * @example
+ * ```typescript
+ * export const metadata: Metadata = {
+ *   ...createManifestMetadata({
+ *     name: 'My App',
+ *     shortName: 'App',
+ *     description: 'My awesome app',
+ *   }),
+ * };
+ *
+ * export const viewport: Viewport = createViewport({
+ *   themeColor: '#ffffff',
+ * });
+ * ```
+ */
+export function createManifestMetadata(config: ManifestConfig): Metadata {
+  return {
+    manifest: '/manifest.json',
+    appleWebApp: {
+      capable: true,
+      statusBarStyle: 'default',
+      title: config.shortName || config.name,
+    },
+    applicationName: config.name,
+    formatDetection: {
+      telephone: false,
+    },
+  };
+}
+
+/**
+ * Create Next.js manifest function
+ *
+ * Use this in your app/manifest.ts file
+ *
+ * @example
+ * ```typescript
+ * // app/manifest.ts
+ * import { createManifest } from '@djangocfg/nextjs/config';
+ * import { settings } from '@core/settings';
+ *
+ * export default createManifest({
+ *   name: settings.app.name,
+ *   description: settings.app.description,
+ *   icons: {
+ *     logo192: settings.app.icons.logo192,
+ *     logo384: settings.app.icons.logo384,
+ *     logo512: settings.app.icons.logo512,
+ *   },
+ * });
+ * ```
+ */
+export interface ScreenshotConfig {
+  src: string;
+  sizes: string;
+  type?: string;
+  form_factor?: 'narrow' | 'wide';
+  label?: string;
+}
+
+/**
+ * Smart screenshot configuration
+ * Automatically detects everything from path or uses defaults
+ */
+export interface SmartScreenshotInput {
+  src: string;
+  /** Form factor (auto-detected from filename if contains 'desktop'/'mobile', or use default) */
+  form_factor?: 'narrow' | 'wide';
+  /** Optional label (auto-generated from form_factor) */
+  label?: string;
+  /** Optional width (defaults based on form_factor) */
+  width?: number;
+  /** Optional height (defaults based on form_factor) */
+  height?: number;
+}
+
+/**
+ * Create screenshot config with smart defaults
+ * Automatically detects type, sizes, form_factor from path or uses sensible defaults
+ *
+ * @example
+ * ```typescript
+ * // Minimal - everything auto-detected
+ * createScreenshot({ src: '/screenshots/desktop-view.png' })
+ * // → form_factor: 'wide', sizes: '1920x1080', type: 'image/png', label: 'Desktop screenshot'
+ *
+ * createScreenshot({ src: '/screenshots/mobile.png' })
+ * // → form_factor: 'narrow', sizes: '390x844', type: 'image/png', label: 'Mobile screenshot'
+ *
+ * // With custom dimensions
+ * createScreenshot({ src: '/screenshots/tablet.png', width: 1024, height: 768 })
+ * ```
+ */
+export function createScreenshot(input: SmartScreenshotInput | string): ScreenshotConfig {
+  // Allow string shorthand
+  const config = typeof input === 'string' ? { src: input } : input;
+  let { src, width, height, label, form_factor } = config;
+
+  // Auto-detect image type from extension
+  const ext = src.split('.').pop()?.toLowerCase();
+  const typeMap: Record<string, string> = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    webp: 'image/webp',
+    svg: 'image/svg+xml',
+  };
+  const type = ext ? typeMap[ext] || 'image/png' : 'image/png';
+
+  // Try to parse dimensions from filename (e.g., "1920x1080.png" or "screenshot-390x844.png")
+  const filename = src.toLowerCase();
+  const dimensionMatch = filename.match(/(\d{3,4})x(\d{3,4})/);
+  if (dimensionMatch && !width && !height) {
+    width = parseInt(dimensionMatch[1], 10);
+    height = parseInt(dimensionMatch[2], 10);
+  }
+
+  // Auto-detect form_factor from filename if not provided
+  let autoFormFactor: 'narrow' | 'wide' = 'wide'; // Default to wide
+  if (filename.includes('mobile') || filename.includes('phone') || filename.includes('narrow')) {
+    autoFormFactor = 'narrow';
+  } else if (filename.includes('desktop') || filename.includes('laptop') || filename.includes('wide')) {
+    autoFormFactor = 'wide';
+  } else if (width && height) {
+    // Calculate from dimensions if provided or parsed
+    const aspectRatio = width / height;
+    autoFormFactor = aspectRatio > 1.2 ? 'wide' : 'narrow';
+  }
+
+  const finalFormFactor = form_factor || autoFormFactor;
+
+  // Default dimensions based on form_factor (only if not parsed from filename)
+  const defaultDimensions = finalFormFactor === 'wide'
+    ? { width: 1920, height: 1080 } // Desktop default
+    : { width: 390, height: 844 };  // Mobile default (iPhone 14)
+
+  const finalWidth = width || defaultDimensions.width;
+  const finalHeight = height || defaultDimensions.height;
+
+  // Auto-generate label
+  const autoLabel = finalFormFactor === 'wide'
+    ? 'Desktop screenshot'
+    : 'Mobile screenshot';
+
+  return {
+    src,
+    sizes: `${finalWidth}x${finalHeight}`,
+    type,
+    form_factor: finalFormFactor,
+    label: label || autoLabel,
+  };
+}
+
+/**
+ * Create multiple screenshots from array
+ * Supports string shorthand or full config objects
+ *
+ * @example
+ * ```typescript
+ * // Minimal - just paths
+ * createScreenshots([
+ *   '/screenshots/desktop.png',  // Auto: wide, 1920x1080
+ *   '/screenshots/mobile.png',   // Auto: narrow, 390x844
+ * ])
+ *
+ * // Mixed
+ * createScreenshots([
+ *   '/screenshots/desktop.png',
+ *   { src: '/screenshots/tablet.png', width: 1024, height: 768 },
+ * ])
+ * ```
+ */
+export function createScreenshots(inputs: Array<SmartScreenshotInput | string>): ScreenshotConfig[] {
+  return inputs.map(createScreenshot);
+}
+
+export function createManifest(config: {
+  name: string;
+  shortName?: string;
+  description?: string;
+  themeColor?: string;
+  backgroundColor?: string;
+  display?: 'standalone' | 'fullscreen' | 'minimal-ui' | 'browser';
+  orientation?: 'portrait' | 'landscape' | 'any';
+  id?: string;
+  startUrl?: string;
+  scope?: string;
+  lang?: string;
+  dir?: 'ltr' | 'rtl' | 'auto';
+  icons?: IconPaths | ManifestConfig['icons'];
+  screenshots?: ScreenshotConfig[];
+  protocol_handlers?: ProtocolHandler[];
+}): () => MetadataRoute.Manifest {
+  return () => {
+    // Convert IconPaths to manifest icons format
+    let manifestIcons: MetadataRoute.Manifest['icons'];
+
+    if (Array.isArray(config.icons)) {
+      // Already in manifest format
+      manifestIcons = config.icons as MetadataRoute.Manifest['icons'];
+    } else if (config.icons) {
+      // Convert IconPaths to manifest icons
+      const { logo192, logo384, logo512 } = config.icons as IconPaths;
+      manifestIcons = [
+        ...(logo192
+          ? [
+              {
+                src: logo192,
+                sizes: '192x192',
+                type: 'image/png',
+                purpose: 'maskable' as const,
+              },
+            ]
+          : []),
+        ...(logo384
+          ? [
+              {
+                src: logo384,
+                sizes: '384x384',
+                type: 'image/png',
+              },
+            ]
+          : []),
+        ...(logo512
+          ? [
+              {
+                src: logo512,
+                sizes: '512x512',
+                type: 'image/png',
+              },
+            ]
+          : []),
+      ];
+    }
+
+    const manifest: MetadataRoute.Manifest = {
+      name: config.name,
+      short_name: config.shortName || config.name,
+      description: config.description || config.name,
+      id: config.id || config.startUrl || '/',
+      start_url: config.startUrl || '/',
+      scope: config.scope || '/',
+      display: config.display || 'standalone',
+      orientation: config.orientation || 'portrait',
+      background_color: config.backgroundColor || '#000000',
+      theme_color: config.themeColor || '#ffffff',
+      lang: config.lang || 'en',
+      dir: config.dir || 'ltr',
+      icons: manifestIcons,
+      // Removed forced gcm_sender_id to avoid potential conflicts with VAPID
+      // gcm_sender_id: '103953800507',
+    };
+
+    // Add screenshots if provided (for Richer PWA Install UI)
+    if (config.screenshots && config.screenshots.length > 0) {
+      (manifest as any).screenshots = config.screenshots;
+    }
+
+    // Add protocol handlers if provided
+    if (config.protocol_handlers && config.protocol_handlers.length > 0) {
+      (manifest as any).protocol_handlers = config.protocol_handlers;
+    }
+
+    return manifest;
+  };
+}
+
+/**
+ * Generate manifest.json content (legacy)
+ *
+ * @deprecated Use createManifest() instead
+ */
+export function generateManifest(config: ManifestConfig): Record<string, any> {
+  return createManifest(config)();
+}