router6-plugin-persistent-params

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(persistentParamsPlugin(["lang", "theme"]));
router.navigate("products", { lang: "en", theme: "dark" });
router.navigate("cart");
// URL: /cart?lang=en&theme=dark  ← automatically preserved

Installation

npm install router6-plugin-persistent-params
# or
pnpm add router6-plugin-persistent-params
# or
yarn add router6-plugin-persistent-params
# or
bun add router6-plugin-persistent-params

Quick Start

import { createRouter } from "router6";
import { persistentParamsPlugin } from "router6-plugin-persistent-params";

const router = createRouter(routes);

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

// Option 2: With default values
router.usePlugin(
  persistentParamsPlugin({
    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(persistentParamsPlugin({ lang: "en" }));

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

UTM Tracking

router.usePlugin(
  persistentParamsPlugin(["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(persistentParamsPlugin(["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

• router6 — Core router
• router6-plugin-browser — Browser history

License

MIT © Oleg Ivanov