fix(tanstack-react-start): Parse URL query params for TanStack Router navigation

[nikosdouvlis]

Summary

TanStack Router's navigate() function doesn't parse query strings from the to parameter. It expects:

• to: pathname only (e.g., /sign-in)
• search: object with query parameters (e.g., { redirect_url: '...' })
• hash: fragment string without #

Previously, Clerk's routerPush and routerReplace were passing the full URL string (e.g., /sign-in?redirect_url=...) directly to to, which TanStack Router tried to match as a literal route name, causing "Not Found" errors.

This affected satellite domain authentication flows and any Clerk navigation that includes query parameters.

Changes

• Added parseUrlForNavigation() utility that extracts pathname, search params, and hash from a URL string
• Updated routerPush and routerReplace in ClerkProvider to use the new parsing function
• Added comprehensive tests for the URL parsing logic

Test plan

• Unit tests for parseUrlForNavigation covering various URL formats
• Build passes
• Lint passes
• Manual testing on satellite domain flow (to be done by reporter)

Summary by CodeRabbit

• Bug Fixes

  • Fixed navigation errors with URLs containing query parameters in TanStack Start apps. Query strings in redirect URLs (e.g., /sign-in?redirect_url=...) are now properly handled and no longer cause "Not Found" errors.

• Tests

  • Added comprehensive unit tests for URL navigation parsing.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Feb 3, 2026 10:59am

[changeset-bot]

🦋 Changeset detected

Latest commit: fbedee4

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@clerk/tanstack-react-start	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request introduces a fix for URL navigation with query parameters in TanStack Start applications. The change adds a new utility function parseUrlForNavigation that parses URLs and separates the pathname, search parameters, and hash components. The ClerkProvider is updated to use this utility when invoking TanStack Router's navigate function. Comprehensive unit tests are added to validate the parsing behavior across various URL formats. A changeset entry documents the fix for the @clerk/tanstack-react-start package.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main fix: parsing URL query parameters for TanStack Router navigation, which directly addresses the core problem solved by this changeset.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7741

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@7741

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@7741

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@7741

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@7741

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@7741

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@7741

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@7741

@clerk/express

npm i https://pkg.pr.new/@clerk/express@7741

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@7741

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@7741

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@7741

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@7741

@clerk/react

npm i https://pkg.pr.new/@clerk/react@7741

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@7741

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@7741

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@7741

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@7741

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@7741

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@7741

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@7741

commit: fbedee4

[wobsoriano]

Thanks! This should fix #7362 right?

[paperclover]

great work, would really like to see this merged soon so our team can stop patching the clerk dependency.

[paperclover]

no, this does not fix #7362. i applied the patch manually to the dist/ output and i am noticing routerPush is called with "/signup#/?redirect_url=http%3A%2F%2Flocalhost%3A3000%2F"