@tanstack/router-core 1.132.0-alpha.12 → 1.132.0-alpha.15

package/dist/esm/router.d.ts

@@ -178,6 +178,18 @@ export interface RouterOptions<TRouteTree extends AnyRoute, TTrailingSlashOption
     /**
      * The basepath for then entire router. This is useful for mounting a router instance at a subpath.
      *
+     * @deprecated - use `rewrite.input` with the new `rewriteBasepath` utility instead:
+     * ```ts
+     * const router = createRouter({
+     *   routeTree,
+     *   rewrite: rewriteBasepath('/basepath')
+     *   // Or wrap existing rewrite functionality
+     *   rewrite: rewriteBasepath('/basepath', {
+     *     output: ({ url }) => {...},
+     *     input: ({ url }) => {...},
+     *   })
+     * })
+     * ```
      * @default '/'
      * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#basepath-property)
      */
@@ -328,7 +340,41 @@ export interface RouterOptions<TRouteTree extends AnyRoute, TTrailingSlashOption
      */
     disableGlobalCatchBoundary?: boolean;
     serializationAdapters?: ReadonlyArray<AnySerializationAdapter>;
+    /**
+     * Configures how the router will rewrite the location between the actual href and the internal href of the router.
+     *
+     * @default undefined
+     * @description You can provide a custom rewrite pair (in/out) or use the utilities like `rewriteBasepath` as a convenience for common use cases, or even do both!
+     * This is useful for basepath rewriting, shifting data from the origin to the path (for things like )
+     */
+    rewrite?: LocationRewrite;
+    origin?: string;
 }
