feat: start support for tanstack in @clerk/elements

packages/elements/package.json

@@ -86,6 +86,7 @@
   },
   "devDependencies": {
     "@statelyai/inspect": "^0.4.0",
+    "@tanstack/react-router": "1.131.49",
     "concurrently": "^9.2.1",
     "next": "14.2.33"
   },

packages/elements/src/react/router/tanstack.ts

@@ -0,0 +1,48 @@
+import type { ClerkHostRouter } from '@clerk/types';
+import { useRouter } from '@tanstack/react-router';
+
+import { usePathnameWithoutCatchAll } from '../utils/path-inference/tanstack';
+
+/**
+ * Clerk Elements router integration hook for TanStack Router.
+ *
+ * Provides a standardized router interface (`ClerkHostRouter`) that Clerk Elements
+ * can use to navigate and read URL state within a TanStack Router application.
+ *
+ * @returns A `ClerkHostRouter` object with navigation methods (`push`, `replace`, `shallowPush`),
+ * URL state accessors (`pathname`, `searchParams`), and path inference (`inferredBasePath`).
+ *
+ * @example
+ * ```tsx
+ * import { useTanStackRouter } from '@clerk/elements/tanstack';
+ *
+ * function MyComponent() {
+ *   const router = useTanStackRouter();
+ *   // Clerk Elements will use this router for navigation
+ * }
+ * ```
+ *
+ * @remarks
+ * - Requires TanStack Router v1.x+ to be installed and configured in your application.
+ * - The hook must be called within a TanStack Router context (inside a `<RouterProvider>`).
+ */
+export const useTanStackRouter = (): ClerkHostRouter => {
+  const router = useRouter();
+  const pathname = router.location.pathname;
+  const searchString = router.location.search;
+  const inferredBasePath = usePathnameWithoutCatchAll(); //
+  const getSearchParams = () => new URLSearchParams(searchString);
+
+  return {
+    mode: 'path',
+    name: 'TanStackRouter',
+    push: (path: string) => router.navigate({ to: path }),
+    replace: (path: string) => router.navigate({ to: path, replace: true }),
+    shallowPush: (path: string) =>
+      // In TanStack Router, all navigations are already shallow by default.
+      router.navigate({ to: path }),
+    pathname: () => pathname,
+    searchParams: () => getSearchParams(),
+    inferredBasePath: () => inferredBasePath,
+  };
+};

packages/elements/src/react/utils/path-inference/tanstack.tsx

@@ -0,0 +1,40 @@
+import { useParams, useRouter } from '@tanstack/react-router';
+import React from 'react';
+
+import { removeOptionalCatchAllSegment } from './utils';
+
+/**
+ * This hook grabs the current pathname and removes any (optional) catch-all segments.
+ * Adapted from Next.js App Router logic for TanStack Router.
+ * @example
+ * Route: /user/$[id]/profile/$[...rest] (or file: user.[id].profile.[[...rest]].tsx)
+ * Pathname: /user/123/profile/security
+ * Params: { id: '123', rest: ['security'] }
+ * Returns: /user/123/profile
+ * @returns The pathname without any catch-all segments
+ */
+export const usePathnameWithoutCatchAll = (): string => {
+  const router = useRouter();
+
+  const pathname = router?.location.pathname || '';
+  const params = useParams() as Record<string, string | string[] | undefined>;
+
+  return React.useMemo(() => {
+    const processedPath = removeOptionalCatchAllSegment(pathname);
+    const pathParts = processedPath.split('/').filter(Boolean);
+    const catchAllParams = Object.values(params || {})
+      .filter((v): v is string[] => Array.isArray(v))
+      .flat(Infinity);
+
+    if (!pathname || catchAllParams.length === 0) {
+      return pathname.replace(/\/$/, '') || '/';
+    }
+
+    // Slice off the trailing segments matching the catch-all length
+    // E.g., pathParts = ['user', '123', 'profile', 'security'], length=1 → slice(0, 3) = /user/123/profile
+    const baseParts = pathParts.slice(0, pathParts.length - catchAllParams.length);
+    const basePath = `/${baseParts.join('/')}`;
+
+    return basePath.replace(/\/$/, '') || '/';
+  }, [pathname, params]);
+};