@djangocfg/nextjs 2.1.35 → 2.1.37

package/src/config/plugins/pwa.ts

@@ -1,616 +0,0 @@
-/**
- * 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
- */
-
-import type { NextConfig } from 'next';
-import { consola } from 'consola';
-
-/**
- * Runtime caching handler strategies
- */
-export type CacheStrategy =
-  | 'CacheFirst'
-  | 'CacheOnly'
-  | 'NetworkFirst'
-  | 'NetworkOnly'
-  | 'StaleWhileRevalidate';
-
-/**
- * Runtime cache entry configuration
- */
-export 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;
-  };
-}
-
-export 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
- */
-export function isPWAAvailable(): boolean {
-  try {
-    require.resolve('@ducanh2912/next-pwa');
-    return true;
-  } catch {
-    // Try legacy next-pwa (not recommended for Next.js 13+)
-    try {
-      require.resolve('next-pwa');
-      consola.warn(
-        'Found legacy next-pwa. Please use @ducanh2912/next-pwa for Next.js 13+ support.\n' +
-        'Run: pnpm remove next-pwa && pnpm add @ducanh2912/next-pwa'
-      );
-      return true;
-    } catch {
-      return false;
-    }
-  }
-}
-
-/**
- * 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',
- *   },
- * });
- * ```
- */
-export function withPWA(
-  nextConfig: NextConfig,
-  options: Partial<PWAPluginOptions> = {}
-): NextConfig {
-  // Check if next-pwa is available
-  if (!isPWAAvailable()) {
-    consola.error(
-      '@ducanh2912/next-pwa is missing!\n' +
-        'This is unexpected as it should be installed automatically.\n' +
-        'Try: pnpm install --force\n' +
-        'PWA features will be disabled.'
-    );
-    return nextConfig;
-  }
-
-  const isDev = process.env.NODE_ENV === 'development';
-
-  const defaultOptions: Partial<PWAPluginOptions> = {
-    dest: 'public',
-    disable: options.disable !== undefined ? options.disable : isDev,
-    register: true,
-    skipWaiting: true,
-    clientsClaim: true,
-    cleanupOutdatedCaches: true,
-    publicExcludes: ['!noprecache/**/*'],
-    buildExcludes: [/middleware-manifest\.json$/, /build-manifest\.json$/],
-    cacheStartUrl: true,
-    dynamicStartUrl: true,
-    reloadOnOnline: true,
-    ...options,
-  };
-
-  try {
-    // Use modern next-pwa (@ducanh2912/next-pwa) - supports Next.js 13+
-    const withPWAImport = require('@ducanh2912/next-pwa').default;
-    return withPWAImport(defaultOptions)(nextConfig);
-  } catch {
-    try {
-      // Fallback to legacy next-pwa (not recommended for Next.js 13+)
-      const withPWAImport = require('next-pwa');
-      consola.warn('Using legacy next-pwa. Upgrade to @ducanh2912/next-pwa for Next.js 13+ support');
-      return withPWAImport(defaultOptions)(nextConfig);
-    } catch (error) {
-      consola.error('Failed to load next-pwa:', error);
-      return 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' },
- *     },
- *   ],
- * });
- * ```
- */
-export const defaultRuntimeCaching: RuntimeCacheEntry[] = [
-  {
-    urlPattern: /^https:\/\/fonts\.(?:gstatic)\.com\/.*/i,
-    handler: 'CacheFirst',
-    options: {
-      cacheName: 'google-fonts-webfonts',
-      expiration: {
-        maxEntries: 4,
-        maxAgeSeconds: 365 * 24 * 60 * 60, // 1 year
-      },
-    },
-  },
-  {
-    urlPattern: /^https:\/\/fonts\.(?:googleapis)\.com\/.*/i,
-    handler: 'StaleWhileRevalidate',
-    options: {
-      cacheName: 'google-fonts-stylesheets',
-      expiration: {
-        maxEntries: 4,
-        maxAgeSeconds: 7 * 24 * 60 * 60, // 1 week
-      },
-    },
-  },
-  {
-    urlPattern: /\.(?:eot|otf|ttc|ttf|woff|woff2|font.css)$/i,
-    handler: 'StaleWhileRevalidate',
-    options: {
-      cacheName: 'static-font-assets',
-      expiration: {
-        maxEntries: 4,
-        maxAgeSeconds: 7 * 24 * 60 * 60, // 1 week
-      },
-    },
-  },
-  {
-    urlPattern: /\.(?:jpg|jpeg|gif|png|svg|ico|webp)$/i,
-    handler: 'StaleWhileRevalidate',
-    options: {
-      cacheName: 'static-image-assets',
-      expiration: {
-        maxEntries: 64,
-        maxAgeSeconds: 24 * 60 * 60, // 24 hours
-      },
-    },
-  },
-  {
-    urlPattern: /\/_next\/image\?url=.+$/i,
-    handler: 'StaleWhileRevalidate',
-    options: {
-      cacheName: 'next-image',
-      expiration: {
-        maxEntries: 64,
-        maxAgeSeconds: 24 * 60 * 60, // 24 hours
-      },
-    },
-  },
-  {
-    urlPattern: /\.(?:mp3|wav|ogg)$/i,
-    handler: 'CacheFirst',
-    options: {
-      rangeRequests: true,
-      cacheName: 'static-audio-assets',
-      expiration: {
-        maxEntries: 32,
-        maxAgeSeconds: 24 * 60 * 60, // 24 hours
-      },
-    },
-  },
-  {
-    urlPattern: /\.(?:mp4)$/i,
-    handler: 'CacheFirst',
-    options: {
-      rangeRequests: true,
-      cacheName: 'static-video-assets',
-      expiration: {
-        maxEntries: 32,
-        maxAgeSeconds: 24 * 60 * 60, // 24 hours
-      },
-    },
-  },
-  {
-    urlPattern: /\.(?:js)$/i,
-    handler: 'StaleWhileRevalidate',
-    options: {
-      cacheName: 'static-js-assets',
-      expiration: {
-        maxEntries: 32,
-        maxAgeSeconds: 24 * 60 * 60, // 24 hours
-      },
-    },
-  },
-  {
-    urlPattern: /\.(?:css|less)$/i,
-    handler: 'StaleWhileRevalidate',
-    options: {
-      cacheName: 'static-style-assets',
-      expiration: {
-        maxEntries: 32,
-        maxAgeSeconds: 24 * 60 * 60, // 24 hours
-      },
-    },
-  },
-  {
-    urlPattern: /\/_next\/data\/.+\/.+\.json$/i,
-    handler: 'StaleWhileRevalidate',
-    options: {
-      cacheName: 'next-data',
-      expiration: {
-        maxEntries: 32,
-        maxAgeSeconds: 24 * 60 * 60, // 24 hours
-      },
-    },
-  },
-  {
-    urlPattern: /\.(?:json|xml|csv)$/i,
-    handler: 'NetworkFirst',
-    options: {
-      cacheName: 'static-data-assets',
-      expiration: {
-        maxEntries: 32,
-        maxAgeSeconds: 24 * 60 * 60, // 24 hours
-      },
-    },
-  },
-  {
-    urlPattern: ({ url }: { url: URL }) => {
-      const isSameOrigin = self.origin === url.origin;
-      if (!isSameOrigin) return false;
-      const pathname = url.pathname;
-      // Exclude /api/ routes
-      if (pathname.startsWith('/api/')) return false;
-      return true;
-    },
-    handler: 'NetworkFirst',
-    options: {
-      cacheName: 'pages',
-      expiration: {
-        maxEntries: 32,
-        maxAgeSeconds: 24 * 60 * 60, // 24 hours
-      },
-    },
-  },
-];
-
-/**
- * Helper: Create API caching rule
- *
- * @example
- * ```ts
- * createApiCacheRule('https://api.example.com', {
- *   strategy: 'NetworkFirst',
- *   maxAge: 300, // 5 minutes
- * });
- * ```
- */
-export function createApiCacheRule(
-  apiUrl: string,
-  options: {
-    strategy?: CacheStrategy;
-    maxAge?: number;
-    maxEntries?: number;
-    cacheName?: string;
-  } = {}
-): RuntimeCacheEntry {
-  const {
-    strategy = 'NetworkFirst',
-    maxAge = 300,
-    maxEntries = 50,
-    cacheName = 'api-cache',
-  } = options;
-
-  return {
-    urlPattern: new RegExp(`^${apiUrl.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/.*`, 'i'),
-    handler: strategy,
-    options: {
-      cacheName,
-      expiration: {
-        maxEntries,
-        maxAgeSeconds: maxAge,
-      },
-      networkTimeoutSeconds: 10,
-    },
-  };
-}
-
-/**
- * Helper: Create static asset caching rule
- *
- * @example
- * ```ts
- * createStaticAssetRule(['jpg', 'png', 'webp'], {
- *   strategy: 'CacheFirst',
- *   maxAge: 86400, // 1 day
- * });
- * ```
- */
-export function createStaticAssetRule(
-  extensions: string[],
-  options: {
-    strategy?: CacheStrategy;
-    maxAge?: number;
-    maxEntries?: number;
-    cacheName?: string;
-  } = {}
-): RuntimeCacheEntry {
-  const {
-    strategy = 'CacheFirst',
-    maxAge = 86400,
-    maxEntries = 64,
-    cacheName = 'static-assets',
-  } = options;
-
-  const pattern = extensions.map((ext) => ext.replace('.', '')).join('|');
-
-  return {
-    urlPattern: new RegExp(`\\.(?:${pattern})$`, 'i'),
-    handler: strategy,
-    options: {
-      cacheName,
-      expiration: {
-        maxEntries,
-        maxAgeSeconds: maxAge,
-      },
-    },
-  };
-}
-
-/**
- * Helper: Create CDN caching rule
- *
- * @example
- * ```ts
- * createCdnCacheRule('https://cdn.example.com', {
- *   strategy: 'CacheFirst',
- *   maxAge: 2592000, // 30 days
- * });
- * ```
- */
-export function createCdnCacheRule(
-  cdnUrl: string,
-  options: {
-    strategy?: CacheStrategy;
-    maxAge?: number;
-    maxEntries?: number;
-    cacheName?: string;
-  } = {}
-): RuntimeCacheEntry {
-  const {
-    strategy = 'CacheFirst',
-    maxAge = 2592000, // 30 days
-    maxEntries = 100,
-    cacheName = 'cdn-cache',
-  } = options;
-
-  return {
-    urlPattern: new RegExp(`^${cdnUrl.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/.*`, 'i'),
-    handler: strategy,
-    options: {
-      cacheName,
-      expiration: {
-        maxEntries,
-        maxAgeSeconds: maxAge,
-      },
-      cacheableResponse: {
-        statuses: [0, 200],
-      },
-    },
-  };
-}