JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 2114
  • Score
    100M100P100Q112062F
  • License MIT

Persist query parameters across route transitions

Package Exports

  • @real-router/persistent-params-plugin

Readme

@real-router/persistent-params-plugin

License: MIT TypeScript

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:

License

MIT © Oleg Ivanov