Chunk load error | Unhandled Rejection

[tyler-dane]

Where did this happen?

Hosted (app.compasscalendar.com)

Expected Behavior

There is a smooth process for existing users to get the new version after it is published

Current Behavior

When an existing user revists compass and attempts to go to a page that has been newly code-split, they get this error. If they refresh, the chunk is loaded. However, it's not apparent to the user that this is the case.

Steps to Reproduce

No response

Possible Solution

Create a smooth version upgrade process that supports this use-case.

Create a way to track versions

When a user visit Compass, check if they have the latest version.

If not, add a subtle icon to bottom of the left sidebar. When clicking the icon or hovering, it should notify the user that there is a new update and encourage them to refresh the page to get the latest

Context

This'll help users feel confident that Compass won't break when trying the new stuff

[tyler-dane]

Version Check Implementation Suggestions

PR #1432 Review: Recommendations for replacing polling with event-driven version checking

Executive Summary

The current implementation polls /version.json every 60 seconds. This document proposes replacing constant polling with the Page Visibility API, which checks for updates only when users return to a previously hidden tab.

---

Current Implementation Analysis

What PR #1432 Does Today

Component	Behavior
useVersionCheck.ts	Polls /version.json every 60 seconds
useChunkLoadErrorHandler.ts	Catches chunk load errors, auto-reloads page
version.json	Generated at build time with unique version hash
UI	Shows download icon in sidebar when update available

Problems with Polling

