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

package/src/index.ts

@@ -103,7 +103,6 @@ export {
   parsePathname,
   interpolatePath,
   matchPathname,
-  removeBasepath,
   matchByPath,
 } from './path'
 export type { Segment } from './path'
@@ -432,3 +431,11 @@ export {
 } from './ssr/serializer/transformer'
 
 export { defaultSerovalPlugins } from './ssr/serializer/seroval-plugins'
+
+export {
+  rewriteBasepath,
+  composeRewrites,
+  executeRewriteInput,
+  executeRewriteOutput,
+} from './rewrite'
+export type { LocationRewrite, LocationRewriteFunction } from './router'

package/src/location.ts

@@ -2,12 +2,50 @@ import type { ParsedHistoryState } from '@tanstack/history'
 import type { AnySchema } from './validators'
 
 export interface ParsedLocation<TSearchObj extends AnySchema = {}> {
+  /**
+   * The full path of the location, including pathname, search, and hash.
+   * Does not include the origin. Is the equivalent of calling
+   * `url.replace(url.origin, '')`
+   */
   href: string
+  /**
+   * @description The pathname of the location, including the leading slash.
+   */
   pathname: string
+  /**
+   * The parsed search parameters of the location in object form.
+   */
   search: TSearchObj
+  /**
+   * The search string of the location, including the leading question mark.
+   */
   searchStr: string
+  /**
+   * The in-memory state of the location as it *may* exist in the browser's history.
+   */
   state: ParsedHistoryState
+  /**
+   * The hash of the location, including the leading hash character.
+   */
   hash: string
+  /**
+   * The masked location of the location.
+   */
   maskedLocation?: ParsedLocation<TSearchObj>
+  /**
+   * Whether to unmask the location on reload.
+   */
   unmaskOnReload?: boolean
+  /**
+   * @private
+   * @description The public href of the location, including the origin before any rewrites.
+   * If a rewrite is applied, the `href` property will be the rewritten URL.
+   */
+  publicHref: string
+  /**
+   * @private
+   * @description The full URL of the location, including the origin.
+   * @private
+   */
+  url: string
 }

package/src/path.ts

