#@alepha/react - Router

#Installation

npm install @alepha/react

#Overview

Provides declarative routing with the $page primitive for building type-safe React routes.

This module enables:

• URL pattern matching with parameters (e.g., /users/:id)
• Nested routing with parent-child relationships
• Type-safe URL parameter and query string validation
• Server-side data fetching with the loader function
• Lazy loading and code splitting
• Page animations and error handling

#API Reference

#Primitives

Primitives are functions that define and configure various aspects of your application. They follow the convention of starting with $ and return configured primitive instances.

For more details, see the Primitives documentation.

#$page()

Main primitive for defining a React route in the application.

The $page primitive is the core building block for creating type-safe, SSR-enabled React routes. It provides a declarative way to define pages with powerful features:

Routing & Navigation

• URL pattern matching with parameters (e.g., /users/:id)
• Nested routing with parent-child relationships
• Type-safe URL parameter and query string validation

Data Loading

• Server-side data fetching with the loader function
• Automatic serialization and hydration for SSR
• Access to request context, URL params, and parent data

Component Loading

• Direct component rendering or lazy loading for code splitting
• Client-only rendering when browser APIs are needed
• Automatic fallback handling during hydration

Performance Optimization

• Static generation for pre-rendered pages at build time
• Server-side caching with configurable TTL and providers
• Code splitting through lazy component loading

Error Handling

• Custom error handlers with support for redirects
• Hierarchical error handling (child → parent)
• HTTP status code handling (404, 401, etc.)

Page Animations

• CSS-based enter/exit animations
• Dynamic animations based on page state
• Custom timing and easing functions

Lifecycle Management

• Server response hooks for headers and status codes
• Page leave handlers for cleanup (browser only)
• Permission-based access control

 1const userProfile = $page({ 2  path: "/users/:id", 3  schema: { 4    params: t.object({ id: t.integer() }), 5    query: t.object({ tab: t.optional(t.text()) }) 6  }, 7  loader: async ({ params }) => { 8    const user = await userApi.getUser(params.id); 9    return { user };10  },11  lazy: () => import("./UserProfile.tsx")12});

 1const projectSection = $page({ 2  path: "/projects/:id", 3  children: () => [projectBoard, projectSettings], 4  loader: async ({ params }) => { 5    const project = await projectApi.get(params.id); 6    return { project }; 7  }, 8  errorHandler: (error) => { 9    if (HttpError.is(error, 404)) {10      return <ProjectNotFound />;11    }12  }13});

 1const blogPost = $page({ 2  path: "/blog/:slug", 3  static: { 4    entries: posts.map(p => ({ params: { slug: p.slug } })) 5  }, 6  loader: async ({ params }) => { 7    const post = await loadPost(params.slug); 8    return { post }; 9  }10});

#Hooks

Hooks provide a way to tap into various lifecycle events and extend functionality. They follow the convention of starting with use and return configured hook instances.

#useActive()

Hook to determine if a given route is active and to provide anchor props for navigation. This hook refreshes on router state changes.

#useQueryParams()

Hook to manage query parameters in the URL using a defined schema.

#useRouter()

Use this hook to access the React Router instance.

You can add a type parameter to specify the type of your application. This will allow you to use the router in a typesafe way.

class App { home = $page(); }

const router = useRouter(); router.go("home"); // typesafe

#Providers

Providers are classes that encapsulate specific functionality and can be injected into your application. They handle initialization, configuration, and lifecycle management.

For more details, see the Providers documentation.

#ReactBrowserRendererProvider

Browser specific React renderer (react-dom/client interface)

#ReactBrowserRouterProvider

Implementation of AlephaRouter for React in browser environment.

#ReactPageProvider

Handle page routes for React applications. (Browser and Server)

#ReactServerProvider

React server provider responsible for SSR and static file serving.

Coordinates between:

• ReactPageProvider: Page routing and layer resolution
• ReactServerTemplateProvider: HTML template parsing and streaming
• ServerHeadProvider: Head content management
• SSRManifestProvider: Module preload link collection

Uses react-dom/server under the hood.

#ReactServerTemplateProvider

Handles HTML template parsing, preprocessing, and streaming for SSR.

Responsibilities:

• Parse template once at startup into logical slots
• Pre-encode static parts as Uint8Array for zero-copy streaming
• Render dynamic parts (attributes, head content) efficiently
• Build hydration data for client-side rehydration

This provider is injected into ReactServerProvider to handle all template-related operations, keeping ReactServerProvider focused on request handling and React rendering coordination.

#SSRManifestProvider

Provider for SSR manifest data used for module preloading.

The manifest is populated at build time by embedding data into the generated index.js via the ssrManifestAtom. This eliminates filesystem reads at runtime, making it optimal for serverless deployments.

Manifest files are generated during vite build:

• manifest.json (client manifest)
• ssr-manifest.json (SSR manifest)
• preload-manifest.json (from viteAlephaSsrPreload plugin)