+export type LocationRewrite = {
+    /**
+     * A function that will be called to rewrite the URL before it is interpreted by the router from the history instance.
+     * Utilities like `rewriteBasepath` are provided as a convenience for common use cases.
+     *
+     * @default undefined
+     */
+    input?: LocationRewriteFunction;
+    /**
+     * A function that will be called to rewrite the URL before it is committed to the actual history instance from the router.
+     * Utilities like `rewriteBasepath` are provided as a convenience for common use cases.
+     *
+     * @default undefined
+     */
+    output?: LocationRewriteFunction;
+};
+/**
+ * A function that will be called to rewrite the URL.
+ *
+ * @param url The URL to rewrite.
+ * @returns The rewritten URL (as a URL instance or full href string) or undefined if no rewrite is needed.
+ */
+export type LocationRewriteFunction = ({ url, }: {
+    url: URL;
+}) => undefined | string | URL;
 export interface RouterState<in out TRouteTree extends AnyRoute = AnyRoute, in out TRouteMatch = MakeRouteMatchUnion> {
     status: 'pending' | 'idle';
     loadedAt: number;
@@ -495,6 +541,8 @@ export declare class RouterCore<in out TRouteTree extends AnyRoute, in out TTrai
     __store: Store<RouterState<TRouteTree>>;
     options: PickAsRequired<RouterOptions<TRouteTree, TTrailingSlashOption, TDefaultStructuralSharingOption, TRouterHistory, TDehydrated>, 'stringifySearch' | 'parseSearch' | 'context'>;
     history: TRouterHistory;
+    rewrite?: LocationRewrite;
+    origin?: string;
     latestLocation: ParsedLocation<FullSearchSchema<TRouteTree>>;
     basepath: string;
     routeTree: TRouteTree;
@@ -577,10 +625,9 @@ export declare function processRouteTree<TRouteLike extends RouteLike>({ routeTr
     routeTree: TRouteLike;
     initRoute?: (route: TRouteLike, index: number) => void;
 }): ProcessRouteTreeResult<TRouteLike>;
-export declare function getMatchedRoutes<TRouteLike extends RouteLike>({ pathname, routePathname, basepath, caseSensitive, routesByPath, routesById, flatRoutes, parseCache, }: {
+export declare function getMatchedRoutes<TRouteLike extends RouteLike>({ pathname, routePathname, caseSensitive, routesByPath, routesById, flatRoutes, parseCache, }: {
     pathname: string;
     routePathname?: string;
-    basepath: string;
     caseSensitive?: boolean;
     routesByPath: Record<string, TRouteLike>;
     routesById: Record<string, TRouteLike>;

package/dist/esm/router.js

@@ -1,8 +1,8 @@
 import { Store, batch } from "@tanstack/store";
-import { createMemoryHistory, createBrowserHistory, parseHref } from "@tanstack/history";
+import { createBrowserHistory, parseHref } from "@tanstack/history";
 import invariant from "tiny-invariant";
 import { createControlledPromise, deepEqual, replaceEqualDeep, last, findLast, functionalUpdate } from "./utils.js";
-import { trimPath, resolvePath, cleanPath, matchPathname, trimPathRight, interpolatePath, joinPaths, trimPathLeft, parsePathname, SEGMENT_TYPE_PARAM, SEGMENT_TYPE_OPTIONAL_PARAM, SEGMENT_TYPE_WILDCARD, SEGMENT_TYPE_PATHNAME } from "./path.js";
+import { resolvePath, cleanPath, trimPathRight, trimPath, matchPathname, interpolatePath, trimPathLeft, parsePathname, SEGMENT_TYPE_PARAM, SEGMENT_TYPE_OPTIONAL_PARAM, SEGMENT_TYPE_WILDCARD, SEGMENT_TYPE_PATHNAME } from "./path.js";
 import { isNotFound } from "./not-found.js";
 import { setupScrollRestoration } from "./scroll-restoration.js";
 import { defaultParseSearch, defaultStringifySearch } from "./searchParams.js";
@@ -10,6 +10,7 @@ import { rootRouteId } from "./root.js";
 import { redirect, isRedirect } from "./redirect.js";
 import { createLRUCache } from "./lru-cache.js";
 import { loadMatches, loadRouteChunk, routeNeedsPreload } from "./load-matches.js";
+import { rewriteBasepath, composeRewrites, executeRewriteInput, executeRewriteOutput } from "./rewrite.js";
 function defaultSerializeError(err) {
   if (err instanceof Error) {
     const obj = {
@@ -54,7 +55,6 @@ class RouterCore {
           "The notFoundRoute API is deprecated and will be removed in the next major version. See https://tanstack.com/router/v1/docs/framework/react/guide/not-found-errors#migrating-from-notfoundroute for more info."
         );
       }
-      const previousOptions = this.options;
       this.options = {
         ...this.options,
         ...newOptions
@@ -66,24 +66,43 @@ class RouterCore {
           char
         ])
       ) : void 0;
-      if (!this.basepath || newOptions.basepath && newOptions.basepath !== previousOptions.basepath) {
-        if (newOptions.basepath === void 0 || newOptions.basepath === "" || newOptions.basepath === "/") {
-          this.basepath = "/";
+      if (!this.history || this.options.history && this.options.history !== this.history) {
+        if (!this.options.history) {
+          if (!this.isServer) {
+            this.history = createBrowserHistory();
+          }
         } else {
-          this.basepath = `/${trimPath(newOptions.basepath)}`;
+          this.history = this.options.history;
         }
       }
-      if (!this.history || this.options.history && this.options.history !== this.history) {
-        this.history = this.options.history ?? (this.isServer ? createMemoryHistory({
-          initialEntries: [this.basepath || "/"]
-        }) : createBrowserHistory());
+      if (this.options.basepath) {
+        const basepathRewrite = rewriteBasepath({
+          basepath: this.options.basepath
+        });
+        if (this.options.rewrite) {
+          this.rewrite = composeRewrites([basepathRewrite, this.options.rewrite]);
+        } else {
+          this.rewrite = basepathRewrite;
+        }
+      } else {
+        this.rewrite = this.options.rewrite;
+      }
+      this.origin = this.options.origin;
+      if (!this.origin) {
+        if (!this.isServer) {
+          this.origin = window.origin;
+        } else {
+          this.origin = "http://localhost";
+        }
+      }
+      if (this.history) {
         this.updateLatestLocation();
       }
       if (this.options.routeTree !== this.routeTree) {
         this.routeTree = this.options.routeTree;
         this.buildRouteTree();
       }
-      if (!this.__store) {
+      if (!this.__store && this.latestLocation) {
         this.__store = new Store(getInitialRouterState(this.latestLocation), {
           onUpdate: () => {
             this.__store.state = {
@@ -147,19 +166,24 @@ class RouterCore {
     };
     this.parseLocation = (locationToParse, previousLocation) => {
       const parse = ({
-        pathname,
-        search,
-        hash,
+        href,
         state
       }) => {
-        const parsedSearch = this.options.parseSearch(search);
+        const fullUrl = new URL(href, this.origin);
+        const url = executeRewriteInput(this.rewrite, fullUrl);
+        const parsedSearch = this.options.parseSearch(url.search);
         const searchStr = this.options.stringifySearch(parsedSearch);
+        url.search = searchStr;
+        const fullPath = url.href.replace(url.origin, "");
+        const { pathname, hash } = url;
         return {
+          href: fullPath,
+          publicHref: href,
+          url: url.href,
           pathname,
           searchStr,
           search: replaceEqualDeep(previousLocation?.search, parsedSearch),
           hash: hash.split("#").reverse()[0] ?? "",
-          href: `${pathname}${searchStr}${hash}`,
           state: replaceEqualDeep(previousLocation?.state, state)
         };
       };
@@ -179,11 +203,9 @@ class RouterCore {
     };
     this.resolvePathWithBase = (from, path) => {
       const resolvedPath = resolvePath({
-        basepath: this.basepath,
         base: from,
         to: cleanPath(path),
         trailingSlash: this.options.trailingSlash,
-        caseSensitive: this.options.caseSensitive,
         parseCache: this.parsePathnameCache
       });
       return resolvedPath;
@@ -205,7 +227,6 @@ class RouterCore {
       return getMatchedRoutes({
         pathname,
         routePathname,
-        basepath: this.basepath,
         caseSensitive: this.options.caseSensitive,
         routesByPath: this.routesByPath,
         routesById: this.routesById,
@@ -313,13 +334,18 @@ class RouterCore {
         const hashStr = hash ? `#${hash}` : "";
         let nextState = dest.state === true ? currentLocation.state : dest.state ? functionalUpdate(dest.state, currentLocation.state) : {};
         nextState = replaceEqualDeep(currentLocation.state, nextState);
+        const fullPath = `${nextPathname}${searchStr}${hashStr}`;
+        const url = new URL(fullPath, this.origin);
+        const rewrittenUrl = executeRewriteOutput(this.rewrite, url);
         return {
+          publicHref: rewrittenUrl.pathname + rewrittenUrl.search + rewrittenUrl.hash,
+          href: fullPath,
+          url: rewrittenUrl.href,
           pathname: nextPathname,
           search: nextSearch,
           searchStr,
           state: nextState,
           hash: hash ?? "",
-          href: `${nextPathname}${searchStr}${hashStr}`,
           unmaskOnReload: dest.unmaskOnReload
         };
       };
@@ -330,7 +356,6 @@ class RouterCore {
           let params = {};
           const foundMask = this.options.routeMasks?.find((d) => {
             const match = matchPathname(
-              this.basepath,
               next.pathname,
               {
                 to: d.from,
@@ -391,7 +416,7 @@ class RouterCore {
         });
         return isEqual;
       };
-      const isSameUrl = this.latestLocation.href === next.href;
+      const isSameUrl = trimPathRight(this.latestLocation.href) === trimPathRight(next.href);
       const previousCommitPromise = this.commitLocationPromise;
       this.commitLocationPromise = createControlledPromise(() => {
         previousCommitPromise?.resolve();
@@ -427,7 +452,7 @@ class RouterCore {
         nextHistory.state.__hashScrollIntoViewOptions = hashScrollIntoView ?? this.options.defaultHashScrollIntoView ?? true;
         this.shouldViewTransition = viewTransition;
         this.history[next.replace ? "replace" : "push"](
-          nextHistory.href,
+          nextHistory.publicHref,
           nextHistory.state,
           { ignoreBlocker }
         );
@@ -480,7 +505,7 @@ class RouterCore {
       if (reloadDocument) {
         if (!href) {
           const location = this.buildLocation({ to, ...rest });
-          href = this.history.createHref(location.href);
+          href = location.href;
         }
         if (rest.replace) {
           window.location.replace(href);
@@ -827,7 +852,6 @@ class RouterCore {
       const pending = opts?.pending === void 0 ? !this.state.isLoading : opts.pending;
       const baseLocation = pending ? this.latestLocation : this.state.resolvedLocation || this.state.location;
       const match = matchPathname(
-        this.basepath,
         baseLocation.pathname,
         {
           ...opts,
@@ -1005,7 +1029,7 @@ class RouterCore {
           routeId: route.id,
           params: previousMatch ? replaceEqualDeep(previousMatch.params, routeParams) : routeParams,
           _strictParams: usedParams,
-          pathname: joinPaths([this.basepath, interpolatedPath]),
+          pathname: interpolatedPath,
           updatedAt: Date.now(),
           search: previousMatch ? replaceEqualDeep(previousMatch.search, preMatchSearch) : preMatchSearch,
           _strictSearch: strictMatchSearch,
@@ -1257,7 +1281,6 @@ function processRouteTree({
 function getMatchedRoutes({
   pathname,
   routePathname,
-  basepath,
   caseSensitive,
   routesByPath,
   routesById,
@@ -1268,7 +1291,6 @@ function getMatchedRoutes({
   const trimmedPath = trimPathRight(pathname);
   const getMatchedParams = (route) => {
     const result = matchPathname(
-      basepath,
       trimmedPath,
       {
         to: route.fullPath,