vite-plugin-smart-prefetch 0.1.0

package/README.md

@@ -0,0 +1,605 @@
+# @farmart/vite-plugin-smart-prefetch
+
+**Smart prefetch plugin for Vite applications powered by BigQuery GA4 analytics**
+
+Automatically prefetch route chunks based on real user navigation patterns from BigQuery GA4 export. Improve perceived performance by up to 80-90% for predicted route transitions.
+
+## Features
+
+- 🤖 **Smart Learning** - Analyzes BigQuery GA4 event data to learn user navigation patterns
+- 📊 **Data-Driven** - Prefetch decisions based on actual user behavior, not assumptions
+- ⚡ **Multiple Strategies** - Auto, hover, visible, idle, or hybrid prefetching
+- 🌐 **Network-Aware** - Respects data-saver mode and connection quality
+- 💾 **Smart Caching** - Caches computed models with TTL for efficiency
+- 🎯 **Framework Support** - React (Vue and Svelte coming soon)
+- 🔧 **Zero Config** - Works out of the box with sensible defaults
+- 📈 **Environment-Specific** - Different models for production, staging, development
+
+---
+
+## Installation
+
+```bash
+# Using pnpm (recommended for monorepos)
+pnpm add @farmart/vite-plugin-smart-prefetch
+
+# Using npm
+npm install @farmart/vite-plugin-smart-prefetch
+
+# Using yarn
+yarn add @farmart/vite-plugin-smart-prefetch
+```
+
+---
+
+## Quick Start
+
+### 1. Setup BigQuery for GA4 Export
+
+```bash
+# 1. Enable BigQuery export from GA4 Console
+# GA4 Admin > Data Export > BigQuery
+
+# 2. Create Google Cloud service account
+# https://console.cloud.google.com/iam-admin/serviceaccounts
+
+# 3. Grant "BigQuery Data Viewer" and "BigQuery Job User" roles
+
+# 4. Create and download JSON key
+# Service Accounts > Keys > Add Key > Create New Key > JSON
+
+# 5. Add to environment variables
+```
+
+`.env`:
+```bash
+VITE_GA_PROPERTY_ID=123456789
+VITE_GA_CLIENT_EMAIL=prefetch@your-project.iam.gserviceaccount.com
+VITE_GA_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
+```
+
+### 2. Configure Vite Plugin
+
+`vite.config.mts`:
+```typescript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { smartPrefetch } from '@farmart/vite-plugin-smart-prefetch';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    smartPrefetch({
+      framework: 'react',
+      strategy: 'hybrid',
+      analytics: {
+        provider: 'google-analytics',
+        credentials: {
+          propertyId: process.env.VITE_GA_PROPERTY_ID!,
+          clientEmail: process.env.VITE_GA_CLIENT_EMAIL!,
+          privateKey: process.env.VITE_GA_PRIVATE_KEY!,
+        },
+        dataRange: {
+          days: 30,           // Analyze last 30 days
+          minSessions: 100,   // Minimum sessions threshold
+        },
+        model: {
+          type: 'probability',
+          threshold: 0.3,     // 30% probability threshold
+          maxPrefetch: 3,     // Max 3 routes per page
+        },
+        environment: process.env.NODE_ENV || 'production',
+      },
+      manualRules: {
+        // Optional: Override ML predictions
+        '/checkout': ['/payment'],
+      },
+      cache: {
+        enabled: true,
+        ttl: 24 * 60 * 60 * 1000, // 24 hours
+      },
+    }),
+  ],
+});
+```
+
+### 3. Add to Your App
+
+`App.tsx`:
+```typescript
+import { usePrefetch } from '@farmart/vite-plugin-smart-prefetch/react';
+
+function App() {
+  // That's it! Plugin handles everything
+  usePrefetch();
+
+  return (
+    <Routes>
+      <Route path="/" element={<Home />} />
+      <Route path="/orders" element={<Orders />} />
+      <Route path="/dispatch-order" element={<DispatchOrder />} />
+    </Routes>
+  );
+}
+```
+
+### 4. Build & Deploy
+
+```bash
+npm run build
+```
+
+The plugin will:
+1. ✅ Connect to Google Analytics
+2. ✅ Fetch navigation data
+3. ✅ Train probability model
+4. ✅ Generate `prefetch-config.json`
+5. ✅ Cache model for future builds
+
+---
+
+## Configuration
+
+### Plugin Options
+
+```typescript
+interface PluginOptions {
+  /** Framework (default: 'react') */
+  framework?: 'react' | 'vue' | 'svelte';
+
+  /** Prefetch strategy (default: 'hybrid') */
+  strategy?: 'auto' | 'hover' | 'visible' | 'idle' | 'hybrid';
+
+  /** Google Analytics integration */
+  analytics?: AnalyticsConfig;
+
+  /** Manual prefetch rules */
+  manualRules?: {
+    [sourceRoute: string]: string[];
+  };
+
+  /** Cache configuration */
+  cache?: {
+    enabled?: boolean;
+    ttl?: number;
+    path?: string;
+  };
+
+  /** Advanced options */
+  advanced?: {
+    debug?: boolean;
+    excludeRoutes?: string[];
+  };
+}
+```
+
+### Prefetch Strategies
+
+| Strategy | Description | Use Case |
+|----------|-------------|----------|
+| `auto` | Prefetch immediately on route change | High-confidence predictions |
+| `hover` | Prefetch when user hovers over link | User intent signals |
+| `visible` | Prefetch when link becomes visible | Below-the-fold content |
+| `idle` | Prefetch during browser idle time | Low priority routes |
+| **`hybrid`** | **Smart combination based on probability** | **Recommended** |
+
+#### Hybrid Strategy (Recommended)
+
+- **High priority** (>70% probability): Prefetch immediately
+- **Medium priority** (40-70%): Prefetch on idle
+- **Low priority** (30-40%): Prefetch on hover/visible
+
+---
+
+## React Integration
+
+### usePrefetch Hook
+
+```typescript
+import { usePrefetch } from '@farmart/vite-plugin-smart-prefetch/react';
+
+function App() {
+  // Automatically prefetches routes based on navigation
+  usePrefetch();
+
+  return <Routes>...</Routes>;
+}
+```
+
+### PrefetchLink Component
+
+Enhanced `Link` component with manual control:
+
+```tsx
+import { PrefetchLink } from '@farmart/vite-plugin-smart-prefetch/react';
+
+// Prefetch on hover
+<PrefetchLink to="/orders" prefetch="hover">
+  View Orders
+</PrefetchLink>
+
+// Prefetch when visible (great for lists)
+<PrefetchLink to="/dispatch-order" prefetch="visible">
+  Create Dispatch
+</PrefetchLink>
+
+// Manual control (no automatic prefetch)
+<PrefetchLink to="/settings" prefetch="manual">
+  Settings
+</PrefetchLink>
+```
+
+### Manual Prefetch Control
+
+```typescript
+import { getPrefetchManager } from '@farmart/vite-plugin-smart-prefetch/react';
+
+function MyComponent() {
+  const handleMouseEnter = () => {
+    const manager = getPrefetchManager();
+    manager?.prefetchRoute('/orders');
+  };
+
+  return (
+    <button onMouseEnter={handleMouseEnter}>
+      View Orders
+    </button>
+  );
+}
+```
+
+---
+
+## How It Works
+
+### Build Time
+
+```
+1. Connect to Google Analytics
+   ├── Authenticate with service account
+   └── Fetch last 30 days of navigation data
+
+2. Train Model
+   ├── Calculate transition probabilities
+   │   Example: P(/dispatch-order | /orders) = 0.58
+   ├── Apply threshold filter (>30%)
+   └── Select top 3 predictions per route
+
+3. Generate Configuration
+   ├── Map routes to Vite chunks
+   │   /dispatch-order → assets/dispatch-order-abc123.js
+   └── Emit prefetch-config.json
+
+4. Cache Model
+   ├── Save to node_modules/.cache/smart-prefetch/
+   └── TTL: 24 hours (configurable)
+```
+
+### Runtime
+
+```
+1. App Loads
+   ├── usePrefetch() initializes
+   └── Fetch /prefetch-config.json
+
+2. User on /orders page
+   ├── Check network conditions (Data Saver, 2G, etc.)
+   ├── Read predictions: [/dispatch-order (58%), /orders/:id (42%)]
+   └── Apply strategy:
+       - High priority: Prefetch immediately
+       - Medium: Prefetch on idle
+       - Low: Wait for hover/visible
+
+3. Inject <link rel="prefetch">
+   <link rel="prefetch" href="/assets/dispatch-order-abc123.js">
+
+4. User clicks "Dispatch Order"
+   ├── Chunk already in browser cache!
+   └── Load time: ~10ms instead of ~300ms
+```
+
+---
+
+## Performance Impact
+
+### Before vs After
+
+| Metric | Without Prefetch | With Prefetch | Improvement |
+|--------|------------------|---------------|-------------|
+| Route transition | 250-500ms | 10-50ms | **80-90% faster** |
+| Cache hit rate | 0% | 60-80% | **New capability** |
+| Time to Interactive | Baseline | -15-20% | **Faster** |
+
+### Real-World Example
+
+```
+Example: /orders → /dispatch-order (58% probability)
+
+Without prefetch:
+  1. User clicks link
+  2. Download dispatch-order-abc123.js (300ms)
+  3. Parse and execute (50ms)
+  Total: 350ms
+
+With prefetch:
+  1. User lands on /orders
+  2. Plugin prefetches dispatch-order-abc123.js in background
+  3. User clicks link
+  4. Load from cache (5ms)
+  5. Parse and execute (50ms)
+  Total: 55ms (84% faster!)
+```
+
+---
+
+## Network-Aware Prefetching
+
+The plugin automatically detects and respects:
+
+- ✅ **Data Saver mode** - No prefetch if enabled
+- ✅ **Slow connections** - No prefetch on 2G/slow-2G
+- ✅ **Metered connections** - Conservative prefetch on cellular
+- ✅ **Connection quality** - Uses Network Information API
+
+```typescript
+// Automatic detection (no configuration needed)
+if (navigator.connection.saveData) {
+  // Skip prefetch
+}
+
+if (connection.effectiveType === '2g') {
+  // Skip prefetch
+}
+```
+
+---
+
+## Cache Management
+
+### Cache Location
+
+```
+node_modules/.cache/smart-prefetch/
+├── model-production.json    # Production model
+├── model-staging.json        # Staging model
+└── metadata.json             # Cache metadata
+```
+
+### Invalidate Cache
+
+```bash
+# Invalidate all cache
+rm -rf node_modules/.cache/smart-prefetch
+
+# Or programmatically
+const cacheManager = new CacheManager();
+await cacheManager.invalidate();
+```
+
+### Cache Stats
+
+```typescript
+const stats = cacheManager.getStats();
+// {
+//   enabled: true,
+//   cacheDir: './node_modules/.cache/smart-prefetch',
+//   ttl: 86400000,
+//   cachedEnvironments: ['production', 'staging'],
+//   totalSize: 45678
+// }
+```
+
+---
+
+## Manual Rules
+
+Override ML predictions with manual rules:
+
+```typescript
+smartPrefetch({
+  manualRules: {
+    // Always prefetch payment on checkout
+    '/checkout': ['/payment'],
+
+    // Multiple targets
+    '/': ['/products', '/orders', '/dashboard'],
+
+    // Dynamic routes (use :id notation)
+    '/orders/:id': ['/dispatch-order/:id'],
+  },
+})
+```
+
+Manual rules:
+- ✅ Take precedence over ML predictions
+- ✅ Always have `priority: 'high'`
+- ✅ Always have `probability: 1.0`
+- ✅ Merged with analytics data
+
+---
+
+## Debugging
+
+Enable debug mode to see detailed logs:
+
+```typescript
+smartPrefetch({
+  advanced: {
+    debug: true,
+  },
+})
+```
+
+### Build-Time Logs
+
+```
+🚀 Smart Prefetch Plugin Initialized
+   Framework: react
+   Strategy: hybrid
+   Analytics: enabled
+
+📊 Fetching analytics data...
+   Date range: Last 30 days
+   Min sessions threshold: 100
+
+✅ Fetched 87 navigation patterns
+
+🤖 Training prefetch model...
+   Model type: probability
+   Threshold: 30%
+   Max prefetch per route: 3
+
+✅ Model trained successfully
+   Routes with predictions: 42
+
+📦 Generating prefetch configuration...
+   Manifest entries: 156
+   Mapped chunks: 89
+```
+
+### Runtime Logs
+
+```
+🚀 Prefetch Manager Initialized
+   Strategy: hybrid
+   Routes: 42
+   Environment: production
+
+📦 Prefetching for route: /orders
+   Targets: 2
+   ✅ Prefetched: /dispatch-order (58%, high)
+   ✅ Prefetched: /orders/:id (42%, medium)
+```
+
+---
+
+## Troubleshooting
+
+### Issue: "Failed to load prefetch config"
+
+**Solution:** Ensure `/prefetch-config.json` is in your build output (`dist/`).
+
+```bash
+# Check if file exists
+ls dist/prefetch-config.json
+```
+
+### Issue: "Google Analytics connection test failed"
+
+**Solutions:**
+1. Verify service account has "Viewer" access to GA4 property
+2. Check credentials in `.env` file
+3. Ensure private key has correct newlines (`\n`)
+
+```bash
+# Test credentials
+echo $VITE_GA_PRIVATE_KEY | grep "BEGIN PRIVATE KEY"
+```
+
+### Issue: "No navigation data found"
+
+**Solutions:**
+1. Ensure GA4 property has at least 30 days of data
+2. Lower `minSessions` threshold
+3. Check GA4 property ID is correct
+
+### Issue: "No chunk found for route"
+
+**Solution:** Adjust route normalization or use manual rules:
+
+```typescript
+smartPrefetch({
+  manualRules: {
+    '/my-route': ['/target-route'],
+  },
+  advanced: {
+    routeNormalization: (path) => {
+      // Custom normalization logic
+      return path.replace(/\/[0-9]+/g, '/:id');
+    },
+  },
+})
+```
+
+---
+
+## Best Practices
+
+### 1. Use Hybrid Strategy
+
+```typescript
+strategy: 'hybrid'  // ✅ Recommended
+```
+
+Automatically prioritizes prefetch based on prediction confidence.
+
+### 2. Set Appropriate Thresholds
+
+```typescript
+model: {
+  threshold: 0.3,      // 30% - Good balance
+  maxPrefetch: 3,      // Limit bandwidth usage
+}
+```
+
+- **Too low** (<20%): Wastes bandwidth
+- **Too high** (>50%): Misses opportunities
+
+### 3. Use Manual Rules for Critical Paths
+
+```typescript
+manualRules: {
+  '/checkout': ['/payment'],  // Always prefetch payment
+}
+```
+
+### 4. Monitor Prefetch Performance
+
+Enable dashboard to visualize predictions:
+
+```typescript
+analytics: {
+  dashboard: true,  // Generates prefetch-report.html
+}
+```
+
+Access at: `https://your-app.com/prefetch-report.html`
+
+### 5. Environment-Specific Models
+
+```typescript
+// Production
+environment: 'production'
+
+// Staging
+environment: 'staging'
+```
+
+Keeps models separate for different user behaviors.
+
+---
+
+## API Reference
+
+See [RFC-001-SMART-PREFETCH-PLUGIN.md](../../RFC-001-SMART-PREFETCH-PLUGIN.md) for detailed API documentation.
+
+---
+
+## Contributing
+
+This is an internal FarmArt Engineering package. For issues or feature requests, please contact the engineering team.
+
+---
+
+## License
+
+MIT © FarmArt Engineering
+
+---
+
+## Support
+
+For questions or support:
+- Internal Slack: `#engineering`
+- Documentation: See RFC-001 in project root
+- Issues: Create ticket in project management tool