metabuilder/codegen/docs/preloading-quick-reference.md

Route Preloading - Quick Reference

For Developers

Adding a New Preloadable Component

1. Register in Component Registry (/src/lib/component-registry.ts):

MyNewComponent: lazyWithPreload(
  () => import('@/components/MyNewComponent').then(m => ({ default: m.MyNewComponent })),
  'MyNewComponent'  // Unique cache key
),

2. Add to pages.json (/src/config/pages.json):

{
  "id": "my-route",
  "component": "MyNewComponent",
  "enabled": true
}

3. Done! The component will now preload on hover automatically.

Manual Preloading in a Custom Component

import { useRoutePreload } from '@/hooks/use-route-preload'

function MyComponent() {
  const { preloadRoute } = useRoutePreload({ delay: 150 })
  
  return (
    <button onMouseEnter={() => preloadRoute('editor')}>
      Go to Editor
    </button>
  )
}

Checking Preload Status

import { routePreloadManager } from '@/lib/route-preload-manager'

const isReady = routePreloadManager.isPreloaded('editor')
const stats = routePreloadManager.getStats()
console.log(stats)
// { preloadedCount: 5, queuedCount: 2, activePreloads: 1, currentRoute: 'dashboard' }

For Users

What is Route Preloading?

When you hover over a navigation item, the app starts loading that page in the background. When you click, the page appears instantly with no loading spinner.

Visual Feedback

A small lightning icon appears in the bottom-right corner when routes are preloading. This is normal and indicates the app is preparing pages for you.

Performance Tips

• Hover before clicking: Give the app a moment to preload by hovering over navigation items before clicking
• Sequential navigation: The app automatically preloads the next/previous pages when you navigate
• First load: Popular pages load in the background after initial app startup

Configuration

Adjust Hover Delay

In /src/components/organisms/NavigationMenu.tsx:

const { preloadRoute, cancelPreload } = useRoutePreload({ delay: 100 }) // milliseconds

Adjust Concurrent Preloads

In /src/lib/route-preload-manager.ts:

const DEFAULT_STRATEGY = {
  maxConcurrentPreloads: 3, // Adjust based on bandwidth
}

Customize Popular Routes

In /src/lib/route-preload-manager.ts:

const popularRoutes = new Set(['dashboard', 'editor', 'models', 'components'])

Disable Features

In /src/lib/route-preload-manager.ts:

const DEFAULT_STRATEGY = {
  preloadAdjacent: false,  // Disable prev/next preloading
  preloadPopular: false,   // Disable popular route preloading
}

Hide Preload Indicator

In /src/App.tsx, remove or comment out:

<PreloadIndicator />

Console Debugging

Enable Verbose Logging

All preload operations log with [PRELOAD] or [PRELOAD_MGR] prefix:

• 🚀 = Initiating preload
• ✅ = Success
• ❌ = Error
• ⚠️ = Warning
• ⏳ = In progress
• 🎯 = Targeting specific route

Filter Console

In browser DevTools:

[PRELOAD     // Show only preload logs

Troubleshooting

Issue	Solution
Routes not preloading	Check component is using lazyWithPreload
Too many network requests	Reduce maxConcurrentPreloads
Slow initial load	Disable preloadPopular or increase delay
Memory concerns	Normal - browser manages cache automatically
Indicator always showing	Check for errors in console

Metrics to Track

• Preload Hit Rate: % of navigations that were preloaded
• Average Preload Time: Time from hover to bundle loaded
• User Satisfaction: Navigation feels instant vs. noticeable delay

Related Documentation

• Full documentation: /docs/hover-preloading.md
• Code splitting docs: /docs/code-splitting.md (if exists)
• React Router docs: /docs/routing.md (if exists)