Implement a prefetch/preload hints policy: priority rules, mis‑hint detection, budget…
- User
Implement a prefetch/preload hints policy: priority rules, mis‑hint detection, budget guardrails, and AB validation.
Assistant
The user wants to implement a prefetch/preload hints policy. This policy needs to cover four specific areas:
- Priority Rules: How to decide what gets hinted and at what priority level?
- Mis-hint Detection: How to identify hints that are wrong, unhelpful, or harmful (e.g., 404s, resources never used, low cache hits).
- Budget Guardrails: Limiting the impact of prefetching on bandwidth, CPU, and cache storage.
- A/B Validation: How to test if the hints are actually improving performance metrics.
This is a complex engineering task involving browser hints (
rel=prefetch,rel=preload,rel=preconnect,rel=dns-prefetch, Early Hints 103), performance monitoring (RUM), and backend logic.Structure of the Response: I should structure this as a comprehensive technical design or implementation guide.
- High-Level Architecture: Briefly explain the components (Generator, Inserter, Enforcer, Monitor).
- Priority Rules: Define the logic for assigning importance.
- Mis-hint Detection: Define signals and mechanisms for flagging bad hints.
- Budget Guardrails: Define constraints (data, CPU, cache).
- A/B Validation: Define the experiment setup and metrics.
- Implementation Example (Code/Config): Provide pseudo-code or configuration examples.
Detailed Breakdown:
-
1. Priority Rules:
- Resource Types: CSS/Fonts are highest priority (Render blocking). Images/Low-priority scripts are lower.
- User Intent: Probability of click (for prefetching next pages). Viewport proximity (for images).
- Vitality: Core Web Vitals impact (LCP candidates).
-
2. Mis-hint Detection:
- The "Unused Preload" problem: Preloading something the browser didn't ask for.
- The "Wrong URL" problem: 404, 403, or redirects.
- The "Double Download" problem: Variations in cache keys.
- Mechanism: JavaScript
PerformanceObserverto watch for "unused" warnings or resource timing mismatches. Server-side logs comparing hint emission vs. request logs.
-
3. Budget Guardrails:
- Data Cap: Don't prefetch 50MB on a 3G connection.
- Concurrency: Browser limits (usually 6 per host), but we shouldn't starve main requests.
- Cache Eviction: Prefetch shouldn't push out current page resources.
- Logic: Check
navigator.connection.effectiveType(Network Information API).
-
4. A/B Validation:
- Hypothesis: Preloading the LCP image reduces LCP by .
- Groups: Control (no hints), Variant A (basic hints), Variant B (smart hints).
- Metrics: LCP, FID/INP, TTFB, and Wasted Bytes.
- Guardrail Metric: Bounce rate (if prefetching hurts UX by clogging bandwidth).
-
5. Code/Implementation Strategy:
- Use a "Hint Manager" class.
- Input: Analytics data, heuristic engine.
- Output: HTML headers or tags.
Refining the Content:
- Preload vs. Prefetch: Be clear on the distinction. Preload = current page necessity (high risk if wrong). Prefetch = future page probability (lower risk, but bandwidth cost).
- Early Hints (103): Mention HTTP/2 Push replacement.
Drafting the "Policy" (Mental Draft):
- Rule 1: Never preload scripts that aren't blocking.
- Rule 2: Only prefetch links with >80% click probability based on user segment.
- Rule 3: If Network API says "slow-2g", disable all prefetch. Limit preload to CSS/Font only.
- Detection: RUM script checks
performance.getEntriesByType("resource"). If entry.initiatorType is "link" but duration is huge or transferSize is 0 (cached) but we requested it... actually, unused preloads show up as warnings in console, but in RUM, you check if the resource was actually used shortly after load.
Constructing the Output: I will structure this into a Policy Document and an Engineering Implementation Guide.
- Part 1: Policy Logic (The Rules) - Priority queues, Network conditions.
- Part 2: Runtime Implementation (The Code) - JavaScript for detection and budgeting.
- Part 3: Validation (The Stats) - A/B testing setup.
Self-Correction during drafting: Initial thought: Just list rules. Correction: The user asked for "Mis-hint detection" and "Budget guardrails". This implies a system that actively monitors and self-corrects. I need to emphasize the feedback loop.
Let's flesh out the Mis-hint Detection specifically. How do we know a hint was bad?
- Unused Preload: The browser downloaded it, but the parser never requested it. Chrome generates a console warning. We can surface this to analytics.
- Cache Reuse: Did the prefetch actually save time? Compare TTFB of the requested resource vs. the prefetch start time.
- Resource Timing: Look for
transferSize. If 0, it was cached (good). If > 0, we paid a network cost.
Let's flesh out Budget Guardrails. Standard limits:
- 300KB total prefetch per page load on 4G.
- 0KB on 2G/3G or Save-Data mode.
Let's write the code. I'll use TypeScript/JavaScript interfaces to define the strict types and a "HintManager" class.
Final Polish: Make sure to distinguish between
<link rel="preload">(for current page) and<link rel="prefetch">(for next navigation), as the risk profiles are different.- Preload: High risk of wasted bandwidth if wrong (must be used within 3s usually).
- Prefetch: Lower critical risk, but higher bandwidth risk.
Okay, ready to generate the response. I will provide a comprehensive framework covering Policy Definition, Implementation Logic, and Validation Strategy. This implementation guide defines a robust Prefetch/Preload Policy Framework. This system is designed to maximize Core Web Vitals (CWV) by optimizing resource loading while actively preventing the "over-fetching" that wastes user bandwidth and degrades performance on slow networks.
1. Priority Rules (The Heuristics)
The policy distinguishes between Preload (current route, high confidence) and Prefetch (future route, low confidence).
A. The Pecking Order
We implement a strict priority queue. If a resource doesn't meet the criteria, it is downgraded or discarded.
-
Tier 1: Critical Preload (Current Navigation)
- Targets: Fonts, Critical CSS, LCP Image/Background.
- Condition: Resource is blocking the render or is the Largest Contentful Paint element.
- Action:
<link rel="preload" ... fetchpriority="high">
-
Tier 2: Probable Prefetch (High Intent)
- Targets: Next-page HTML (Deep linking), Cart, Checkout.
- Condition: User interaction signals (e.g., mouse hover > 200ms,
pointerdown) or high-probability business logic (e.g., "Next" button in wizard). - Action:
<link rel="prefetch" ... fetchpriority="low">
-
Tier 3: Speculative Prefetch (Low Intent)
- Targets: Links in footer, generic navigation.
- Condition: Viewport visibility (link is visible) and Idle time (
requestIdleCallback). - Action:
<link rel="prefetch" ... fetchpriority="lowest">(Note:lowestisn't a valid attribute value, standard islow, usually controlled via JS queueing).
B. Network Awareness
The policy checks
navigator.connection.effectiveTypebefore triggering Tier 2 or 3.- Slow 2G / 2G: Disable all Tier 3. Limit Tier 2 to absolute essentials.
- Save-Data Mode: Disable all Prefetch.
2. Budget Guardrails (The Constraints)
To prevent the "Tragedy of the Commons" (where too many hints clog the pipe), we implement a Budget Keeper.
A. Data Quotas
- View Quota: Max 500KB of prefetched data per page view.
- Cache Quota: Stop prefetching if the browser's Cache API is > 80% full.
B. Concurrency Limits
Browsers limit active connections per domain (usually 6). We must not saturate this.
- Active Queue: Never more than 1 active background prefetch at a time.
- Deprioritization: If the main thread is busy (Long Tasks > 50ms), pause the prefetch queue.
3. Mis-Hint Detection (The Feedback Loop)
We need to detect if our hints are actually helping or just wasting bytes.
A. Unused Resource Detection
Using the Performance Timeline API, we identify resources that were hinted but never used.
- Logic: Find entries with
initiatorType: 'link'(or specifically looking at the resource timing). - The Check: If
decodedBodySize > 0but no subsequent request for that resource occurred in the DOM within 5 seconds.
B. Cache Hit vs. Miss Ratio
We track if a prefetched resource is actually in the cache when the user navigates.
C. Performance Impact Analysis
Does the prefetch hurt the Current Page?
- Metric: Total Blocking Time (TBT).
- Logic: If TBT increases by > 10% on pages with aggressive prefetching vs. control group, the policy is too aggressive.
4. Implementation (The Code)
Here is a modular JavaScript implementation of the HintManager.
class HintManager { constructor() { this.config = { maxBytes: 500 * 1024, // 500KB Budget maxConcurrent: 1, minConnectionSpeed: '3g', // '4g', '3g', '2g', 'slow-2g' hoverDelayMs: 150, }; this.queue = []; this.activeRequests = 0; this.bytesSpent = 0; this.processedUrls = new Set(); this.setupObserver(); } // 1. Network Guardrail isNetworkViable() { const conn = navigator.connection || navigator.mozConnection || navigator.webkitConnection; if (!conn) return true; // Assume good if API missing if (conn.saveData) return false; const slowTypes = ['slow-2g', '2g']; if (slowTypes.includes(conn.effectiveType)) return false; return true; } // 2. Budget Check hasBudget(size = 0) { return (this.bytesSpent + size) < this.maxBytes; } // 3. Queue Management enqueue(url, priority = 'low', estimatedSize = 0) { if (this.processedUrls.has(url)) return; this.processedUrls.add(url); if (!this.isNetworkViable()) { console.log(`[HintManager] Network too slow, skipping: ${url}`); return; } if (!this.hasBudget(estimatedSize)) { console.log(`[HintManager] Budget exceeded, skipping: ${url}`); return; } // Add to priority queue (Simplified insertion sort) const item = { url, priority, estimatedSize }; if (priority === 'high') { this.queue.unshift(item); } else { this.queue.push(item); } this.processQueue(); } processQueue() { if (this.activeRequests >= this.config.maxConcurrent || this.queue.length === 0) return; const item = this.queue.shift(); // Preload vs Prefetch Logic const link = document.createElement('link'); link.rel = item.priority === 'critical' ? 'preload' : 'prefetch'; link.href = item.url; link.as = 'fetch'; // or 'script', 'style', 'image' // 4. Mis-Hint Detection (Listeners) link.onload = () => { this.activeRequests--; this.bytesSpent += item.estimatedSize; this.markUsage(item.url, true); // Track success this.processQueue(); // Next item }; link.onerror = () => { this.activeRequests--; this.reportMisHint(item.url, 'Network Error'); this.processQueue(); }; this.activeRequests++; document.head.appendChild(link); } // 5. Mis-Hint Analytics markUsage(url, preloaded) { // Logic to cross-reference later if resource was actually used // e.g., store in sessionStorage } reportMisHint(url, reason) { // Send to Analytics / A/B testing backend navigator.sendBeacon('/api/log-mishint', JSON.stringify({ url, reason })); } // Setup Interaction Listeners (Tier 2 Rules) setupObserver() { document.addEventListener('mouseover', (e) => { const target = e.target.closest('a'); if (target && target.href) { // Simple debounce via setTimeout setTimeout(() => { // Check if mouse is still over this.enqueue(target.href, 'low', 20000); }, this.config.hoverDelayMs); } }, { capture: true }); } } // Initialize const hintManager = new HintManager(); // Example: Critical Preload (Tier 1) // hintManager.enqueue('/fonts/roboto.woff2', 'critical', 24000);
5. A/B Validation Strategy
To scientifically validate the policy, we must run an experiment that measures Resultant Value, not just hit rate.
The Hypothesis
"Predictive prefetching reduces Page Load Time (PLT) by > 10% for the next navigation without significantly increasing Total Blocking Time (TBT) on the current page."
The Groups
- Control: No prefetching.
- Variant A (Conservative): Only Tier 1 (Preload) + Tier 2 (Hover only).
- Variant B (Aggressive): Tier 1 + Tier 2 + Tier 3 (Idle prefetching in viewport).
Metrics to Monitor
Metric Type Success Criteria LCP (Largest Contentful Paint) Result Decreases on next page navigation. TBT (Total Blocking Time) Guardrail Does not increase > 5% on current page. Prefetch Hit Rate Efficiency Cache Hits / Total Prefetches> 60%.Wasted Bytes Efficiency (Bytes prefetched but never used) < 10% of total prefetched bytes. Bounce Rate Business Should remain static or improve (bad prefetching can increase bounce rate on slow connections). Reporting Logic (Client-Side)
On the subsequent page load, check
performance.getEntriesByType('navigation').- Check
transferSize. If it is 0 (or very small for revalidation), the resource was served from cache (Hit). - Check
duration. Compare fetch time against non-cached fetch time to calculate Time Saved.
Implementation of the A/B Check
window.addEventListener('load', () => { const entries = performance.getEntriesByType('resource'); let wastedBytes = 0; entries.forEach(entry => { // If transferSize is 0, it came from cache. // If we prefetched it (check local storage flag), mark as win. if (entry.transferSize === 0 && isPrefetchedUrl(entry.name)) { trackMetric('PrefetchHit', entry.name); } }); });