@@ -97,11 +97,9 @@ export function exactPathTest(
 // /a/b/c + d/ = /a/b/c/d
 // /a/b/c + d/e = /a/b/c/d/e
 interface ResolvePathOptions {
-  basepath: string
   base: string
   to: string
   trailingSlash?: 'always' | 'never' | 'preserve'
-  caseSensitive?: boolean
   parseCache?: ParsePathnameCache
 }
 
@@ -151,16 +149,11 @@ function segmentToString(segment: Segment): string {
 }
 
 export function resolvePath({
-  basepath,
   base,
   to,
   trailingSlash = 'never',
-  caseSensitive,
   parseCache,
 }: ResolvePathOptions) {
-  base = removeBasepath(basepath, base, caseSensitive)
-  to = removeBasepath(basepath, to, caseSensitive)
-
   let baseSegments = parsePathname(base, parseCache).slice()
   const toSegments = parsePathname(to, parseCache)
 
@@ -201,7 +194,8 @@ export function resolvePath({
   }
 
   const segmentValues = baseSegments.map(segmentToString)
-  const joined = joinPaths([basepath, ...segmentValues])
+  // const joined = joinPaths([basepath, ...segmentValues])
+  const joined = joinPaths(segmentValues)
   return joined
 }
 
@@ -491,17 +485,11 @@ function encodePathParam(value: string, decodeCharMap?: Map<string, string>) {
 }
 
 export function matchPathname(
-  basepath: string,
   currentPathname: string,
   matchLocation: Pick<MatchLocation, 'to' | 'fuzzy' | 'caseSensitive'>,
   parseCache?: ParsePathnameCache,
 ): AnyPathParams | undefined {
-  const pathParams = matchByPath(
-    basepath,
-    currentPathname,
-    matchLocation,
-    parseCache,
-  )
+  const pathParams = matchByPath(currentPathname, matchLocation, parseCache)
   // const searchMatched = matchBySearch(location.search, matchLocation)
 
   if (matchLocation.to && !pathParams) {
@@ -511,49 +499,7 @@ export function matchPathname(
   return pathParams ?? {}
 }
 
-export function removeBasepath(
-  basepath: string,
-  pathname: string,
-  caseSensitive: boolean = false,
-) {
-  // normalize basepath and pathname for case-insensitive comparison if needed
-  const normalizedBasepath = caseSensitive ? basepath : basepath.toLowerCase()
-  const normalizedPathname = caseSensitive ? pathname : pathname.toLowerCase()
-
-  switch (true) {
-    // default behaviour is to serve app from the root - pathname
-    // left untouched
-    case normalizedBasepath === '/':
-      return pathname
-
-    // shortcut for removing the basepath if it matches the pathname
-    case normalizedPathname === normalizedBasepath:
-      return ''
-
-    // in case pathname is shorter than basepath - there is
-    // nothing to remove
-    case pathname.length < basepath.length:
-      return pathname
-
-    // avoid matching partial segments - strict equality handled
-    // earlier, otherwise, basepath separated from pathname with
-    // separator, therefore lack of separator means partial
-    // segment match (`/app` should not match `/application`)
-    case normalizedPathname[normalizedBasepath.length] !== '/':
-      return pathname
-
-    // remove the basepath from the pathname if it starts with it
-    case normalizedPathname.startsWith(normalizedBasepath):
-      return pathname.slice(basepath.length)
-
-    // otherwise, return the pathname as is
-    default:
-      return pathname
-  }
-}
-
 export function matchByPath(
-  basepath: string,
   from: string,
   {
     to,
@@ -562,14 +508,7 @@ export function matchByPath(
   }: Pick<MatchLocation, 'to' | 'caseSensitive' | 'fuzzy'>,
   parseCache?: ParsePathnameCache,
 ): Record<string, string> | undefined {
-  // check basepath first
-  if (basepath !== '/' && !from.startsWith(basepath)) {
-    return undefined
-  }
-  // Remove the base path from the pathname
-  from = removeBasepath(basepath, from, caseSensitive)
-  // Default to to $ (wildcard)
-  to = removeBasepath(basepath, `${to ?? '$'}`, caseSensitive)
+  const stringTo = to as string
 
   // Parse the from and to
   const baseSegments = parsePathname(
@@ -577,7 +516,7 @@ export function matchByPath(
     parseCache,
   )
   const routeSegments = parsePathname(
-    to.startsWith('/') ? to : `/${to}`,
+    stringTo.startsWith('/') ? stringTo : `/${stringTo}`,
     parseCache,
   )
 

package/src/rewrite.ts

@@ -0,0 +1,70 @@
+import { joinPaths, trimPath } from './path'
+import type { LocationRewrite } from './router'
+
+export function composeRewrites(rewrites: Array<LocationRewrite>) {
+  return {
+    input: ({ url }) => {
+      for (const rewrite of rewrites) {
+        url = executeRewriteInput(rewrite, url)
+      }
+      return url
+    },
+    output: ({ url }) => {
+      for (let i = rewrites.length - 1; i >= 0; i--) {
+        url = executeRewriteOutput(rewrites[i], url)
+      }
+      return url
+    },
+  } satisfies LocationRewrite
+}
+
+export function rewriteBasepath(opts: {
+  basepath: string
+  caseSensitive?: boolean
+}) {
+  const trimmedBasepath = trimPath(opts.basepath)
+  const regex = new RegExp(
+    `^/${trimmedBasepath}/`,
+    opts.caseSensitive ? '' : 'i',
+  )
+  return {
+    input: ({ url }) => {
+      url.pathname = url.pathname.replace(regex, '/')
+      return url
+    },
+    output: ({ url }) => {
+      url.pathname = joinPaths(['/', trimmedBasepath, url.pathname])
+      return url
+    },
+  } satisfies LocationRewrite
+}
+
+export function executeRewriteInput(
+  rewrite: LocationRewrite | undefined,
+  url: URL,
+): URL {
+  const res = rewrite?.input?.({ url })
+  if (res) {
+    if (typeof res === 'string') {
+      return new URL(res)
+    } else if (res instanceof URL) {
+      return res
+    }
+  }
+  return url
+}
+
+export function executeRewriteOutput(
+  rewrite: LocationRewrite | undefined,
+  url: URL,
+): URL {
+  const res = rewrite?.output?.({ url })
+  if (res) {
+    if (typeof res === 'string') {
+      return new URL(res)
+    } else if (res instanceof URL) {
+      return res
+    }
+  }
+  return url
+}

package/src/router.ts

@@ -1,9 +1,5 @@
 import { Store, batch } from '@tanstack/store'
-import {
-  createBrowserHistory,
-  createMemoryHistory,
-  parseHref,
-} from '@tanstack/history'
+import { createBrowserHistory, parseHref } from '@tanstack/history'
 import invariant from 'tiny-invariant'
 import {
   createControlledPromise,
@@ -20,7 +16,6 @@ import {
   SEGMENT_TYPE_WILDCARD,
   cleanPath,
   interpolatePath,
-  joinPaths,
   matchPathname,
   parsePathname,
   resolvePath,
@@ -35,6 +30,12 @@ import { rootRouteId } from './root'
 import { isRedirect, redirect } from './redirect'
 import { createLRUCache } from './lru-cache'
 import { loadMatches, loadRouteChunk, routeNeedsPreload } from './load-matches'
+import {
+  composeRewrites,
+  executeRewriteInput,
+  executeRewriteOutput,
+  rewriteBasepath,
+} from './rewrite'
 import type { ParsePathnameCache, Segment } from './path'
 import type { SearchParser, SearchSerializer } from './searchParams'
 import type { AnyRedirect, ResolvedRedirect } from './redirect'
@@ -271,6 +272,18 @@ export interface RouterOptions<
   /**
    * 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)
    */
@@ -438,8 +451,46 @@ export interface RouterOptions<
   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,
@@ -810,7 +861,10 @@ export class RouterCore<
     'stringifySearch' | 'parseSearch' | 'context'
   >
   history!: TRouterHistory
+  rewrite?: LocationRewrite
+  origin?: string
   latestLocation!: ParsedLocation<FullSearchSchema<TRouteTree>>
+  // @deprecated - basepath functionality is now implemented via the `rewrite` option
   basepath!: string
   routeTree!: TRouteTree
   routesById!: RoutesById<TRouteTree>
@@ -874,7 +928,6 @@ export class RouterCore<
       )
     }
 
-    const previousOptions = this.options
     this.options = {
       ...this.options,
       ...newOptions,
@@ -892,31 +945,41 @@ export class RouterCore<
       : undefined
 
     if (
-      !this.basepath ||
-      (newOptions.basepath && newOptions.basepath !== previousOptions.basepath)
+      !this.history ||
+      (this.options.history && this.options.history !== this.history)
     ) {
-      if (
-        newOptions.basepath === undefined ||
-        newOptions.basepath === '' ||
-        newOptions.basepath === '/'
-      ) {
-        this.basepath = '/'
+      if (!this.options.history) {
+        if (!this.isServer) {
+          this.history = createBrowserHistory() as TRouterHistory
+        }
       } else {
-        this.basepath = `/${trimPath(newOptions.basepath)}`
+        this.history = this.options.history
       }
     }
+    // For backwards compatibility, we support a basepath option, which we now implement as a rewrite
+    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
+    }
 
-    if (
-      !this.history ||
-      (this.options.history && this.options.history !== this.history)
-    ) {
-      this.history =
-        this.options.history ??
-        ((this.isServer
-          ? createMemoryHistory({
-              initialEntries: [this.basepath || '/'],
-            })
-          : createBrowserHistory()) as TRouterHistory)
+    this.origin = this.options.origin
+    if (!this.origin) {
+      if (!this.isServer) {
+        this.origin = window.origin
+      } else {
+        // fallback for the server, can be overridden by calling router.update({origin}) on the server
+        this.origin = 'http://localhost'
+      }
+    }
+    if (this.history) {
       this.updateLatestLocation()
     }
 
@@ -925,7 +988,7 @@ export class RouterCore<
       this.buildRouteTree()
     }
 
-    if (!this.__store) {
+    if (!this.__store && this.latestLocation) {
       this.__store = new Store(getInitialRouterState(this.latestLocation), {
         onUpdate: () => {
           this.__store.state = {
@@ -1012,20 +1075,32 @@ export class RouterCore<
     previousLocation,
   ) => {
     const parse = ({
-      pathname,
-      search,
-      hash,
+      href,
       state,
     }: HistoryLocation): ParsedLocation<FullSearchSchema<TRouteTree>> => {
-      const parsedSearch = this.options.parseSearch(search)
+      // Before we do any processing, we need to allow rewrites to modify the URL
+      // build up the full URL by combining the href from history with the router's origin
+      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)
+      // Make sure our final url uses the re-stringified pathname, search, and has for consistency
+      // (We were already doing this, so just keeping it for now)
+      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) as any,
         hash: hash.split('#').reverse()[0] ?? '',
-        href: `${pathname}${searchStr}${hash}`,
         state: replaceEqualDeep(previousLocation?.state, state),
       }
     }
@@ -1053,11 +1128,9 @@ export class RouterCore<
 
   resolvePathWithBase = (from: string, path: string) => {
     const resolvedPath = resolvePath({
-      basepath: this.basepath,
       base: from,
       to: cleanPath(path),
       trailingSlash: this.options.trailingSlash,
-      caseSensitive: this.options.caseSensitive,
       parseCache: this.parsePathnameCache,
     })
     return resolvedPath
@@ -1289,7 +1362,7 @@ export class RouterCore<
             ? replaceEqualDeep(previousMatch.params, routeParams)
             : routeParams,
           _strictParams: usedParams,
-          pathname: joinPaths([this.basepath, interpolatedPath]),
+          pathname: interpolatedPath,
           updatedAt: Date.now(),
           search: previousMatch
             ? replaceEqualDeep(previousMatch.search, preMatchSearch)
@@ -1394,7 +1467,6 @@ export class RouterCore<
     return getMatchedRoutes({
       pathname,
       routePathname,
-      basepath: this.basepath,
       caseSensitive: this.options.caseSensitive,
       routesByPath: this.routesByPath,
       routesById: this.routesById,
@@ -1583,14 +1655,25 @@ export class RouterCore<
       // Replace the equal deep
       nextState = replaceEqualDeep(currentLocation.state, nextState)
 
-      // Return the next location
+      // Create the full path of the location
+      const fullPath = `${nextPathname}${searchStr}${hashStr}`
+
+      // Create the new href with full origin
+      const url = new URL(fullPath, this.origin)
+
+      // If a rewrite function is provided, use it to rewrite the URL
+      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 as any,
         hash: hash ?? '',
-        href: `${nextPathname}${searchStr}${hashStr}`,
         unmaskOnReload: dest.unmaskOnReload,
       }
     }
@@ -1608,7 +1691,6 @@ export class RouterCore<
 
         const foundMask = this.options.routeMasks?.find((d) => {
           const match = matchPathname(
-            this.basepath,
             next.pathname,
             {
               to: d.from,
@@ -1638,8 +1720,7 @@ export class RouterCore<
       }
 
       if (maskedNext) {
-        const maskedFinal = build(maskedDest)
-        next.maskedLocation = maskedFinal
+        next.maskedLocation = maskedNext
       }
 
       return next
@@ -1682,7 +1763,8 @@ export 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<void>(() => {
@@ -1731,7 +1813,7 @@ export class RouterCore<
       this.shouldViewTransition = viewTransition
 
       this.history[next.replace ? 'replace' : 'push'](
-        nextHistory.href,
+        nextHistory.publicHref,
         nextHistory.state,
         { ignoreBlocker },
       )
@@ -1793,7 +1875,7 @@ export class RouterCore<
     if (reloadDocument) {
       if (!href) {
         const location = this.buildLocation({ to, ...rest } as any)
-        href = this.history.createHref(location.href)
+        href = location.href
       }
       if (rest.replace) {
         window.location.replace(href)
@@ -1846,6 +1928,7 @@ export class RouterCore<
         throw redirect({ href: nextLocation.href })
       }
     }
+
     // Match the routes
     const pendingMatches = this.matchRoutes(this.latestLocation)
 
@@ -1991,6 +2074,7 @@ export class RouterCore<
           this.latestLoadPromise = undefined
           this.commitLocationPromise = undefined
         }
+
         resolve()
       })
     })
@@ -2289,7 +2373,6 @@ export class RouterCore<
       : this.state.resolvedLocation || this.state.location
 
     const match = matchPathname(
-      this.basepath,
       baseLocation.pathname,
       {
         ...opts,
@@ -2625,7 +2708,6 @@ export function processRouteTree<TRouteLike extends RouteLike>({
 export function getMatchedRoutes<TRouteLike extends RouteLike>({
   pathname,
   routePathname,
-  basepath,
   caseSensitive,
   routesByPath,
   routesById,
@@ -2634,7 +2716,6 @@ export function getMatchedRoutes<TRouteLike extends RouteLike>({
 }: {
   pathname: string
   routePathname?: string
-  basepath: string
   caseSensitive?: boolean
   routesByPath: Record<string, TRouteLike>
   routesById: Record<string, TRouteLike>
@@ -2645,7 +2726,6 @@ export function getMatchedRoutes<TRouteLike extends RouteLike>({
   const trimmedPath = trimPathRight(pathname)
   const getMatchedParams = (route: TRouteLike) => {
     const result = matchPathname(
-      basepath,
       trimmedPath,
       {
         to: route.fullPath,