@real-router/hash-plugin

Hash-based routing plugin for Real-Router. Uses URL hash fragment (#/path) for navigation — no server configuration needed.

Works on static hosting (GitHub Pages, S3, Netlify) without redirect rules. Tradeoff: URLs include # (example.com/#!/users vs example.com/users).

Looking for clean URLs? Use @real-router/browser-plugin (History API).

Installation

npm install @real-router/hash-plugin

Peer dependency: @real-router/core

Quick Start

import { createRouter } from "@real-router/core";
import { hashPluginFactory } from "@real-router/hash-plugin";

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

router.usePlugin(hashPluginFactory());
await router.start(); // reads hash from browser location

Options

| Option | Type | Default | Description | | ----------------- | --------- | ------- | ----------------------------------------------------- | | hashPrefix | string | "" | Prefix after # (e.g., "!" → #!/path) | | base | string | "" | Base path before hash (e.g., "/app" → /app#/path) | | forceDeactivate | boolean | true | Bypass canDeactivate guards on back/forward |

router.usePlugin(hashPluginFactory({ hashPrefix: "!", base: "/app" }));

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

Router Extensions

The plugin extends the router instance with three methods via extendRouter():

| Method | Returns | Description | | -------------------------------------------- | -------------------- | ------------------------------------- | | buildUrl(name, params?) | string | Build full URL with hash and prefix | | matchUrl(url) | State \| undefined | Parse hash URL to router state | | replaceHistoryState(name, params?, title?) | void | Update browser URL without navigation |

router.buildUrl("users", { id: "123" });
// => "#!/users/123" (with hashPrefix "!")

router.matchUrl("https://example.com/#!/users/123");
// => { name: "users", params: { id: "123" }, path: "/users/123" }

// Update URL silently (no transition, no guards)
router.replaceHistoryState("users", { id: "456" });

buildUrl vs buildPath

router.buildPath("users", { id: 1 }); // "/users/1"       — core, no hash
router.buildUrl("users", { id: 1 }); // "#!/users/1"     — plugin, with hash prefix

Form Protection

Set forceDeactivate: false to respect canDeactivate guards on back/forward:

router.usePlugin(hashPluginFactory({ forceDeactivate: false }));

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

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

SSR Support

SSR-safe — automatically detects the environment and falls back to no-ops:

router.usePlugin(hashPluginFactory());
router.buildUrl("home"); // returns hash path
router.matchUrl("/path"); // returns undefined

Documentation

Full documentation: Wiki — hash-plugin

• Configuration Options
• Behavior & Edge Cases

Related Packages

| Package | Description | | ---------------------------------------------------------------------------------------- | -------------------------------------- | | @real-router/core | Core router (required peer dependency) | | @real-router/browser-plugin | History API routing (clean URLs) | | @real-router/react | React integration |

Contributing

See contributing guidelines for development setup and PR process.

License

MIT © Oleg Ivanov