fix: graceful WebGL fallback for Firefox/Linux blank page#1
Open
fix: graceful WebGL fallback for Firefox/Linux blank page#1
Conversation
…hen WebGL unavailable
Both landing-map.web.tsx and map-view.web.tsx called `new mapboxgl.Map()`
inside useEffect with no try/catch and no mapboxgl.supported() check.
On Firefox/Linux with missing or incompatible GPU drivers, the Map constructor
throws "Failed to initialize WebGL", which propagates as an uncaught error
and crashes the React app before it can mount — resulting in a completely
blank page.
Fix:
- Check mapboxgl.supported({ failIfMajorPerformanceCaveat: false }) before
constructing the map; set error/webglUnavailable state if false
- Wrap `new mapboxgl.Map()` in try/catch as a second safety net
- Show a graceful fallback UI with a user-friendly message instead of crashing
- Add map.webglUnavailable i18n key in en.json and es.json
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
When WebGL fails, both the landing map and main map now show a Mapbox Static Images API tile of Tijuana instead of a blank placeholder, with a semi-transparent banner explaining WebGL is unavailable and a link to get.webgl.org/troubleshooting/ for browser-specific help. - landing-map: static 800x400 image + bottom banner + troubleshoot link - map-view: static 1280x720 image + centered overlay banner + link - i18n: split webglUnavailable into short description + webglTroubleshoot link key; Spanish version notes the link is in English Static Images API: 50k free requests/month; URL is deterministic so browser/CDN cache handles repeat views at no cost. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
On Firefox/Linux (e.g. Fedora) with missing or incompatible GPU drivers, the site rendered a completely blank page. The browser console showed:
Both
landing-map.web.tsxandmap-view.web.tsxcallednew mapboxgl.Map()insideuseEffectwith nomapboxgl.supported()check and no try/catch. When WebGL initialization fails, the Map constructor throws an uncaught error that crashes the entire React app before it can mount.Fix
mapboxgl.supported({ failIfMajorPerformanceCaveat: false })before constructing the map instance; set error state if WebGL is unavailablenew mapboxgl.Map()intry/catchas a secondary safety netmap.webglUnavailable) instead of crashingmapRef.current?.remove()(safer, consistent)map.webglUnavailablei18n key inen.jsonandes.jsonTest plan
about:config→webgl.disabled = true): confirm the map section shows the fallback message instead of a blank page🤖 Generated with Claude Code