@real-router/persistent-params-plugin

Automatically persist query parameters across all navigation transitions in Real-Router.

// 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

Peer dependency: @real-router/core

Quick Start

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

const router = createRouter(routes);

// Array — values set on first navigation
router.usePlugin(persistentParamsPluginFactory(["lang", "theme"]));

// Object — with default values
router.usePlugin(persistentParamsPluginFactory({ lang: "en", theme: "light" }));

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 a param).

Behavior

// Persist — saved on first navigation
router.navigate("page1", { lang: "en" });     // saved: lang=en

// Carry — auto-injected into subsequent navigations
router.navigate("page2");                      // URL: /page2?lang=en

// Update — explicit values override saved ones
router.navigate("page3", { lang: "fr" });      // URL: /page3?lang=fr, saved: lang=fr

// Remove — pass undefined to stop persisting
router.navigate("page4", { lang: undefined }); // lang removed permanently

Note: Removal is permanent for the plugin lifetime. Once undefined is passed, the param is no longer tracked — even if passed again in a later navigation.

Use Cases

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

Cleanup

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

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

State Context: state.context.persistentParams

The plugin publishes a snapshot of the current persistent params to state.context.persistentParams after each successful transition. This lets components distinguish persistent params from route-specific params.

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

const router = createRouter(routes);
router.usePlugin(persistentParamsPluginFactory({ lang: "en", theme: "light" }));

router.subscribe(({ route, previousRoute }) => {
  const { params, context } = route;

  // params contains BOTH route-specific and persistent params merged together
  console.log(params);              // { id: "42", lang: "en", theme: "light" }

  // context.persistentParams contains ONLY the persistent params
  console.log(context.persistentParams); // { lang: "en", theme: "light" }
});

Timing: Written in onTransitionSuccess (before subscriber callbacks fire). Always reflects the latest committed values.

Type: Importing @real-router/persistent-params-plugin augments StateContext with persistentParams?: Params, providing full type safety.

Documentation

Full documentation: Wiki — persistent-params-plugin

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

Related Packages

| Package | Description | |---------|-------------| | @real-router/core | Core router (required peer dependency) | | @real-router/browser-plugin | Browser History API integration |

Contributing

See contributing guidelines for development setup and PR process.

License

MIT © Oleg Ivanov