@djangocfg/nextjs 2.1.30 → 2.1.31

package/src/config/plugins/pwa.ts

@@ -0,0 +1,616 @@
+/**
+ * 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],
+      },
+    },
+  };
+}

package/src/config/utils/index.ts

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