caddis-plugin: Instructions file for GitHub Copilot

Frontend Development Instructions

Guidelines for building consistent, accessible, and visually appealing user interfaces.

SPA Chunk Resilience (React/Vite)

When using route-level code splitting (import() / React.lazy), implement one-time stale-chunk recovery:

1. Wrap lazy imports with retry logic for transient failures.
2. On exhausted retries, detect chunk-load errors (Failed to fetch dynamically imported module, ChunkLoadError).
3. Trigger exactly one automatic reload per chunk key via sessionStorage.
4. If reload still fails, show a user-facing fallback with retry button.

const CHUNK_RELOAD_KEY_PREFIX = "app:chunk-reload:";

function tryOneTimeChunkReload(error: unknown): boolean {
    const message = error instanceof Error ? error.message : String(error ?? "");
    const isChunkError = /Failed to fetch dynamically imported module|ChunkLoadError|Loading chunk/i.test(message);
    if (!isChunkError) return false;

    const chunkLike = message.match(/[A-Za-z0-9_-]+\.[cm]?js/i)?.[0] ?? "unknown";
    const key = `${CHUNK_RELOAD_KEY_PREFIX}${chunkLike}`;
    if (sessionStorage.getItem(key) === "1") return false;

    sessionStorage.setItem(key, "1");
    window.location.reload();
    return true;
}

This pattern prevents users from getting stuck on stale chunk hashes after deployments while avoiding infinite reload loops.

Proactive Version Detection (Long-Lived Sessions)

Reactive chunk recovery (above) handles errors after they happen. For long-lived sessions — dashboards left open for days by executives — add proactive version detection so the browser reloads before stale chunks are requested.

Why Not Service Workers?

Service workers are the FAANG standard (Gmail, Twitter/X, YouTube). However, they require HTTPS. Intranet apps served over plain HTTP (common with IIS on internal hostnames) cannot register a service worker. If your prod server has HTTPS, prefer vite-plugin-pwa (Workbox). Otherwise, use the 3-layer polling approach below.