fix(electron,shared,ui): keep Clerk navigation inside the Electron renderer

[jeremy-clerk]

Description

When an Electron app supplied no routerPush/routerReplace, clerk-js fell back to a
window.location navigation. Additional sign-in/up steps target the internal component router
(/CLERK-ROUTER/VIRTUAL/...), and a renderer served from a custom scheme would often result in navigation reloading the whole renderer, unmounting Clerk and breaking the auth flow.

This PR makes ClerkProvider always supply a routerPush/routerReplace:

• internal virtual routers are now absorbed.
• Real destinations go to the application's router when one is provided, otherwise fall back to
  host navigation, preserving current behavior for apps that supply no router.

isVirtualRouterPath moves to @clerk/shared so @clerk/electron and @clerk/ui share one
definition; @clerk/ui re-exports VIRTUAL_ROUTER_BASE_PATH unchanged.

The electron-vite integration template passed no-op router functions to work around this, which
also swallowed real destinations. Those are removed, and the suite now asserts that no
clerk:beforeunload fires during sign-in, as that event is dispatched immediately before clerk-js
assigns window.location.

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

[changeset-bot]

🦋 Changeset detected

Latest commit: 5fac41b

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

This PR includes changesets to release 23 packages

Name	Type
@clerk/electron	Patch
@clerk/shared	Patch
@clerk/ui	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/headless	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/react	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/vue	Patch
@clerk/swingset	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

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Aug 23, 2026 12:15am
swingset	Building	Preview	Aug 23, 2026 12:15am

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: d3e04910-f349-44ad-a871-ed69c2dddcce

📥 Commits

Reviewing files that changed from the base of the PR and between e21ae9a and 5fac41b.

📒 Files selected for processing (7)

• .changeset/electron-virtual-router-navigation.md
• integration/templates/electron-vite/src/main.tsx
• integration/tests/electron/basic.test.ts
• packages/electron/src/react/__tests__/ClerkProvider.test.tsx
• packages/electron/src/react/index.tsx
• packages/shared/src/internal/clerk-js/url.ts
• packages/ui/src/router/VirtualRouter.tsx

Disabled knowledge base sources:

• Linear integration is disabled

You can enable these sources in your CodeRabbit configuration.

---

📝 Walkthrough

Walkthrough

Electron ClerkProvider now always supplies routerPush and routerReplace handlers. The handlers ignore virtual router paths, delegate real destinations to application router callbacks, or use host navigation. Shared virtual-router path detection is re-exported by the UI router. Integration and unit tests cover the navigation behavior. The Electron template removes no-op router callbacks, and a changeset documents the update.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested reviewers: wobsoriano

---

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

[github-actions]

API Changes Report

Generated by Break Check on 2026-08-23T00:18:23.253Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	1
🔴 Breaking changes	0
🟡 Non-breaking changes	0
🟢 Additions	2

---

@clerk/shared

Current version: 4.29.3
Recommended bump: MINOR → 4.30.0

Subpath ./internal/clerk-js/url

🟢 Additions (2)

Added: isVirtualRouterPath

+ isVirtualRouterPath: (to: string) => boolean

Added function isVirtualRouterPath

Added: VIRTUAL_ROUTER_BASE_PATH

+ VIRTUAL_ROUTER_BASE_PATH = "CLERK-ROUTER/VIRTUAL"

Added variable VIRTUAL_ROUTER_BASE_PATH

---

Report generated by Break Check

_{Last ran on 5fac41b.}