@real-router/persistent-params-plugin

Automatically persists query parameters across all navigation transitions.

Problem & Solution

// Without plugin:
router.navigate("products", { lang: "en", theme: "dark" });
router.navigate("cart");
// URL: /cart  ← lang and theme are lost

// With plugin:
router.usePlugin(persistentParamsPluginFactory(["lang", "theme"]));
router.navigate("products", { lang: "en", theme: "dark" });
router.navigate("cart");
// URL: /cart?lang=en&theme=dark  ← automatically preserved

Installation

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

Quick Start

import { createRouter } from "@real-router/core";
import { persistentParamsPluginFactory } from "@real-router/persistent-params-plugin";

const router = createRouter(routes);

// Option 1: Parameter names (values set on first use)
router.usePlugin(persistentParamsPluginFactory(["lang", "theme"]));

// Option 2: With default values
router.usePlugin(
  persistentParamsPluginFactory({
    lang: "en",
    theme: "light",
  }),
);

router.start();

Configuration

| Config Type | Description | Example | | --------------------------- | ------------------------------------------- | ------------------- | | string[] | Parameter names, initial values undefined | ["lang", "theme"] | | Record<string, primitive> | Parameter names with defaults | { lang: "en" } |

Allowed value types: string, number, boolean, undefined (to remove)

See Wiki for details.

Behavior

Persistence

router.navigate("page1", { lang: "en" }); // Saved: lang=en
router.navigate("page2"); // URL: /page2?lang=en

Update

router.navigate("page", { lang: "fr" }); // Updates saved value

Remove

router.navigate("page", { lang: undefined }); // Removes from persistent params

Priority

Explicit values override saved ones:

// Saved: lang=en
router.navigate("page", { lang: "de" }); // URL: /page?lang=de

See Wiki for edge cases and guarantees.

Usage Examples

Multilingual App

router.usePlugin(persistentParamsPluginFactory({ lang: "en" }));

router.navigate("settings", { lang: "fr" });
router.navigate("products"); // ?lang=fr
router.navigate("cart"); // ?lang=fr

UTM Tracking

router.usePlugin(
  persistentParamsPluginFactory(["utm_source", "utm_medium", "utm_campaign"]),
);

// User arrives: /?utm_source=google&utm_medium=cpc
router.navigate("products"); // UTM params preserved
router.navigate("checkout"); // UTM params preserved

Lifecycle

const unsubscribe = router.usePlugin(persistentParamsPluginFactory(["mode"]));

// Later: restore original router behavior
unsubscribe();

Note: Double initialization throws an error. Call unsubscribe() first.

Documentation

Full documentation on Wiki:

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

Related Packages

• @real-router/core — Core router
• @real-router/browser-plugin — Browser history

License

MIT © Oleg Ivanov