@real-router/persistent-params-plugin


Automatically persists query parameters across all navigation transitions.

Problem & Solution

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

`bash
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

`typescript
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 | Parameter names with defaults | { lang: "en" } |

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

See Wiki for details.

---

Behavior

$3

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

$3

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

$3

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

$3

Explicit values override saved ones:

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

See Wiki for edge cases and guarantees.

---

Usage Examples

$3

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

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

$3

`typescript
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

`typescript
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