@real-router/browser-plugin

Browser History API integration for Real-Router. Synchronizes router state with browser URL and handles back/forward navigation.

Installation

npm install @real-router/browser-plugin
# or
pnpm add @real-router/browser-plugin
# or
yarn add @real-router/browser-plugin
# or
bun add @real-router/browser-plugin

Quick Start

import { createRouter } from "@real-router/core";
import { browserPluginFactory } from "@real-router/browser-plugin";

const router = createRouter([
  { name: "home", path: "/" },
  { name: "products", path: "/products/:id" },
  { name: "cart", path: "/cart" },
]);

// Basic usage
router.usePlugin(browserPluginFactory());

// With options
router.usePlugin(
  browserPluginFactory({
    base: "/app",
  }),
);

await router.start();

Configuration

router.usePlugin(
  browserPluginFactory({
    base: "/app",
    forceDeactivate: true,
  }),
);

router.navigate("products", { id: "123" });
// URL: http://example.com/app/products/123

| Option | Type | Default | Description | | ----------------- | --------- | ------- | ----------------------------------------------------- | | base | string | "" | Base path for all routes (e.g., "/app") | | forceDeactivate | boolean | true | Bypass canDeactivate guards on browser back/forward |

Looking for hash routing? Use @real-router/hash-plugin instead.

See Wiki for detailed option descriptions and examples.

Added Router Methods

The plugin extends the router instance with browser-specific methods (via extendRouter()):

router.buildUrl(name: string, params?: Params): string

Build full URL with base path.
name: string — route name
params?: Params — route parameters
Returns: string — full URL
Wiki

router.buildUrl("users", { id: "123" });
// => "/app/users/123" (with base "/app")

router.matchUrl(url: string): State | undefined

Parse URL to router state.
url: string — URL to parse
Returns: State | undefined
Wiki

router.navigate("page1");
router.navigate("page2");
router.navigate("page3");

// User clicks back twice rapidly
// Plugin ensures router ends at page1
// URL and router state remain synchronized

router.replaceHistoryState(name: string, params?: Params, title?: string): void

Update browser URL without triggering navigation.
name: string — route name
params?: Params — route parameters
title?: string — page title
Returns: void
Wiki

router.replaceHistoryState("users", { id: "456" });

Usage Examples

With Base Path

router.usePlugin(
  browserPluginFactory({
    base: "/app",
  }),
);

router.navigate("users", { id: "123" });
// URL: /app/users/123

Form Protection

router.usePlugin(
  browserPluginFactory({
    forceDeactivate: false,
  }),
);

import { getLifecycleApi } from "@real-router/core/api";

const lifecycle = getLifecycleApi(router);
lifecycle.addDeactivateGuard("checkout", () => (toState, fromState) => {
  return !hasUnsavedChanges(); // false blocks navigation
});

SSR Support

The plugin is SSR-safe with automatic fallback:

// Server-side — no errors, methods return safe defaults
router.usePlugin(browserPluginFactory());
router.buildUrl("home"); // Works
router.matchUrl("/path"); // Returns undefined

Documentation

Full documentation available on the Wiki:

• Configuration Options
• Lifecycle Hooks
• Router Methods
• Behavior & Edge Cases
• Migration from router5

Related Packages

• @real-router/core — Core router
• @real-router/hash-plugin — Hash-based routing (#/path)
• @real-router/react — React integration
• @real-router/logger-plugin — Debug logging

License

MIT © Oleg Ivanov