@djangocfg/layouts 2.1.37 → 2.1.39

package/src/snippets/PWA/@refactoring2/COMPARISON-WITH-NEXTJS.md

@@ -1,718 +0,0 @@
-# Comparison: layouts/PWA vs nextjs/PWA
-
-**Date**: December 2025
-**Purpose**: Compare architectures and identify integration opportunities
-
-## Executive Summary
-
-**layouts/PWA** and **nextjs/PWA** solve different parts of the PWA puzzle:
-
-| Package | Focus | Strength |
-|---------|-------|----------|
-| **layouts** | UI/UX for install prompts + push notifications | User-facing components |
-| **nextjs** | Build-time configuration + service worker generation | Developer tooling |
-
-**Key Insight**: These packages are **complementary, not competing**
-
-**Integration Opportunity**: Use both together for a complete PWA solution
-
----
-
-## Architecture Comparison
-
-### layouts/PWA Architecture
-
-```
-Frontend Runtime (React Components + Hooks)
-├── Installation Flow
-│   ├── A2HSHint (iOS + Android unified prompt)
-│   ├── IOSGuide (visual instructions)
-│   ├── useInstallPrompt (beforeinstallprompt handling)
-│   └── useIsPWA (standalone detection)
-│
-├── Push Notifications
-│   ├── PushPrompt (subscription prompt)
-│   ├── PushContext (state management)
-│   └── usePushNotifications (subscription logic)
-│
-└── Utilities
-    ├── platform.ts (detection)
-    ├── logger.ts (conditional logging)
-    ├── vapid.ts (key validation)
-    └── localStorage.ts (persistence)
-```
-
-**Focus**: User-facing components for PWA installation and push notifications
-
-**Runtime**: Client-side React components
-
-### nextjs/PWA Architecture
-
-```
-Build-Time Configuration (Next.js Plugin)
-├── Service Worker Generation
-│   ├── withPWA() (Next.js plugin)
-│   ├── Runtime caching strategies
-│   ├── Precaching of static assets
-│   └── Workbox integration
-│
-├── Manifest Generation
-│   ├── manifest.json builder
-│   ├── Icon generation
-│   └── PWA metadata
-│
-└── Utilities
-    ├── registerServiceWorker()
-    ├── cacheFirst / networkFirst strategies
-    └── Background sync
-```
-
-**Focus**: Build-time PWA configuration and service worker management
-
-**Runtime**: Build-time code generation + minimal runtime utilities
-
----
-
-## Feature Comparison
-
-### 1. Installation Flow
-
-| Feature | layouts | nextjs | Winner |
-|---------|---------|--------|--------|
-| beforeinstallprompt handling | ✅ Full support | ⚠️ Manual | layouts |
-| iOS Safari instructions | ✅ Visual guide | ❌ None | layouts |
-| Install button component | ✅ A2HSHint | ❌ None | layouts |
-| Standalone detection | ✅ Excellent (cached, reliable) | ⚠️ Basic utility | layouts |
-| Dismissal persistence | ✅ With auto-reset | ❌ None | layouts |
-
-**Winner**: **layouts** - Complete UI/UX for installation
-
-**nextjs**: Provides manifest generation but no UI
-
-### 2. Push Notifications
-
-| Feature | layouts | nextjs | Winner |
-|---------|---------|--------|--------|
-| Subscription UI | ✅ PushPrompt | ❌ None | layouts |
-| VAPID validation | ✅ Robust with errors | ⚠️ Basic | layouts |
-| Push state management | ✅ React Context | ❌ None | layouts |
-| Message handling | ✅ Service Worker integration | ⚠️ Manual | layouts |
-| Server-side persistence | ⚠️ Frontend only | ⚠️ Not handled | Tie |
-
-**Winner**: **layouts** - Complete push notification flow
-
-**nextjs**: Only provides service worker infrastructure
-
-### 3. Service Worker
-
-| Feature | layouts | nextjs | Winner |
-|---------|---------|--------|--------|
-| Service Worker generation | ❌ Manual | ✅ Automatic (Workbox) | nextjs |
-| Runtime caching | ❌ External | ✅ Built-in | nextjs |
-| Precaching | ❌ Manual | ✅ Automatic | nextjs |
-| Custom strategies | ❌ External | ✅ Configurable | nextjs |
-| Background sync | ❌ Manual | ✅ Built-in | nextjs |
-
-**Winner**: **nextjs** - Complete service worker management
-
-**layouts**: Assumes service worker exists externally
-
-### 4. Manifest
-
-| Feature | layouts | nextjs | Winner |
-|---------|---------|--------|--------|
-| manifest.json generation | ❌ Manual | ✅ Automatic | nextjs |
-| Icon generation | ❌ Manual | ✅ Multiple sizes | nextjs |
-| Theme configuration | ❌ Manual | ✅ From config | nextjs |
-| Validation | ❌ None | ✅ Build-time | nextjs |
-
-**Winner**: **nextjs** - Automatic manifest generation
-
-**layouts**: Expects manifest to exist
-
-### 5. Developer Experience
-
-| Feature | layouts | nextjs | Winner |
-|---------|---------|--------|--------|
-| Setup complexity | 🟡 Medium | 🟢 Low | nextjs |
-| Documentation | 🟢 Excellent | 🟢 Excellent | Tie |
-| TypeScript support | 🟢 Full | 🟢 Full | Tie |
-| Error messages | 🟢 Excellent | 🟡 Basic | layouts |
-| Debug tools | 🟢 Logger + debug mode | 🟡 Console only | layouts |
-
-**Winner**: Depends on use case
-
-**nextjs**: Easier to get started (one config)
-
-**layouts**: Better runtime debugging
-
----
-
-## Code Examples
-
-### layouts/PWA Usage
-
-```tsx
-// app/layout.tsx
-import { PwaProvider } from '@djangocfg/layouts/snippets';
-
-export default function RootLayout({ children }) {
-  return (
-    <html>
-      <body>
-        <PwaProvider
-          enabled
-          showInstallHint
-          resetAfterDays={3}
-          pushNotifications={{
-            vapidPublicKey: process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY!,
-            subscribeEndpoint: '/api/push/subscribe',
-          }}
-        >
-          {children}
-        </PwaProvider>
-      </body>
-    </html>
-  );
-}
-```
-
-**What you get**:
-- ✅ Install prompts (iOS + Android)
-- ✅ Push notification prompt
-- ✅ State management
-- ❌ No service worker
-- ❌ No manifest
-- ❌ No caching
-
-### nextjs/PWA Usage
-
-```js
-// next.config.mjs
-import withPWA from '@djangocfg/nextjs/pwa';
-
-export default withPWA({
-  dest: 'public',
-  register: true,
-  skipWaiting: true,
-  runtimeCaching: [
-    {
-      urlPattern: /^https?.*/,
-      handler: 'NetworkFirst',
-      options: {
-        cacheName: 'offlineCache',
-        expiration: {
-          maxEntries: 200,
-        },
-      },
-    },
-  ],
-  manifest: {
-    name: 'My App',
-    short_name: 'App',
-    theme_color: '#000000',
-    background_color: '#ffffff',
-    display: 'standalone',
-    icons: [
-      {
-        src: '/icon-192x192.png',
-        sizes: '192x192',
-        type: 'image/png',
-      },
-    ],
-  },
-});
-```
-
-**What you get**:
-- ✅ Service worker (auto-generated)
-- ✅ manifest.json (auto-generated)
-- ✅ Runtime caching
-- ✅ Offline support
-- ❌ No install UI
-- ❌ No push notification UI
-
-### Combined Usage (Recommended)
-
-```tsx
-// next.config.mjs
-import withPWA from '@djangocfg/nextjs/pwa';
-
-export default withPWA({
-  // Service worker + manifest configuration
-  dest: 'public',
-  register: true,
-  manifest: { /* ... */ },
-});
-```
-
-```tsx
-// app/layout.tsx
-import { PwaProvider } from '@djangocfg/layouts/snippets';
-
-export default function RootLayout({ children }) {
-  return (
-    <html>
-      <body>
-        {/* UI components for install + push */}
-        <PwaProvider
-          enabled
-          pushNotifications={{ /* ... */ }}
-        >
-          {children}
-        </PwaProvider>
-      </body>
-    </html>
-  );
-}
-```
-
-**What you get**:
-- ✅ Service worker (nextjs)
-- ✅ Manifest (nextjs)
-- ✅ Runtime caching (nextjs)
-- ✅ Install UI (layouts)
-- ✅ Push notification UI (layouts)
-- ✅ Complete PWA solution 🎉
-
----
-
-## Integration Opportunities
-
-### 1. Unified Configuration
-
-**Problem**: Two separate configurations
-
-**Solution**: Single PWA config object
-
-```typescript
-// pwa.config.ts
-export const pwaConfig = {
-  // nextjs/PWA configuration
-  serviceWorker: {
-    dest: 'public',
-    register: true,
-    skipWaiting: true,
-    runtimeCaching: [ /* ... */ ],
-  },
-
-  // Manifest configuration
-  manifest: {
-    name: 'My App',
-    short_name: 'App',
-    theme_color: '#000000',
-    icons: [ /* ... */ ],
-  },
-
-  // layouts/PWA configuration
-  ui: {
-    enabled: true,
-    showInstallHint: true,
-    resetAfterDays: 3,
-    pushNotifications: {
-      vapidPublicKey: process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY!,
-      subscribeEndpoint: '/api/push/subscribe',
-    },
-  },
-};
-```
-
-```tsx
-// next.config.mjs
-import withPWA from '@djangocfg/nextjs/pwa';
-import { pwaConfig } from './pwa.config';
-
-export default withPWA(pwaConfig.serviceWorker, pwaConfig.manifest);
-```
-
-```tsx
-// app/layout.tsx
-import { PwaProvider } from '@djangocfg/layouts/snippets';
-import { pwaConfig } from '@/pwa.config';
-
-export default function RootLayout({ children }) {
-  return (
-    <html>
-      <body>
-        <PwaProvider {...pwaConfig.ui}>
-          {children}
-        </PwaProvider>
-      </body>
-    </html>
-  );
-}
-```
-
-### 2. Service Worker Communication
-
-**Opportunity**: layouts components could communicate with nextjs service worker
-
-```typescript
-// layouts/PWA: Listen for SW update events
-export function useServiceWorkerUpdate() {
-  const [updateAvailable, setUpdateAvailable] = useState(false);
-
-  useEffect(() => {
-    if ('serviceWorker' in navigator) {
-      navigator.serviceWorker.addEventListener('controllerchange', () => {
-        setUpdateAvailable(true);
-      });
-    }
-  }, []);
-
-  return { updateAvailable };
-}
-
-// Usage in component
-function UpdatePrompt() {
-  const { updateAvailable } = useServiceWorkerUpdate();
-
-  if (!updateAvailable) return null;
-
-  return (
-    <div className="fixed bottom-4 right-4">
-      <Button onClick={() => window.location.reload()}>
-        Update Available - Reload
-      </Button>
-    </div>
-  );
-}
-```
-
-### 3. Shared Types
-
-**Opportunity**: Share TypeScript types between packages
-
-```typescript
-// @djangocfg/pwa-types (new package)
-export interface PWAManifest {
-  name: string;
-  short_name: string;
-  theme_color: string;
-  background_color: string;
-  display: 'standalone' | 'fullscreen' | 'minimal-ui' | 'browser';
-  icons: ManifestIcon[];
-}
-
-export interface RuntimeCachingStrategy {
-  urlPattern: RegExp | string;
-  handler: 'CacheFirst' | 'NetworkFirst' | 'StaleWhileRevalidate';
-  options?: CachingOptions;
-}
-
-export interface PushNotificationConfig {
-  vapidPublicKey: string;
-  subscribeEndpoint?: string;
-}
-```
-
-Both packages import from shared types package.
-
-### 4. CLI Tool Integration
-
-**Opportunity**: Single CLI for PWA management
-
-```bash
-# Generate VAPID keys
-pnpm pwa generate-vapid
-
-# Validate PWA configuration
-pnpm pwa validate
-
-# Test push notifications
-pnpm pwa test-push --endpoint http://localhost:3000
-
-# Analyze PWA score
-pnpm pwa audit
-```
-
-Could be implemented in `@djangocfg/nextjs` CLI.
-
----
-
-## Strengths and Weaknesses
-
-### layouts/PWA
-
-**Strengths** ✅:
-1. Complete UI/UX for installation flow
-2. Excellent platform detection (iOS + Android)
-3. Robust push notification handling
-4. Great developer experience (error messages, debug mode)
-5. Adaptive UI (drawer on mobile, modal on desktop)
-6. Well-documented with examples
-
-**Weaknesses** ⚠️:
-1. No service worker generation
-2. No manifest generation
-3. Assumes external SW exists
-4. No runtime caching utilities
-5. Frontend-only (no backend integration examples)
-
-**Best For**:
-- Apps that need polished install prompts
-- Apps with push notifications
-- Custom PWA experiences
-- When you already have a service worker
-
-### nextjs/PWA
-
-**Strengths** ✅:
-1. Automatic service worker generation
-2. Automatic manifest generation
-3. Built-in runtime caching (Workbox)
-4. Zero-config PWA setup
-5. Build-time optimization
-6. Precaching of static assets
-
-**Weaknesses** ⚠️:
-1. No UI components for installation
-2. No push notification handling
-3. Limited runtime utilities
-4. Less control over SW behavior
-5. No install prompt customization
-
-**Best For**:
-- Quick PWA setup
-- Apps that need offline support
-- Standard PWA requirements
-- When you want automatic configuration
-
----
-
-## Learning Opportunities
-
-### What layouts can learn from nextjs
-
-1. **Automatic Generation**
-   - Consider generating boilerplate code
-   - CLI tool for scaffolding
-
-2. **Build-Time Validation**
-   - Validate VAPID keys at build time
-   - Check manifest exists
-   - Verify service worker registration
-
-3. **Convention over Configuration**
-   - Sensible defaults
-   - Less boilerplate
-
-4. **Service Worker Utilities**
-   - Provide optional SW helpers
-   - Runtime caching utilities
-
-### What nextjs can learn from layouts
-
-1. **UI Components**
-   - Provide default install prompt components
-   - Push notification UI
-
-2. **Runtime Debugging**
-   - Better error messages
-   - Debug mode in production
-   - Diagnostic tools
-
-3. **Platform Detection**
-   - Better iOS/Android detection
-   - Reliable standalone checking
-
-4. **State Management**
-   - React Context for PWA state
-   - Hooks for common patterns
-
----
-
-## Recommended Integration Pattern
-
-### Complete PWA Stack
-
-```
-┌─────────────────────────────────────┐
-│     User Experience (Frontend)     │
-│                                     │
-│  layouts/PWA                        │
-│  ├── Install Prompts (A2HSHint)    │
-│  ├── Push Notifications (PushPrompt)│
-│  └── State Management (Context)    │
-└─────────────────────────────────────┘
-              ↓ ↑
-┌─────────────────────────────────────┐
-│   Infrastructure (Build + Runtime)  │
-│                                     │
-│  nextjs/PWA                         │
-│  ├── Service Worker (Workbox)      │
-│  ├── Manifest Generation            │
-│  └── Runtime Caching                │
-└─────────────────────────────────────┘
-              ↓ ↑
-┌─────────────────────────────────────┐
-│         Backend (API Routes)        │
-│                                     │
-│  ├── /api/push/subscribe            │
-│  ├── /api/push/send                 │
-│  └── Database (subscriptions)       │
-└─────────────────────────────────────┘
-```
-
-### Setup Checklist
-
-**Step 1: Install dependencies**
-```bash
-pnpm add @djangocfg/nextjs @djangocfg/layouts
-```
-
-**Step 2: Configure nextjs/PWA (Build-Time)**
-```js
-// next.config.mjs
-import withPWA from '@djangocfg/nextjs/pwa';
-
-export default withPWA({
-  dest: 'public',
-  register: true,
-  skipWaiting: true,
-  manifest: {
-    name: 'My App',
-    short_name: 'App',
-    theme_color: '#000000',
-    display: 'standalone',
-    icons: [ /* ... */ ],
-  },
-  runtimeCaching: [ /* ... */ ],
-});
-```
-
-**Step 3: Add layouts/PWA UI (Runtime)**
-```tsx
-// app/layout.tsx
-import { PwaProvider } from '@djangocfg/layouts/snippets';
-
-export default function RootLayout({ children }) {
-  return (
-    <html>
-      <body>
-        <PwaProvider
-          enabled
-          showInstallHint
-          pushNotifications={{
-            vapidPublicKey: process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY!,
-            subscribeEndpoint: '/api/push/subscribe',
-          }}
-        >
-          {children}
-        </PwaProvider>
-      </body>
-    </html>
-  );
-}
-```
-
-**Step 4: Add Backend API Routes**
-```typescript
-// app/api/push/subscribe/route.ts
-export async function POST(request: Request) {
-  const subscription = await request.json();
-  // Save to database
-  return Response.json({ success: true });
-}
-```
-
-**Result**: Complete PWA with:
-- ✅ Service worker (nextjs)
-- ✅ Manifest (nextjs)
-- ✅ Offline support (nextjs)
-- ✅ Install UI (layouts)
-- ✅ Push notifications (layouts)
-- ✅ Backend persistence (custom)
-
----
-
-## Future Opportunities
-
-### 1. Unified PWA Package
-
-**Vision**: Single package combining both
-
-```
-@djangocfg/pwa
-├── Build-time (from nextjs/PWA)
-│   ├── withPWA()
-│   ├── Service Worker generation
-│   └── Manifest generation
-│
-└── Runtime (from layouts/PWA)
-    ├── UI Components
-    ├── Hooks
-    └── Context
-```
-
-**Benefits**:
-- One installation
-- Unified configuration
-- Shared types
-- Better integration
-
-### 2. PWA CLI Tool
-
-**Vision**: Command-line tool for PWA management
-
-```bash
-pnpm create @djangocfg/pwa
-# Interactive setup wizard
-
-pnpm pwa generate-vapid
-# Generate VAPID key pair
-
-pnpm pwa validate
-# Validate PWA configuration
-
-pnpm pwa test
-# Test PWA functionality locally
-
-pnpm pwa audit
-# Run Lighthouse PWA audit
-```
-
-### 3. PWA Dashboard
-
-**Vision**: Admin dashboard for PWA analytics
-
-```tsx
-import { PWADashboard } from '@djangocfg/pwa/admin';
-
-export default function AdminPage() {
-  return (
-    <PWADashboard
-      subscriptions={subscriptions}
-      installations={installations}
-      metrics={metrics}
-    />
-  );
-}
-```
-
-**Features**:
-- View active push subscriptions
-- Track install metrics
-- Test push notifications
-- Manage subscribers
-
----
-
-## Conclusion
-
-**layouts/PWA** and **nextjs/PWA** are **complementary**:
-
-- **nextjs/PWA**: Infrastructure (service worker, manifest)
-- **layouts/PWA**: User experience (install prompts, push notifications)
-
-**Recommendation**: **Use both together** for complete PWA solution
-
-**Next Steps**:
-1. Document integration pattern
-2. Create integration examples
-3. Consider unified package for future
-4. Share types between packages
-
-**Current State**: Both packages production-ready, work well together
-
-**Future**: Tighter integration possible, but not urgent