How preactjs/preact-iso works
Project type and purpose
• This is an open‑source library (not a standalone app) that provides isomorphic (SSR+CSR) async utilities for Preact—namely lazy, prerender, hydrate, routing, and error boundaries.
• It is intended to plug into Preact applications or build tools (e.g. Vite with @preact/preset-vite) to enable code‑splitting, progressive hydration, async routing, and prerendering.
File structure
Top level:
• package.json, ts/jsconfigs, CI and metadata (.github/, LICENSE, etc.)
• src/ → implementation of each export (lazy.js, router.js, hydrate.js, prerender.js, internal.js, plus TypeScript definitions)
• test/ → unit tests exercising each feature in both browser and Node contexts
• web-test-runner.config.js → test runner setup
Patterns & clues:
• Each feature is factored into its own module in src/
• internal.js likely holds shared utilities for promise‑suspense integration
• No “frontend/backend” – it’s a library, so core components and utilities
README for insights
• Confirms the main exports: lazy(), prerender(), hydrate(), <Router>, <LocationProvider>, <ErrorBoundary>, and hooks useLocation, useRoute.
• Describes how client hydration and server prerendering interact.
• Mentions dependency on preact-render-to-string for SSR.
• Shows code examples with dynamic import() and async routing behavior.
a. Main components
• Consumer App (user’s Preact application)
• LocationProvider / Context Layer
• Router & Route Matching Engine
• Lazy Loader (dynamic import wrapper + Suspense boundary)
• ErrorBoundary
• CSR Hydrator (hydrate)
• SSR Prerenderer (prerender → preact‑render‑to‑string)
• Shared Internal Utilities
• External Dependencies (Preact core, dynamic import mechanism, preact‑render‑to‑string)
b. Relationships & interactions
1. Consumer App imports preact‑iso exports.
2. At build/SSR time:
– prerender() invokes internal utilities + preact-render-to-string to produce HTML + link list.
3. At runtime in browser:
– hydrate() checks for existing SSR markup → if present, calls Preact’s hydrate, else does fresh render.
– <LocationProvider> sets up URL context.
– <Router> consumes context, matches routes using router-engine.
– When a routed component is a lazy() wrapper, it suspends (throws a Promise) until the dynamic import resolves, enabling progressive hydration or seamless transitions.
– <ErrorBoundary> wraps around to catch rendering or loading errors.
c. Architectural patterns/design principles
• Modular single‑responsibility: each feature is in its own module.
• Suspense‑style async handling: lazy() components throw Promises for integration with SSR and CSR lifecycles.
• Context API for routing state (LocationProvider + Router).
• Clear separation of SSR vs CSR utilities (prerender vs hydrate).
• Hooks for location and route introspection.
d. Key technologies & libraries
• Preact core (vnode creation, hydrate/render)
• preact‑render‑to‑string (SSR)
• Dynamic import() for code splitting
• Web‑Test‑Runner for tests