@real-router/memory-plugin

In-memory history stack for Real-Router. Back/forward/go navigation without browser History API.

Installation

npm install @real-router/memory-plugin

Peer dependency: @real-router/core

Quick Start

import { createRouter } from "@real-router/core";
import { memoryPluginFactory } from "@real-router/memory-plugin";

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

router.usePlugin(memoryPluginFactory());
await router.start("/");

await router.navigate("users", { id: "1" });
await router.navigate("users", { id: "2" });

// Fire-and-forget: each call schedules a navigation and returns immediately.
// Subscribe to state changes to detect completion.
router.back(); // navigate to users/1
router.forward(); // navigate to users/2
router.go(-2); // navigate to home

Options

router.usePlugin(
  memoryPluginFactory({
    maxHistoryLength: 50, // Keep at most 50 entries
  }),
);

| Option | Type | Default | Description | | ------------------ | -------- | ------- | ------------------------------------------------------------- | | maxHistoryLength | number | 1000 | Maximum entries. 0 = unlimited, negative throws TypeError |

Router Extensions

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

| Method | Returns | Description | | ---------------- | --------- | --------------------------------------------------------------- | | back() | void | Navigate to the previous history entry | | forward() | void | Navigate to the next history entry | | go(delta) | void | Navigate by delta steps (negative = back, positive = forward) | | canGoBack() | boolean | true if there is a previous entry | | canGoForward() | boolean | true if there is a next entry |

All navigation methods are fire-and-forget (void). To detect completion, subscribe to state changes before calling.

router.subscribe(({ route }) => {
  console.log("navigated to", route.name);
});

router.back();

Guards can block back/forward navigation. If a guard rejects, the history index stays unchanged and canGoBack()/canGoForward() continue to reflect the actual position.

Use Cases

React Native / non-browser environments

No window.history required. Drop in memoryPluginFactory() and get full back/forward support anywhere JavaScript runs.

Testing and benchmarks

Deterministic navigation without browser globals. Start the router at any path, navigate programmatically, assert state.

const router = createRouter(routes);
router.usePlugin(memoryPluginFactory());
await router.start("/");

await router.navigate("dashboard");
expect(router.canGoBack()).toBe(true);

router.back();
// wait for state change, then assert

SSR navigation simulation

Simulate multi-step user flows on the server without a browser environment.

Documentation

Full documentation: Wiki — memory-plugin

Related Packages

| Package | Description | | ---------------------------------------------------------------------------------------- | -------------------------------------- | | @real-router/core | Core router (required peer dependency) | | @real-router/browser-plugin | Browser History API integration | | @real-router/hash-plugin | Hash-based routing (#/path) |

Contributing

See contributing guidelines for development setup and PR process.

License

MIT © Oleg Ivanov