feat(mosaic): add MosaicRoutingProvider and useMosaicRoutes

[alexcarpenter]

Description

Adds internal routing for Mosaic, loosely modeled on nanostores/router. MosaicRoutingProvider decides where the route lives (the path, the hash, or memory). useMosaicRoutes gives controllers a typed route table.

Provider

<MosaicRoutingProvider routing='path' path='/user-profile'>…</MosaicRoutingProvider>
<MosaicRoutingProvider routing='hash'>…</MosaicRoutingProvider>
<MosaicRoutingProvider routing='memory' initialPath='security'>…</MosaicRoutingProvider>

• path: the URL under a base path, navigated through clerk.navigate as an internal navigation.
• hash: #/…, never calls the host router (Chrome extension, Electron).
• memory: never touches the URL (modals). This is also the default with no provider.

Routes in a controller

const { route, params, search, go } = useMosaicRoutes({
  index: '',
  security: 'security',
  statement: 'billing/statement/:statementId',
});

go('statement', { statementId: 'st_1' });
go('security', {}, { replace: true, search: { tab: 'passkeys' } });
go('statement'); // type error: statementId is required

For a full example (a profile-style controller and view under each mode), see routing/__tests__/usage.test.tsx.

Carries over the legacy router's behavior: waits for the host navigation and then commits with flushSync, converts #/… URLs to paths on mount, ignores URL changes outside the base path or during its own navigation, drops a repeat of a navigation that's already in flight, and keeps PRESERVED_QUERYSTRING_PARAMS across moves. Nothing touches window at import time, so it's safe for SSR and native.

Gaps

• Not exported from @clerk/mosaic, and no component uses it yet.
• No nested route scopes, so it can't yet serve sign-in/sign-up flows or modal subflows.
• No href for building links.
• On the server it resolves to the initial route.
• Only tested in jsdom, not yet run in a real Next.js app.

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:

[vercel]

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

Project	Deployment	Actions	Updated
swingset	Ready	Preview	Sep 21, 2026 7:20pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
clerk-js-sandbox	Skipped		Sep 21, 2026 7:20pm UTC

[changeset-bot]

🦋 Changeset detected

Latest commit: 794dd96

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

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

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]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@9843

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@9843

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@9843

@clerk/expo

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

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@9843

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@9843

@clerk/localizations

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

@clerk/mosaic

npm i https://pkg.pr.new/@clerk/mosaic@9843

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 794dd96