Suspense Split Utility and Vite SSR Optimization

[Uttkarsh-Srivastava]

Overview

This PR introduces a comprehensive code-splitting and Server-Side Rendering (SSR) optimization system that replaces the existing asset extraction mechanism with a more sophisticated approach using React Suspense, custom Split components, and enhanced Vite build tooling.

Key Changes

1. New Split Component System (src/web-router/components/Split.jsx)

• Purpose: Provides SSR-aware code splitting using React's lazy and Suspense
• Features:
  • Configurable SSR behavior (ssr: true/false)
  • Automatic asset tracking via ChunkExtractor
  • Graceful fallback handling
  • Server/client environment detection

// Usage example
const LazyComponent = split(() => import('./MyComponent'), { 
  ssr: true, 
  fallback: <Loading /> 
})

2. ChunkExtractor System (src/server/renderer/ChunkExtractor.js)

• Replaces: Legacy CSS/JS caching system
• Features:
  • Tracks essential vs non-essential assets
  • Categorizes assets by SSR configuration
  • Deduplicates CSS and JS files
  • Integrates with Vite's manifest system

3. Vite Build System Enhancements

Asset Categorization Plugin (src/vite/manifest-categorization-plugin.js)

• Purpose: Automatically categorizes build assets into three groups:
  • essential: Core assets needed for app functionality
  • ssrTrue: Assets from components with ssr: true
  • ssrFalse: Assets from components with ssr: false
• Process:
  1. Scans source code for split() calls
  2. Tracks SSR configuration per component
  3. Maps modules to chunks during build
  4. Generates asset-categories.json manifest

Cache Key Injection Plugin (src/vite/inject-cache-key-plugin.js)

• Purpose: Automatically injects resolved file paths as cache keys into split() calls
• Benefit: Enables precise asset tracking without manual configuration

4. Enhanced Asset Loading System

Before (Legacy System)

• Used cacheCSS() and cacheJS() functions
• Inlined CSS styles directly into HTML
• Simple asset bundling without categorization

After (New System)

• CSS: Generates <link rel="stylesheet"> tags instead of inlined styles
• JS: Creates proper module preload hints and script tags
• Streaming: Assets are loaded progressively during SSR streaming
• Categorization: Different loading strategies based on SSR requirements

5. Server-Side Rendering Improvements (src/server/renderer/handler.jsx)

Removed Two-Pass Rendering

• Old: Component usage tracking with React.createElement override
• New: Direct asset collection using ChunkExtractor

Streaming Enhancements

• Essential assets loaded with initial HTML shell
• Non-essential assets streamed after onAllReady
• Better performance through progressive loading

Dynamic Store Loading

• Fallback mechanism when store configuration is missing
• More resilient error handling

6. Configuration Updates

Express Server (src/server/expressServer.js)

• Added assetManifest loading from asset-categories.json
• Enhanced manifest reading with better error handling
• Updated static asset serving paths

Vite Configurations

• Client Config: Added manifest categorization plugin
• Server Config: Added cache key injection plugin
• Base Config: Enhanced chunking strategy and build optimization

Benefits

Performance Improvements

1. Reduced Bundle Size: Code splitting prevents loading unused components
2. Faster Initial Load: Essential assets loaded first, non-essential deferred
3. Better Caching: More granular asset categorization enables better cache strategies
4. Streaming SSR: Progressive asset loading during server rendering

Developer Experience

1. Automatic Asset Management: No manual asset tracking required
2. SSR Control: Fine-grained control over which components render server-side
3. Build-Time Optimization: Vite plugins handle complexity automatically
4. Better Error Handling: Graceful fallbacks for missing components/stores

Architecture Benefits

1. Separation of Concerns: Clear distinction between essential and optional assets
2. Scalability: System handles complex component hierarchies efficiently
3. Maintainability: Automated asset categorization reduces manual configuration
4. Future-Proof: Built on modern React patterns (Suspense, lazy loading)

Breaking Changes

• Changed CSS delivery from inlined styles to external stylesheets
• Updated document Head/Body component prop interfaces
• Modified asset extraction workflow

Migration Path

Existing applications need to:

1. Replace manual asset loading with split() components
2. Update custom document components to handle new asset structure
3. Rebuild with new Vite configuration to generate asset categories
4. Test SSR behavior with new streaming approach

[deputydev-agent]

DeputyDev has started reviewing your pull request.