@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({
    useHash: false,
    base: "/app",
  }),
);

router.start();

Configuration

router.usePlugin(
  browserPluginFactory({
    useHash: true, // Required for hashPrefix
    hashPrefix: "!",
  }),
);

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

| Option | Type | Default | Description | | ----------------- | --------- | ------- | -------------------------------------------------------------------- | | useHash | boolean | false | Use hash routing (#/path) instead of History API | | hashPrefix | string | "" | Hash prefix (e.g., "!" → #!/path). Only with useHash: true | | preserveHash | boolean | true | Keep URL hash fragment during navigation. Only with useHash: false | | base | string | "" | Base path for all routes (e.g., "/app") | | forceDeactivate | boolean | true | Bypass canDeactivate guards on browser back/forward | | mergeState | boolean | false | Merge with existing history.state |

Type Safety: Options use discriminated union — hashPrefix and preserveHash are mutually exclusive at compile time.

See Wiki for detailed option descriptions and examples.

Added Router Methods

The plugin extends the router with browser-specific methods:

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

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

const state = router.lastKnownState;
// Returns frozen copy of state or undefined

if (state) {
  console.log("Last route:", state.name);
  console.log("Parameters:", state.params);
}

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" });

router.lastKnownState: State | undefined

Last successful navigation state (readonly).
Returns: State | undefined
Wiki

Usage Examples

History Mode (default)

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

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

Hash Mode

router.usePlugin(
  browserPluginFactory({
    useHash: true,
    hashPrefix: "!",
  }),
);

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

Form Protection

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

router.canDeactivate("checkout", () => (toState, fromState, done) => {
  if (hasUnsavedChanges()) {
    done({ error: new Error("Unsaved changes") });
  } else {
    done();
  }
});

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/react — React integration
• @real-router/logger-plugin — Debug logging

License

MIT © Oleg Ivanov