Improve lighthouse performance scores (desktop and mobile)

[masenf]

Lighthouse is a webpage performance benchmark built into Chrome browsers. It evaluates pages across four categories: Performance, Accessibility, Best Practices, and SEO.

Reflex apps in prod mode should consistently score in the 90s for all categories in the default configuration.

Current State

Out-of-the-box Reflex apps can score lower than expected on Lighthouse audits, particularly on mobile. Common issues include:

• Large JS bundle size — the compiled frontend ships more JavaScript than necessary, increasing Total Blocking Time (TBT) and Time to Interactive (TTI).
• Render-blocking resources — CSS and JS that block first paint, hurting First Contentful Paint (FCP) and Largest Contentful Paint (LCP).
• Missing or suboptimal meta tags — default templates may lack proper <meta> viewport, description, or Open Graph tags, lowering the SEO score.
• Accessibility gaps — default component markup may be missing ARIA attributes, proper heading hierarchy, color contrast ratios, or focus management.
• Cumulative Layout Shift (CLS) — layout shifts during hydration or lazy-loaded content can degrade the performance score.
• Image handling — no built-in support for modern formats (WebP/AVIF), responsive srcset, or lazy loading defaults.

Goals

Performance (target: 90+)

• Reduce JS bundle size via tree-shaking, code splitting, and dead code elimination
• Defer non-critical JS and CSS; inline critical CSS
• Optimize hydration to minimize TBT
• Minimize CLS during initial load and state hydration
• Serve assets with proper caching headers and compression (gzip/brotli)

Accessibility (target: 90+)

• Ensure all default components emit semantic HTML with proper ARIA attributes
• Enforce sufficient color contrast in the default theme
• Ensure proper heading hierarchy and landmark regions in default layouts
• Keyboard navigability and focus management for interactive components

Best Practices (target: 90+)

• Serve all assets over HTTPS by default in prod
• Avoid deprecated APIs in generated frontend code
• Ensure proper image aspect ratios to avoid layout shifts
• Use passive event listeners where applicable

SEO (target: 90+)

• Generate proper <title>, <meta description>, and canonical tags by default
• Ensure pages are crawlable — proper use of robots.txt and sitemap generation
• Structured data / JSON-LD support for common page types
• Ensure all links have descriptive text and images have alt attributes

Approach

• Establish a Lighthouse CI benchmark in the test suite that runs against a reference Reflex app in prod mode
• Track scores per category across releases to catch regressions
• Address low-hanging fruit first (meta tags, compression, defer attributes) then tackle deeper issues (bundle splitting, hydration optimization)
• Document best practices for users to further optimize their own apps

[linear]

ENG-9323

[masenf]

Consider an Image optimizer plugin that runs as part of the compile and generates web-native images in different sizes optimized for different devices.