1. Wasteful network requests — ~60 requests/hour regardless of user activity
2. Misaligned with user behavior — Checks while user is actively using the page (when they don't need updates)
3. Battery drain — Continuous polling impacts mobile device battery life
4. Unnecessary CPU wake-ups — Prevents browser from fully optimizing background tabs

---

Recommended Approach: Page Visibility API

Why Visibility-Based Checking is Better

Aspect	Polling (Current)	Visibility-Based (Proposed)
Network requests	~60/hour	~12/hour + on-demand
Checks when user is active	Yes (wasteful)	No
Checks when user returns	Every 60s at most	Immediately
Battery impact	Higher	Minimal
Browser support	N/A	Since July 2015 (all browsers)

How It Works

User opens app → Initial version check
        ↓
User switches to another tab
        ↓
Tab is hidden (record timestamp)
        ↓
User returns after 30+ seconds
        ↓
Tab becomes visible → Check version
        ↓
If new version → Show update icon

---

Implementation Details

Configuration Constants

// Only check if the tab was hidden for longer than this threshold
// Prevents unnecessary checks for brief tab switches (checking email, etc.)
const MIN_HIDDEN_DURATION_MS = 30_000; // 30 seconds

// Backup poll interval - safety net for very long sessions
// Much less frequent than current 60-second polling
const BACKUP_CHECK_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes

Core Logic

import { useCallback, useEffect, useRef, useState } from "react";

export const useVersionCheck = (): VersionCheckResult => {
  const [isUpdateAvailable, setIsUpdateAvailable] = useState(false);

  // Track when the tab was hidden (using ref to avoid re-renders)
  const hiddenAtRef = useRef<number | null>(null);

  // Prevent concurrent version checks
  const isCheckingRef = useRef(false);

  const checkVersion = useCallback(async () => {
    // Guard against concurrent requests
    if (isCheckingRef.current) return;

    try {
      isCheckingRef.current = true;

      const response = await fetch(`/version.json?t=${Date.now()}`, {
        cache: "no-store",
        headers: { "Cache-Control": "no-cache" },
      });

      if (response.ok) {
        const { version: serverVersion } = await response.json();
        if (serverVersion && serverVersion !== CURRENT_VERSION) {
          setIsUpdateAvailable(true);
        }
      }
    } catch (error) {
      console.debug("Version check failed:", error);
    } finally {
      isCheckingRef.current = false;
    }
  }, []);

  useEffect(() => {
    if (IS_DEV) return;

    const handleVisibilityChange = () => {
      if (document.visibilityState === "hidden") {
        // Record when the tab became hidden
        hiddenAtRef.current = Date.now();
      } else if (document.visibilityState === "visible") {
        // Tab became visible - check if we should verify version
        const hiddenAt = hiddenAtRef.current;
        hiddenAtRef.current = null;

        if (hiddenAt !== null) {
          const hiddenDuration = Date.now() - hiddenAt;

          // Only check if hidden long enough to warrant a version check
          if (hiddenDuration >= MIN_HIDDEN_DURATION_MS) {
            checkVersion();
          }
        }
      }
    };

    // Check once on initial mount
    checkVersion();

    // Listen for visibility changes (primary mechanism)
    document.addEventListener("visibilitychange", handleVisibilityChange);

    // Backup poll for very long sessions (safety net)
    const backupInterval = setInterval(checkVersion, BACKUP_CHECK_INTERVAL_MS);

    return () => {
      document.removeEventListener("visibilitychange", handleVisibilityChange);
      clearInterval(backupInterval);
    };
  }, [checkVersion]);

  return { isUpdateAvailable, currentVersion: CURRENT_VERSION };
};

---

Design Decisions Explained

Why 30-Second Threshold?

Users frequently switch tabs briefly (checking email, Slack, etc.). Without a threshold:

• Switching to check a notification would trigger a version check
• Rapid tab switching would cause multiple requests
• The UX benefit is minimal for brief switches

30 seconds is long enough that if you've been away that long, checking for updates makes sense.

Why Keep a Backup Poll?

Edge cases where visibility-only checking could fail:

• User keeps the same tab open for hours without switching
• Browser bugs with visibility events (rare but documented)
• Extensions or iframes interfering with visibility detection

The 5-minute backup ensures updates are eventually detected while being 5x less frequent than current polling.

Why Use useRef Instead of useState?

// Using ref (recommended)
const hiddenAtRef = useRef<number | null>(null);

// vs. using state (not recommended)
const [hiddenAt, setHiddenAt] = useState<number | null>(null);

Refs are better here because:

1. No re-renders — Storing a timestamp shouldn't trigger component updates
2. No stale closures — Event handlers always see current ref value
3. Performance — Avoids unnecessary React reconciliation

Why Prevent Concurrent Checks?

if (isCheckingRef.current) return;

Without this guard:

• Visibility change and backup poll could fire simultaneously
• Multiple in-flight requests to the same endpoint
• Potential race conditions in state updates

---

Test Scenarios

Unit Tests to Add

describe("useVersionCheck", () => {
  describe("visibility change behavior", () => {
    it("should check version when tab becomes visible after >30s hidden", () => {
      // 1. Render hook
      // 2. Simulate tab hidden
      // 3. Advance timers by 31 seconds
      // 4. Simulate tab visible
      // 5. Assert fetch was called
    });

    it("should NOT check when tab becomes visible after <30s hidden", () => {
      // 1. Render hook
      // 2. Simulate tab hidden
      // 3. Advance timers by 10 seconds
      // 4. Simulate tab visible
      // 5. Assert fetch was NOT called
    });

    it("should clean up event listener on unmount", () => {
      // Assert removeEventListener called with "visibilitychange"
    });
  });

  describe("backup polling", () => {
    it("should check version every 5 minutes as backup", () => {
      // Advance timers by 5 minutes, assert fetch called
    });
  });

  describe("concurrent check prevention", () => {
    it("should not make concurrent fetch requests", () => {
      // Start a fetch that doesn't resolve
      // Trigger another check
      // Assert only one fetch in flight
    });
  });
});

Manual Testing Checklist

• Build production version (npm run build)
• Open app, switch to another tab for <30s, return → No network request
• Switch to another tab for >30s, return → Version check fires
• Leave tab open for 5+ minutes → Backup poll fires
• Modify version.json manually → Update icon appears after check
• Click update icon → Page reloads

---

Files to Modify

File	Changes
packages/web/src/common/hooks/useVersionCheck.ts	Replace polling with visibility-based checking
packages/web/src/common/hooks/useVersionCheck.test.ts	Add visibility and backup poll tests

Files That Need No Changes

• useChunkLoadErrorHandler.ts — Remains as safety net for actual chunk errors
• SidebarIconRow.tsx — Same hook API, no changes needed
• App.tsx — No changes needed
• webpack.config.mjs — Version generation stays the same

---

Browser Compatibility

The Page Visibility API is a Baseline web feature, available across all browsers since July 2015.

Browser	Support
Chrome	33+
Firefox	18+
Safari	7+
Edge	12+
Mobile browsers	Full support

No polyfills or vendor prefixes required.

---

How Version Numbers Work (Build-Time Generation)

PR #1432 adds automatic version generation to webpack. Here's how it works:

The Mechanism

// In webpack.config.mjs (added by PR #1432)

// 1. Generate a unique version at build time
const BUILD_VERSION = IS_DEV
  ? "dev"
  : `${Date.now()}-${Math.random().toString(36).substring(7)}`;
// Example output: "1706918400000-x7k2m9"

// 2. Inject into the app via DefinePlugin
new webpack.DefinePlugin({
  "process.env": envObject,
  BUILD_VERSION: JSON.stringify(BUILD_VERSION),  // Available as global constant
});

// 3. Generate version.json file (production only)
compiler.hooks.emit.tapAsync("GenerateVersionPlugin", (compilation, callback) => {
  const versionContent = JSON.stringify({ version: BUILD_VERSION }, null, 2);
  compilation.assets["version.json"] = {
    source: () => versionContent,
    size: () => versionContent.length,
  };
  callback();
});

Why This Works Automatically

Aspect	How It's Handled
Unique per build	Date.now() ensures every build has a different timestamp
Collision-proof	Random suffix (Math.random()) adds extra uniqueness
No manual versioning	No need to bump version numbers in package.json
Build artifact	version.json is generated alongside other build outputs
Development mode	Uses "dev" string, skips version checking entirely

The Flow

┌─────────────────────────────────────────────────────────────────┐
│                        BUILD TIME                               │
├─────────────────────────────────────────────────────────────────┤
│  npm run build                                                  │
│       ↓                                                         │
│  Webpack generates BUILD_VERSION = "1706918400000-x7k2m9"       │
│       ↓                                                         │
│  DefinePlugin injects BUILD_VERSION into app bundle             │
│       ↓                                                         │
│  Custom plugin writes version.json to build output              │
│       ↓                                                         │
│  Deploy build/ folder to server                                 │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                        RUNTIME                                  │
├─────────────────────────────────────────────────────────────────┤
│  User loads app → BUILD_VERSION = "1706918400000-x7k2m9"        │
│       ↓                                                         │
│  Later: New deployment with BUILD_VERSION = "1706920000000-abc" │
│       ↓                                                         │
│  User's app fetches /version.json → { version: "170692..." }    │
│       ↓                                                         │
│  Versions don't match → Show update icon                        │
└─────────────────────────────────────────────────────────────────┘

TypeScript Declaration

PR #1432 also adds the type declaration:

// In packages/web/declaration.d.ts
declare const BUILD_VERSION: string;

This allows TypeScript to recognize BUILD_VERSION as a valid global constant.

No Additional Work Needed

The version mechanism in PR #1432 is fully automatic:

• ✅ Version updates on every build (timestamp-based)
• ✅ No manual version bumping required
• ✅ Works with any CI/CD pipeline
• ✅ version.json is part of build output
• ✅ Development mode is handled (uses "dev", skips checks)

Deployment Considerations

For the version check to work correctly:

1. Serve version.json with no-cache headers — Your CDN/server should not cache this file aggressively, or use the cache-busting query param (?t=timestamp) that the hook adds.

2. Keep the file at the root — The hook fetches /version.json, so it should be accessible at that path.

3. No need to keep old versions — Unlike chunk files (where keeping old chunks helps), version.json only needs the current version.

---

References

• Page Visibility API - MDN
• Using the Page Visibility API - web.dev
• Document: visibilitychange event - MDN
• ChunkLoadError handling - Rollbar

---

Summary

Metric	Before	After
Network requests/hour	~60	~12 + on-demand
Checks while user active	Yes	No
Immediate check on return	No (up to 60s delay)	Yes
Battery impact	Higher	Minimal
Code complexity	Simple	Slightly more complex
Reliability	Good	Better (event-driven + backup)

The visibility-based approach is more efficient, more responsive, and aligns with how users actually interact with web applications.

[tyler-dane]

Handling 404/Missing Chunks:

Even with a prompt, a user might try to navigate before the poll happens. Add a global event listener to catch ChunkLoadErrors and show the same prompt.