@djangocfg/nextjs 2.1.35 → 2.1.37

package/README.md

@@ -40,27 +40,6 @@ yarn add @djangocfg/nextjs
 
 ## Quick Start
 
-### Next.js Dev Server with Auto Browser Open
-
-Start Next.js dev server with automatic browser opening (works with both Turbopack and webpack):
-
-```bash
-# In package.json
-{
-  "scripts": {
-    "dev": "nextjs-dev -p 3000",           // Turbopack + auto browser open
-    "dev:webpack": "nextjs-dev --webpack"  // webpack + auto browser open
-  }
-}
-```
-
-**Features:**
-- ✅ Cross-platform (macOS, Windows, Linux)
-- ✅ Works with Turbopack (Next.js 16 default)
-- ✅ Works with webpack mode
-- ✅ Waits for server to be ready before opening
-- ✅ Zero configuration
-
 ### AI Documentation Search
 
 Search DjangoCFG documentation from the terminal:
@@ -137,7 +116,7 @@ export default withBundleAnalyzer(createBaseNextConfig({
 
 ```tsx
 // app/manifest.ts
-import { createManifest } from '@djangocfg/nextjs/config';
+import { createManifest, createScreenshots } from '@djangocfg/nextjs/config';
 import { settings } from '@core/settings';
 
 export default createManifest({
@@ -150,6 +129,12 @@ export default createManifest({
     logo384: settings.app.icons.logo384,
     logo512: settings.app.icons.logo512,
   },
+  // Optional: Add screenshots for Richer PWA Install UI
+  // IMPORTANT: Image dimensions must match sizes parameter!
+  // screenshots: createScreenshots([
+  //   '/screenshots/desktop-1920x1080.png',  // Wide: 1920x1080
+  //   '/screenshots/mobile-390x844.png',     // Narrow: 390x844
+  // ]),
 });
 ```
 
@@ -194,6 +179,141 @@ export default createBaseNextConfig({
 
 See [PWA.md](./PWA.md) for complete guide.
 
+### Push Notifications
+
+**Zero-config push notifications** using standard Web Push Protocol (no Firebase needed).
+
+#### PWA CLI
+
+Quick commands for managing push notifications:
+
+```bash
+# Generate VAPID keys
+pnpm pwa vapid
+
+# Check PWA status
+pnpm pwa status
+
+# Send test push
+pnpm pwa send '<subscription-json>'
+
+# Show help
+pnpm pwa info
+```
+
+#### 1. Generate VAPID keys
+
+```bash
+pnpm pwa vapid
+```
+
+Add to `.env.local`:
+
+```bash
+NEXT_PUBLIC_VAPID_PUBLIC_KEY=your_public_key_here
+VAPID_PRIVATE_KEY=your_private_key_here
+VAPID_MAILTO=mailto:your-email@example.com
+```
+
+#### 2. Add API routes
+
+```tsx
+// app/api/push/subscribe/route.ts
+export { POST, GET } from '@djangocfg/nextjs/pwa/server/routes';
+
+// app/api/push/send/route.ts
+export { handleSend as POST } from '@djangocfg/nextjs/pwa/server/routes';
+```
+
+#### 3. Enable push in service worker
+
+```tsx
+// app/sw.ts
+import { createServiceWorker } from '@djangocfg/nextjs/pwa/worker';
+import { settings } from '@core/settings';
+
+createServiceWorker({
+  offlineFallback: '/_offline',
+  enablePushNotifications: true,
+  notificationIcon: settings.app.icons.logo192,
+  notificationBadge: settings.app.icons.logo192,
+});
+```
+
+#### 4. Subscribe from client
+
+```tsx
+import { subscribeToPushNotifications } from '@djangocfg/nextjs/pwa';
+
+const subscription = await subscribeToPushNotifications({
+  vapidPublicKey: process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY!,
+});
+
+// Save subscription to server
+await fetch('/api/push/subscribe', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify(subscription),
+});
+```
+
+#### Testing with CLI
+
+```bash
+# 1. Start dev server
+pnpm dev
+
+# 2. Open browser console at http://localhost:3000
+# 3. Subscribe to push notifications:
+await (async () => {
+  const { subscribeToPushNotifications } = await import('@djangocfg/nextjs/pwa');
+  const sub = await subscribeToPushNotifications({
+    vapidPublicKey: 'YOUR_PUBLIC_KEY'
+  });
+  await fetch('/api/push/subscribe', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(sub)
+  });
+  console.log('Subscribed!', sub);
+})();
+
+# 4. Send test notification (from another console tab or curl):
+fetch('/api/push/send', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    subscription: { /* paste subscription object */ },
+    notification: {
+      title: 'Test Push',
+      body: 'Hello from CLI!',
+      icon: '/static/logos/192x192.png'
+    }
+  })
+});
+```
+
+Or use curl:
+
+```bash
+curl -X POST http://localhost:3000/api/push/send \
+  -H "Content-Type: application/json" \
+  -d '{
+    "subscription": {...},
+    "notification": {
+      "title": "Test",
+      "body": "Hello!"
+    }
+  }'
+```
+
+**Features:**
+- Standard Web Push Protocol (VAPID)
+- No Firebase or external services required
+- Auto-configuration with helpful warnings
+- Ready-to-use route handlers
+- Built-in subscription management
+
 ### Sitemap Generation
 
 Generate dynamic XML sitemaps for SEO:
@@ -320,6 +440,10 @@ import { RedirectPage } from '@djangocfg/layouts/components/RedirectPage';
 | `@djangocfg/nextjs` | Main exports (all modules) |
 | `@djangocfg/nextjs/ai` | AI documentation search and MCP config |
 | `@djangocfg/nextjs/config` | Base Next.js configuration factory |
+| `@djangocfg/nextjs/pwa` | PWA client utilities (service worker registration, push subscriptions) |
+| `@djangocfg/nextjs/pwa/worker` | Service worker creation helpers |
+| `@djangocfg/nextjs/pwa/server` | Server-side push notification utilities |
+| `@djangocfg/nextjs/pwa/server/routes` | Ready-to-use API route handlers for push |
 | `@djangocfg/nextjs/sitemap` | Sitemap generation utilities |
 | `@djangocfg/nextjs/health` | Health check handlers |
 | `@djangocfg/nextjs/og-image` | OG image generation |

package/dist/config/index.d.mts

@@ -1,313 +1,8 @@
-import { NextConfig, Metadata, MetadataRoute } from 'next';
+import { NextConfig } from 'next';
 import { Configuration, Compiler } from 'webpack';
+import { P as PWAPluginOptions } from '../plugin-DuRJ_Jq6.mjs';
 export { A as AI_DOCS_HINT, b as MCP_API_URL, M as MCP_BASE_URL, a as MCP_SERVER_URL } from '../constants-HezbftFb.mjs';
 
-/**
- * PWA (Progressive Web App) Plugin
- *
- * Configures @ducanh2912/next-pwa for service worker and offline support
- * Modern fork that supports Next.js 13+ with app directory
- *
- * @see https://www.npmjs.com/package/@ducanh2912/next-pwa
- */
-
-/**
- * Runtime caching handler strategies
- */
-type CacheStrategy = 'CacheFirst' | 'CacheOnly' | 'NetworkFirst' | 'NetworkOnly' | 'StaleWhileRevalidate';
-/**
- * Runtime cache entry configuration
- */
-interface RuntimeCacheEntry {
-    urlPattern: RegExp | string | ((context: {
-        url: URL;
-        request: Request;
-    }) => boolean);
-    handler: CacheStrategy;
-    options?: {
-        cacheName?: string;
-        expiration?: {
-            maxEntries?: number;
-            maxAgeSeconds?: number;
-            purgeOnQuotaError?: boolean;
-        };
-        cacheableResponse?: {
-            statuses?: number[];
-            headers?: Record<string, string>;
-        };
-        rangeRequests?: boolean;
-        backgroundSync?: {
-            name: string;
-            options?: {
-                maxRetentionTime?: number;
-            };
-        };
-        broadcastUpdate?: {
-            channelName?: string;
-            options?: {
-                headersToCheck?: string[];
-            };
-        };
-        matchOptions?: {
-            ignoreSearch?: boolean;
-            ignoreMethod?: boolean;
-            ignoreVary?: boolean;
-        };
-        networkTimeoutSeconds?: number;
-        plugins?: any[];
-        fetchOptions?: RequestInit;
-    };
-}
-interface PWAPluginOptions {
-    /**
-     * Destination directory for service worker files
-     * @default 'public'
-     */
-    dest: string;
-    /**
-     * Disable PWA completely
-     * @default false in production, true in development
-     * @example disable: process.env.NODE_ENV === 'development'
-     */
-    disable?: boolean;
-    /**
-     * Auto-register service worker
-     * @default true
-     * @description Set to false if you want to register SW manually
-     */
-    register?: boolean;
-    /**
-     * URL scope for PWA
-     * @default '/'
-     * @example '/app' - only /app/** will be PWA
-     */
-    scope?: string;
-    /**
-     * Service worker file name
-     * @default 'sw.js'
-     */
-    sw?: string;
-    /**
-     * Skip waiting for service worker activation
-     * @default true
-     * @description Activate new SW immediately
-     */
-    skipWaiting?: boolean;
-    /**
-     * Client claim - take control of uncontrolled clients immediately
-     * @default true
-     */
-    clientsClaim?: boolean;
-    /**
-     * Cleanup outdated caches automatically
-     * @default true
-     */
-    cleanupOutdatedCaches?: boolean;
-    /**
-     * Runtime caching strategies
-     * @default defaultRuntimeCaching
-     * @see defaultRuntimeCaching for default configuration
-     */
-    runtimeCaching?: RuntimeCacheEntry[];
-    /**
-     * Exclude files from build directory precaching
-     * @example [/chunks\/images\/.*$/] - don't precache images
-     */
-    buildExcludes?: (string | RegExp | ((chunk: any) => boolean))[];
-    /**
-     * Exclude files from public directory precaching
-     * @default ['!noprecache/**\/*']
-     * @example ['!videos/**\/*', '!large-images/**\/*']
-     */
-    publicExcludes?: string[];
-    /**
-     * Cache start URL (_app or / route)
-     * @default true
-     */
-    cacheStartUrl?: boolean;
-    /**
-     * Dynamic start URL (returns different HTML for different states)
-     * @default true
-     * @description Set to false if start URL always returns same HTML
-     */
-    dynamicStartUrl?: boolean;
-    /**
-     * Redirect URL if start URL redirects (e.g., to /login)
-     * @example '/login'
-     */
-    dynamicStartUrlRedirect?: string;
-    /**
-     * Enable additional route caching on front-end navigation
-     * @default false
-     * @description Cache routes when navigating with next/link
-     */
-    cacheOnFrontEndNav?: boolean;
-    /**
-     * Subdomain prefix for static files
-     * @deprecated Use basePath in next.config.js instead
-     */
-    subdomainPrefix?: string;
-    /**
-     * Reload app when device goes back online
-     * @default true
-     */
-    reloadOnOnline?: boolean;
-    /**
-     * Custom worker directory
-     * @default 'worker'
-     * @description Directory containing custom worker implementation
-     */
-    customWorkerDir?: string;
-    /**
-     * Custom service worker source (for InjectManifest mode)
-     * @description Path to your custom service worker source
-     */
-    swSrc?: string;
-    /**
-     * Offline fallback pages
-     * @example { document: '/_offline', image: '/offline.jpg' }
-     */
-    fallbacks?: {
-        document?: string;
-        image?: string;
-        audio?: string;
-        video?: string;
-        font?: string;
-    };
-    /**
-     * Additional workbox options
-     * @see https://developer.chrome.com/docs/workbox/modules/workbox-webpack-plugin
-     */
-    workboxOptions?: Record<string, any>;
-}
-/**
- * Check if @ducanh2912/next-pwa is installed
- *
- * Note: @ducanh2912/next-pwa is included as a dependency,
- * so this should always return true unless there's an installation issue
- */
-declare function isPWAAvailable(): boolean;
-/**
- * Add PWA configuration to Next.js config
- *
- * @example
- * ```ts
- * // Basic usage
- * export default withPWA(nextConfig, {
- *   dest: 'public',
- *   disable: process.env.NODE_ENV === 'development',
- * });
- *
- * // With custom runtime caching
- * export default withPWA(nextConfig, {
- *   dest: 'public',
- *   runtimeCaching: [
- *     {
- *       urlPattern: /^https:\/\/api\.example\.com\/.* /i,
- *       handler: 'NetworkFirst',
- *       options: {
- *         cacheName: 'api-cache',
- *         expiration: { maxEntries: 50, maxAgeSeconds: 300 },
- *       },
- *     },
- *   ],
- * });
- *
- * // With offline fallbacks
- * export default withPWA(nextConfig, {
- *   dest: 'public',
- *   fallbacks: {
- *     document: '/_offline',
- *     image: '/offline.jpg',
- *   },
- * });
- * ```
- */
-declare function withPWA(nextConfig: NextConfig, options?: Partial<PWAPluginOptions>): NextConfig;
-/**
- * Default runtime caching strategies
- *
- * Optimized caching rules for common assets:
- * - Google Fonts (webfonts + stylesheets)
- * - Static assets (images, fonts, audio, video)
- * - Next.js resources (JS, CSS, data, images)
- * - API routes excluded from page cache
- *
- * @example
- * ```ts
- * // Use default caching
- * withPWA(nextConfig, {
- *   dest: 'public',
- *   runtimeCaching: defaultRuntimeCaching,
- * });
- *
- * // Extend with custom rules
- * withPWA(nextConfig, {
- *   dest: 'public',
- *   runtimeCaching: [
- *     ...defaultRuntimeCaching,
- *     {
- *       urlPattern: /^https:\/\/api\.example\.com\/.* /i,
- *       handler: 'NetworkFirst',
- *       options: { cacheName: 'api-cache' },
- *     },
- *   ],
- * });
- * ```
- */
-declare const defaultRuntimeCaching: RuntimeCacheEntry[];
-/**
- * Helper: Create API caching rule
- *
- * @example
- * ```ts
- * createApiCacheRule('https://api.example.com', {
- *   strategy: 'NetworkFirst',
- *   maxAge: 300, // 5 minutes
- * });
- * ```
- */
-declare function createApiCacheRule(apiUrl: string, options?: {
-    strategy?: CacheStrategy;
-    maxAge?: number;
-    maxEntries?: number;
-    cacheName?: string;
-}): RuntimeCacheEntry;
-/**
- * Helper: Create static asset caching rule
- *
- * @example
- * ```ts
- * createStaticAssetRule(['jpg', 'png', 'webp'], {
- *   strategy: 'CacheFirst',
- *   maxAge: 86400, // 1 day
- * });
- * ```
- */
-declare function createStaticAssetRule(extensions: string[], options?: {
-    strategy?: CacheStrategy;
-    maxAge?: number;
-    maxEntries?: number;
-    cacheName?: string;
-}): RuntimeCacheEntry;
-/**
- * Helper: Create CDN caching rule
- *
- * @example
- * ```ts
- * createCdnCacheRule('https://cdn.example.com', {
- *   strategy: 'CacheFirst',
- *   maxAge: 2592000, // 30 days
- * });
- * ```
- */
-declare function createCdnCacheRule(cdnUrl: string, options?: {
-    strategy?: CacheStrategy;
-    maxAge?: number;
-    maxEntries?: number;
-    cacheName?: string;
-}): RuntimeCacheEntry;
-
 /**
  * Base Next.js Configuration Factory
  *
@@ -338,12 +33,6 @@ interface BaseNextConfigOptions {
     transpilePackages?: string[];
     /** Additional optimize package imports (merged with defaults) */
     optimizePackageImports?: string[];
-    /**
-     * Automatically open browser in dev mode (default: false)
-     * NOTE: Only works with webpack mode in Next.js 16+ (Turbopack doesn't support webpack plugins)
-     * For Turbopack compatibility, use a custom dev script instead of this option
-     */
-    openBrowser?: boolean;
     /** Check for @djangocfg/* package updates on startup (default: true) */
     checkUpdates?: boolean;
     /** Auto-update outdated packages without prompting (default: false) */
@@ -365,6 +54,8 @@ interface BaseNextConfigOptions {
      * @default { enabled: true (in production), disable: true (in development) }
      */
     pwa?: PWAPluginOptions | false;
+    /** Turbopack configuration (Next.js 16+ default bundler) */
+    turbopack?: NextConfig['turbopack'];
     /** Custom webpack configuration function (called after base webpack logic) */
     webpack?: (config: Configuration, options: {
         isServer: boolean;
@@ -612,12 +303,10 @@ declare function resetUpdaterPreferences(): void;
 /**
  * Dev Startup Webpack Plugin
  *
- * Handles banner display, version checking, package updates, and browser auto-open.
+ * Handles banner display, version checking, and package updates.
  */
 
 interface DevStartupPluginOptions {
-    /** Auto-open browser */
-    openBrowser?: boolean;
     /** Check for missing optional packages (default: true) */
     checkPackages?: boolean;
     /** Auto-install missing packages without prompting */
@@ -637,7 +326,7 @@ declare class DevStartupPlugin {
     constructor(options?: DevStartupPluginOptions);
     apply(compiler: Compiler): void;
     private runStartupTasks;
-    private openBrowser;
+    private checkPWASetup;
 }
 /**
  * Reset plugin state (useful for tests)
@@ -673,95 +362,4 @@ declare function addCompressionPlugins(config: Configuration, options?: Compress
  */
 declare function isCompressionAvailable(): boolean;
 
-/**
- * PWA Manifest Metadata Utilities
- *
- * Helper functions for creating Next.js metadata for PWA manifest
- */
-
-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
- */
-interface IconPaths {
-    logo192?: string;
-    logo384?: string;
-    logo512?: string;
-}
-/**
- * Create manifest metadata for Next.js app
- *
- * @example
- * ```typescript
- * export const metadata: Metadata = {
- *   ...createManifestMetadata({
- *     name: 'My App',
- *     shortName: 'App',
- *     description: 'My awesome app',
- *   }),
- * };
- * ```
- */
-declare function createManifestMetadata(config: ManifestConfig): Metadata;
-/**
- * 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,
- *   },
- * });
- * ```
- */
-declare function createManifest(config: {
-    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?: IconPaths | ManifestConfig['icons'];
-}): () => MetadataRoute.Manifest;
-/**
- * Generate manifest.json content (legacy)
- *
- * @deprecated Use createManifest() instead
- */
-declare function generateManifest(config: ManifestConfig): Record<string, any>;
-
-export { type BaseNextConfigOptions, type CacheStrategy, type CompressionPluginOptions, DEFAULT_OPTIMIZE_PACKAGES, DEFAULT_TRANSPILE_PACKAGES, DJANGOCFG_PACKAGES, DJANGO_CFG_BANNER, DevStartupPlugin, type DevStartupPluginOptions, type IconPaths, type InstallOptions, type InstallProgress, type ManifestConfig, type MissingPackage, OPTIONAL_PACKAGES, PACKAGE_NAME, PEER_DEPENDENCIES, type PWAPluginOptions, type PackageDefinition, type PackageVersion, type RuntimeCacheEntry, type UpdateOptions, addCompressionPlugins, buildInstallCommand, buildSingleInstallCommand, checkAndInstallPackages, checkAndUpdatePackages, checkForUpdate, checkForUpdates, checkPackages, createApiCacheRule, createBaseNextConfig, createCdnCacheRule, createManifest, createManifestMetadata, createStaticAssetRule, deepMerge, defaultRuntimeCaching, detectPackageManager, fetchLatestVersion, generateManifest, getApiUrl, getBasePath, getCurrentVersion, getInstalledVersion, getMissingPackages, getOutdatedPackages, getPackagesForContext, getSiteUrl, getUpdateCommand, installPackages, installPackagesWithProgress, isCI, isCompressionAvailable, isDev, isPWAAvailable, isPackageInstalled, isProduction, isStaticBuild, printVersionInfo, resetDevStartupState, resetInstallerPreferences, resetUpdaterPreferences, updatePackagesWithProgress, withPWA };
+export { type BaseNextConfigOptions, type CompressionPluginOptions, DEFAULT_OPTIMIZE_PACKAGES, DEFAULT_TRANSPILE_PACKAGES, DJANGOCFG_PACKAGES, DJANGO_CFG_BANNER, DevStartupPlugin, type DevStartupPluginOptions, type InstallOptions, type InstallProgress, type MissingPackage, OPTIONAL_PACKAGES, PACKAGE_NAME, PEER_DEPENDENCIES, type PackageDefinition, type PackageVersion, type UpdateOptions, addCompressionPlugins, buildInstallCommand, buildSingleInstallCommand, checkAndInstallPackages, checkAndUpdatePackages, checkForUpdate, checkForUpdates, checkPackages, createBaseNextConfig, deepMerge, detectPackageManager, fetchLatestVersion, getApiUrl, getBasePath, getCurrentVersion, getInstalledVersion, getMissingPackages, getOutdatedPackages, getPackagesForContext, getSiteUrl, getUpdateCommand, installPackages, installPackagesWithProgress, isCI, isCompressionAvailable, isDev, isPackageInstalled, isProduction, isStaticBuild, printVersionInfo, resetDevStartupState, resetInstallerPreferences, resetUpdaterPreferences, updatePackagesWithProgress };