getPluginApi().addBuildPathInterceptor

Method for plugin authors

1. Overview

• What it does: Registers a param transformer in the buildPath pipeline. When router.buildPath() is called, all registered interceptors execute in FIFO order, each receiving and returning params.
• When to use:
  • Injecting params into every buildPath call (e.g., persistent query params)
  • Transforming params before URL construction
  • Plugin infrastructure that needs to modify URL building behavior

2. Signature

import { getPluginApi } from "@real-router/core/api";

const pluginApi = getPluginApi(router);

pluginApi.addBuildPathInterceptor(
  fn: (routeName: string, params: Params) => Params,
): Unsubscribe

Parameters

Parameter	Type	Required	Description
fn	(routeName: string, params: Params) => Params	Yes	Interceptor function. Receives route name and current params, must return (possibly transformed) params.

Return Value

type Unsubscribe = () => void;

• Returns a function that removes this interceptor from the pipeline
• Idempotent — safe to call multiple times
• Typically called during plugin teardown()

3. Behavior

FIFO Execution Order

Interceptors execute in registration order. Each interceptor receives the params returned by the previous one:

const api = getPluginApi(router);

api.addBuildPathInterceptor((routeName, params) => {
  return { ...params, first: "1" };
});

api.addBuildPathInterceptor((routeName, params) => {
  // params already contains { first: "1" }
  return { ...params, second: "2" };
});

router.buildPath("home"); // "/home?first=1&second=2"

Zero Overhead When Empty

When no interceptors are registered, buildPath passes params through unchanged with a fast-path check. No array iteration occurs.

Affects All buildPath Call Sites

The interceptor pipeline is applied at the RouterInternals level, so it affects:

• router.buildPath() (facade method)
• URL building during wiring (NavigationDependencies.buildPath, StateDeps.buildPath)
• Any plugin code that calls buildPath via internals

Unsubscribe

const unsubscribe = api.addBuildPathInterceptor((routeName, params) => {
  return { ...params, lang: "en" };
});

router.buildPath("home"); // "/home?lang=en"

unsubscribe();

router.buildPath("home"); // "/home" — interceptor removed

Disposal Guard

Calling addBuildPathInterceptor on a disposed router throws RouterError(ROUTER_DISPOSED):

router.dispose();
api.addBuildPathInterceptor(fn); // throws RouterError(DISPOSED)

4. Possible Errors

Condition	Error	Message
Router disposed	RouterError	ROUTER_DISPOSED

5. Related Methods

Method	Difference
buildPath	The facade method that the interceptor pipeline transforms
setForwardState	Intercepts state building (navigate, matchPath), not buildPath
getForwardState	Gets current forwardState function

6. Example: Persistent Params Plugin

The persistent-params-plugin uses addBuildPathInterceptor to inject persistent query params into every URL:

const api = getPluginApi(router);

// Register interceptor — returns unsubscribe function
const removeBuildPathInterceptor = api.addBuildPathInterceptor(
  (_routeName, params) => withPersistentParams(params),
);

// In teardown: remove interceptor
return {
  teardown() {
    removeBuildPathInterceptor();
  },
};

---

Related pages: buildPath · forwardState · plugin-architecture · persistent-params-plugin · usePlugin