Feature Summary
Describe the issue
Users frequently encounter blank screens, unauthorized errors, or entirely broken application states when interacting with Texera shortly after a new frontend deployment.
Because modern browsers aggressively cache static assets, a user whose session bridges across a deployment will retain an outdated index.html referencing older JavaScript chunks. When the client dynamically requests these older, cached files (e.g., during a route change or lazy loading) that no longer exist on the server, it results in silent failures or 404s, ultimately causing the UI to crash. This requires significant engineering overhead to investigate, only to find that the root cause is a stale browser cache.
Impact
- User Experience: Disruptive workflow interruptions and perceived platform instability.
- Engineering Velocity: Wasted time investigating false-positive bug reports stemming purely from cache mismatch.
Expected behavior
The client should seamlessly detect when a new deployment has occurred and handle the transition gracefully. Users should either be prompted to refresh or the application should safely auto-reload to fetch the latest assets without crashing.
Proposed Solution or Design
Industry Standards & Proposed Solutions
Based on standard patterns used by major Single Page Applications (SPAs), we should evaluate and implement a combination of the following strategies:
1. Strict Cache-Control for the Entry Point (The Baseline)
Bundlers (like Webpack or Vite) already use content hashing for JS/CSS files (e.g., main.[hash].js), which are safe to cache long-term. However, the root index.html must never be cached.
- Implementation: Configure the web server, Ingress controller, or CDN to serve
index.html with the header: Cache-Control: no-cache, no-store, must-revalidate. This ensures the browser always fetches the latest pointers to the new chunk hashes.
2. Dynamic ChunkLoad Error Boundaries
When a user has an old SPA loaded and navigates to a new route, the app attempts to fetch an old chunk that was wiped during the deployment.
- Implementation: Wrap the application in a global Error Boundary that specifically intercepts dynamic import failures (e.g.,
ChunkLoadError). When caught, execute a hard refresh via window.location.reload(true) to force the browser to pull the new index.html.
3. Version Polling (version.json strategy)
A proactive approach to inform active users of a new deployment before they encounter an error.
- Implementation: Inject a
version.json file during the CI/CD pipeline. The frontend periodically polls this lightweight file (e.g., every few minutes or on background/foreground focus transitions). If the fetched version differs from the currently loaded version, trigger a non-intrusive toast notification: "A new version of Texera is available. Please [Refresh] to update."
4. Service Worker Lifecycle Hooks
If the frontend utilizes a Service Worker for offline capabilities or caching, the update lifecycle can be managed natively.
- Implementation: Use the
onUpdateFound event to detect byte-differences in the deployed service worker. This allows the app to prompt the user to reload, clearing the old cache storage safely.
Affected Area
No response
Feature Summary
Describe the issue
Users frequently encounter blank screens, unauthorized errors, or entirely broken application states when interacting with Texera shortly after a new frontend deployment.
Because modern browsers aggressively cache static assets, a user whose session bridges across a deployment will retain an outdated
index.htmlreferencing older JavaScript chunks. When the client dynamically requests these older, cached files (e.g., during a route change or lazy loading) that no longer exist on the server, it results in silent failures or 404s, ultimately causing the UI to crash. This requires significant engineering overhead to investigate, only to find that the root cause is a stale browser cache.Impact
Expected behavior
The client should seamlessly detect when a new deployment has occurred and handle the transition gracefully. Users should either be prompted to refresh or the application should safely auto-reload to fetch the latest assets without crashing.
Proposed Solution or Design
Industry Standards & Proposed Solutions
Based on standard patterns used by major Single Page Applications (SPAs), we should evaluate and implement a combination of the following strategies:
1. Strict Cache-Control for the Entry Point (The Baseline)
Bundlers (like Webpack or Vite) already use content hashing for JS/CSS files (e.g.,
main.[hash].js), which are safe to cache long-term. However, the rootindex.htmlmust never be cached.index.htmlwith the header:Cache-Control: no-cache, no-store, must-revalidate. This ensures the browser always fetches the latest pointers to the new chunk hashes.2. Dynamic ChunkLoad Error Boundaries
When a user has an old SPA loaded and navigates to a new route, the app attempts to fetch an old chunk that was wiped during the deployment.
ChunkLoadError). When caught, execute a hard refresh viawindow.location.reload(true)to force the browser to pull the newindex.html.3. Version Polling (
version.jsonstrategy)A proactive approach to inform active users of a new deployment before they encounter an error.
version.jsonfile during the CI/CD pipeline. The frontend periodically polls this lightweight file (e.g., every few minutes or on background/foreground focus transitions). If the fetched version differs from the currently loaded version, trigger a non-intrusive toast notification: "A new version of Texera is available. Please [Refresh] to update."4. Service Worker Lifecycle Hooks
If the frontend utilizes a Service Worker for offline capabilities or caching, the update lifecycle can be managed natively.
onUpdateFoundevent to detect byte-differences in the deployed service worker. This allows the app to prompt the user to reload, clearing the old cache storage safely.Affected Area
No response