# Alepha - React Router

## Installation

Part of the `alepha` package. Import from `alepha/react/router`.

```bash
npm install alepha
```

## 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

- [`$page`](https://latest.alepha.dev/docs/reference-primitives-$page.md) - Main primitive for defining a React route in the application.

### React Hooks

- [`useActive`](https://latest.alepha.dev/docs/reference-react-hooks-useactive.md) - Hook to determine if a given route is active and to provide anchor props for navigation.
- [`useQueryParams`](https://latest.alepha.dev/docs/reference-react-hooks-usequeryparams.md) - Hook to manage query parameters in the URL using a defined schema.
- [`useRouter`](https://latest.alepha.dev/docs/reference-react-hooks-userouter.md) - Use this hook to access the React Router instance.
- [`useRouterState`](https://latest.alepha.dev/docs/reference-react-hooks-userouterstate.md) - Subscribes to the router's live state - the matched route, its params and

### Providers

- [`ReactBrowserRendererProvider`](https://latest.alepha.dev/docs/reference-providers-reactbrowserrendererprovider.md) - Browser specific React renderer (react-dom/client interface)
- [`ReactBrowserRouterProvider`](https://latest.alepha.dev/docs/reference-providers-reactbrowserrouterprovider.md) - Implementation of AlephaRouter for React in browser environment.
- [`ReactDomServerProvider`](https://latest.alepha.dev/docs/reference-providers-reactdomserverprovider.md) - The renderer half of React, loaded only once something actually renders.
- [`ReactPageCacheProvider`](https://latest.alepha.dev/docs/reference-providers-reactpagecacheprovider.md) - The automatic page cache (#E78).
- [`ReactPageProvider`](https://latest.alepha.dev/docs/reference-providers-reactpageprovider.md) - Handle page routes for React applications. (Browser and Server)
- [`ReactPreloadProvider`](https://latest.alepha.dev/docs/reference-providers-reactpreloadprovider.md) - Adds HTTP Link headers for preloading entry assets.
- [`ReactServerErrorProvider`](https://latest.alepha.dev/docs/reference-providers-reactservererrorprovider.md) - Answers a browser navigation with an HTML error page instead of JSON.
- [`ReactServerProvider`](https://latest.alepha.dev/docs/reference-providers-reactserverprovider.md) - React server provider responsible for SSR and static file serving.
- [`ReactServerTemplateProvider`](https://latest.alepha.dev/docs/reference-providers-reactservertemplateprovider.md) - Handles HTML streaming for SSR.
- [`RootComponentsProvider`](https://latest.alepha.dev/docs/reference-providers-rootcomponentsprovider.md) - Extension point letting any module contribute root-level React nodes that
- [`RouterLocaleProvider`](https://latest.alepha.dev/docs/reference-providers-routerlocaleprovider.md) - Generic locale path-prefix mechanism for the router.
- [`SSRManifestProvider`](https://latest.alepha.dev/docs/reference-providers-ssrmanifestprovider.md) - Provider for SSR manifest data used for module preloading.

### Environment Variables

Environment variables used to configure this module. These can be set in your `.env` file or through your deployment configuration.

| Variable            | Type    | Default | Description                                                                                                            |
| ------------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `REACT_PAGE_CACHE`  | boolean | -       | Turn the automatic SSR page cache off (false) without a code change, for an incident.                                  |
| `REACT_SSR_ENABLED` | boolean | -       | Enable or disable server-side rendering (SSR) for React pages. When set to false, pages are rendered client-side only. |