@djangocfg/nextjs 2.1.30 → 2.1.32

package/README.md

@@ -17,6 +17,7 @@
 
 ## Features
 
+- **Zero-Config PWA** - Progressive Web App out of the box (service worker, offline support, manifest)
 - **Base Next.js Config** - Universal, reusable Next.js configuration factory for monorepos
 - **AI Documentation** - Search DjangoCFG docs via MCP server and CLI
 - **Sitemap Generation** - Dynamic XML sitemap generation for SEO
@@ -106,6 +107,71 @@ export default withBundleAnalyzer(createBaseNextConfig({
 }));
 ```
 
+### PWA (Progressive Web App)
+
+**Zero-config PWA** - Works out of the box! Service worker and offline support included automatically.
+
+#### 1. Create manifest
+
+```tsx
+// 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,
+  themeColor: '#ffffff',
+  backgroundColor: '#000000',
+  icons: {
+    logo192: settings.app.icons.logo192,
+    logo384: settings.app.icons.logo384,
+    logo512: settings.app.icons.logo512,
+  },
+});
+```
+
+#### 2. Add manifest metadata
+
+```tsx
+// app/layout.tsx
+import { createManifestMetadata } from '@djangocfg/nextjs/config';
+
+export const metadata = {
+  ...createManifestMetadata({
+    name: 'My App',
+    themeColor: '#000000',
+  }),
+};
+```
+
+**That's it!** PWA is now enabled in production. Generated files:
+- `/manifest.webmanifest` - From `app/manifest.ts`
+- `/sw.js` - Service worker (auto-generated in production)
+- `/workbox-*.js` - Workbox runtime
+
+**Customization** (optional):
+
+```tsx
+// next.config.ts
+export default createBaseNextConfig({
+  pwa: {
+    dest: 'public',
+    disable: process.env.NODE_ENV === 'development', // Disable in dev
+    fallbacks: {
+      document: '/_offline', // Offline page
+    },
+    runtimeCaching: [
+      // Custom caching rules
+      ...defaultRuntimeCaching,
+      createApiCacheRule('https://api.example.com'),
+    ],
+  },
+});
+```
+
+See [PWA.md](./PWA.md) for complete guide.
+
 ### Sitemap Generation
 
 Generate dynamic XML sitemaps for SEO:

package/dist/config/index.d.mts

@@ -1,7 +1,313 @@
-import { NextConfig } from 'next';
+import { NextConfig, Metadata, MetadataRoute } from 'next';
 import { Configuration, Compiler } from 'webpack';
 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
  *
@@ -49,6 +355,12 @@ interface BaseNextConfigOptions {
      * Set to ['*'] to allow all origins, or specify domains like ['https://djangocfg.com']
      */
     allowIframeFrom?: string[];
+    /**
+     * PWA configuration options
+     * Set to false to disable PWA, or provide custom options
+     * @default { enabled: true (in production), disable: true (in development) }
+     */
+    pwa?: PWAPluginOptions | false;
     /** Custom webpack configuration function (called after base webpack logic) */
     webpack?: (config: Configuration, options: {
         isServer: boolean;
@@ -357,4 +669,95 @@ declare function addCompressionPlugins(config: Configuration, options?: Compress
  */
 declare function isCompressionAvailable(): boolean;
 
-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 };
+/**
+ * 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 };