fix(nextjs,clerk-js,types): Stop Clerk component flickering when used in App Router

.changeset/olive-files-listen.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/nextjs': patch
+'@clerk/types': patch
+---
+
+Prevent Clerk component flickering when mounted in a Next.js app using App Router

packages/clerk-js/src/core/clerk.redirects.test.ts

@@ -126,56 +126,56 @@ describe('Clerk singleton - Redirects', () => {
  await clerkForProductionInstance.redirectToSignIn({ redirectUrl: 'https://www.example.com/' });
  await clerkForDevelopmentInstance.redirectToSignIn({ redirectUrl: 'https://www.example.com/' });
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
  });
 
  it('redirects to signUpUrl', async () => {
  await clerkForProductionInstance.redirectToSignUp({ redirectUrl: 'https://www.example.com/' });
  await clerkForDevelopmentInstance.redirectToSignUp({ redirectUrl: 'https://www.example.com/' });
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
  });
 
  it('redirects to userProfileUrl', async () => {
  await clerkForProductionInstance.redirectToUserProfile();
  await clerkForDevelopmentInstance.redirectToUserProfile();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/user-profile');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/user-profile');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/user-profile');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/user-profile');
  });
 
  it('redirects to afterSignUp', async () => {
  await clerkForProductionInstance.redirectToAfterSignUp();
  await clerkForDevelopmentInstance.redirectToAfterSignUp();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/');
  });
 
  it('redirects to afterSignIn', async () => {
  await clerkForProductionInstance.redirectToAfterSignIn();
  await clerkForDevelopmentInstance.redirectToAfterSignIn();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/');
  });
 
  it('redirects to create organization', async () => {
  await clerkForProductionInstance.redirectToCreateOrganization();
  await clerkForDevelopmentInstance.redirectToCreateOrganization();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/create-organization');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/create-organization');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/create-organization');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/create-organization');
  });
 
  it('redirects to organization profile', async () => {
  await clerkForProductionInstance.redirectToOrganizationProfile();
  await clerkForDevelopmentInstance.redirectToOrganizationProfile();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/organization-profile');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/organization-profile');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/organization-profile');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/organization-profile');
  });
  });
 

packages/clerk-js/src/core/clerk.test.ts

@@ -571,7 +571,7 @@ describe('Clerk singleton', () => {
  const res = sut.navigate(toUrl);
  expect(res.then).toBeDefined();
  expect(mockHref).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith('/path#hash');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/path#hash');
  expect(logSpy).not.toBeCalled();
  });
 
@@ -591,7 +591,7 @@ describe('Clerk singleton', () => {
  const res = sut.navigate(toUrl);
  expect(res.then).toBeDefined();
  expect(mockHref).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith('/path#hash');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/path#hash');
 
  expect(logSpy).toBeCalledTimes(1);
  expect(logSpy).toBeCalledWith(`Clerk is navigating to: ${toUrl}`);
@@ -721,7 +721,7 @@ describe('Clerk singleton', () => {
 
  await waitFor(() => {
  expect(mockSignUpCreate).toHaveBeenCalledWith({ transfer: true });
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up#/continue');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/continue');
  });
  });
 
@@ -934,7 +934,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/factor-two');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/factor-two');
  });
  });
 
@@ -977,7 +977,7 @@ describe('Clerk singleton', () => {
  });
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/custom-2fa');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/custom-2fa');
  });
  });
 
@@ -1032,7 +1032,7 @@ describe('Clerk singleton', () => {
  });
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/custom-sign-in');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/custom-sign-in');
  });
  });
 
@@ -1088,7 +1088,7 @@ describe('Clerk singleton', () => {
  } as any);
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/custom-sign-in');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/custom-sign-in');
  });
  });
 
@@ -1136,7 +1136,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up');
  });
  });
 
@@ -1184,7 +1184,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up');
  });
  });
 
@@ -1226,7 +1226,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up#/continue');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/continue');
  });
  });
 
@@ -1273,7 +1273,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up#/verify-email-address');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/verify-email-address');
  });
  });
 
@@ -1305,7 +1305,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/factor-one');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/factor-one');
  });
  });
 
@@ -1353,7 +1353,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/factor-one');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/factor-one');
  });
  });
 
@@ -1412,7 +1412,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up');
  });
  });
 
@@ -1463,7 +1463,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in');
  });
  });
 
@@ -1501,7 +1501,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/reset-password');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/reset-password');
  });
  });
  });
@@ -1568,7 +1568,7 @@ describe('Clerk singleton', () => {
 
  await waitFor(() => {
  expect(mockSetActive).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith(redirectUrl);
+ expect(mockNavigate.mock.calls[0][0]).toBe(redirectUrl);
  });
  });
 
@@ -1628,7 +1628,7 @@ describe('Clerk singleton', () => {
 
  await waitFor(() => {
  expect(mockSetActive).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith(redirectUrl);
+ expect(mockNavigate.mock.calls[0][0]).toBe(redirectUrl);
  });
  });
 

packages/clerk-js/src/core/clerk.ts

@@ -726,8 +726,9 @@ export class Clerk implements ClerkInterface {
  return;
  }
 
+ const metadata = options?.metadata ? { __internal_metadata: options?.metadata } : undefined;
  // React router only wants the path, search or hash portion.
- return await customNavigate(stripOrigin(toURL));
+ return await customNavigate(stripOrigin(toURL), metadata);
  };
 
  public buildUrlWithAuth(to: string): string {

packages/clerk-js/src/ui/router/BaseRouter.tsx

@@ -1,4 +1,5 @@
 import { useClerk } from '@clerk/shared/react';
+import type { NavigateOptions } from '@clerk/types';
 import qs from 'qs';
 import React from 'react';
 
@@ -14,7 +15,7 @@ interface BaseRouterProps {
  startPath: string;
  getPath: () => string;
  getQueryString: () => string;
- internalNavigate: (toURL: URL) => Promise<any> | any;
+ internalNavigate: (toURL: URL, options?: NavigateOptions) => Promise<any> | any;
  onExternalNavigate?: () => any;
  refreshEvents?: Array<keyof WindowEventMap>;
  preservedParams?: string[];
@@ -114,7 +115,7 @@ export const BaseRouter = ({
  });
  toURL.search = qs.stringify(toQueryParams);
  }
- const internalNavRes = await internalNavigate(toURL);
+ const internalNavRes = await internalNavigate(toURL, { metadata: { navigationType: 'internal' } });
  setRouteParts({ path: toURL.pathname, queryString: toURL.search });
  return internalNavRes;
  };

packages/nextjs/src/app-router/client/useAwaitableNavigate.ts

@@ -3,7 +3,7 @@
 import { useRouter } from 'next/navigation';
 import { useEffect, useRef, useTransition } from 'react';
 
-type NavigateFunction = ReturnType<typeof useRouter>['push'];
+import type { NextClerkProviderProps } from '../../types';
 
 /**
  * Creates an "awaitable" navigation function that will do its best effort to wait for Next.js to finish its route transition.
@@ -12,31 +12,48 @@ type NavigateFunction = ReturnType<typeof useRouter>['push'];
  * `isPending` to flush the stored promises and ensure the navigates "resolve".
  */
 export const useAwaitableNavigate = () => {
- // eslint-disable-next-line @typescript-eslint/unbound-method
- const { push } = useRouter();
+ const router = useRouter();
  const [isPending, startTransition] = useTransition();
- const clerkNavRef = useRef<(...args: Parameters<NavigateFunction>) => Promise<void>>();
+ const clerkNavRef = useRef<NonNullable<NextClerkProviderProps['routerPush']>>();
  const clerkNavPromiseBuffer = useRef<(() => void)[]>([]);
 
  // Set the navigation function reference only once
  if (!clerkNavRef.current) {
- clerkNavRef.current = (to, opts) => {
+ clerkNavRef.current = ((to, opts) => {
  return new Promise<void>(res => {
  clerkNavPromiseBuffer.current.push(res);
  startTransition(() => {
- push(to, opts);
+ // If the navigation is internal, we should use the history API to navigate
+ // as this is the way to perform a shallow navigation in Next.js App Router
+ // without unmounting/remounting the page or fetching data from the server.
+ if (opts?.__internal_metadata?.navigationType === 'internal') {
+ // In 14.1.0, useSearchParams becomes reactive to shallow updates,
+ // but only if passing `null` as the history state.
+ // Older versions need to maintain the history state for push to work,
+ // without affecting how the Next router works.
+ const state = ((window as any).next?.version ?? '') < '14.1.0' ? history.state : null;
+ window.history.pushState(state, '', to);
+ } else {
+ // If the navigation is external (usually when navigating away from the component but still within the app),
+ // we should use the Next.js router to navigate as it will handle updating the URL and also
+ // fetching the new page if necessary.
+ router.push(to);
+ }
  });
  });
- };
+ }) as NextClerkProviderProps['routerPush'];
  }
 
  // Handle flushing the promise buffer when pending is false. If pending is false and there are promises in the buffer we should be able to safely flush them.
  useEffect(() => {
- if (isPending) return;
+ if (isPending) {
+ return;
+ }
 
  if (clerkNavPromiseBuffer?.current?.length) {
  clerkNavPromiseBuffer.current.forEach(resolve => resolve());
  }
+
  clerkNavPromiseBuffer.current = [];
  }, [isPending]);
 

packages/nextjs/src/client-boundary/usePathnameWithoutCatchAll.tsx

@@ -1,16 +1,23 @@
 import { useRouter } from 'next/compat/router';
+import React from 'react';
 
 export const usePathnameWithoutWithCatchAll = () => {
+ const pathRef = React.useRef<string>();
  // The compat version of useRouter returns null instead of throwing an error
  // when used inside app router instead of pages router
  // we use it to detect if the component is used inside pages or app router
  // so we can use the correct algorithm to get the path
  const pagesRouter = useRouter();
 
  if (pagesRouter) {
- // in pages router things are simpler as the pathname includes the catch all route
- // which starts with [[... and we can just remove it
- return pagesRouter.pathname.replace(/\/\[\[\.\.\..*/, '');
+ if (pathRef.current) {
+ return pathRef.current;
+ } else {
+ // in pages router things are simpler as the pathname includes the catch all route
+ // which starts with [[... and we can just remove it
+ pathRef.current = pagesRouter.pathname.replace(/\/\[\[\.\.\..*/, '');
+ return pathRef.current;
+ }
  }
 
  // require is used to avoid importing next/navigation when the pages router is used,
@@ -38,5 +45,10 @@ export const usePathnameWithoutWithCatchAll = () => {
  .flat(Infinity);
  // so we end up with the pathname where the components are mounted at
  // eg /user/123/profile/security will return /user/123/profile as the path
- return `/${pathParts.slice(0, pathParts.length - catchAllParams.length).join('/')}`;
+ if (pathRef.current) {
+ return pathRef.current;
+ } else {
+ pathRef.current = `/${pathParts.slice(0, pathParts.length - catchAllParams.length).join('/')}`;
+ return pathRef.current;
+ }
 };

.changeset/olive-files-listen.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/nextjs': patch
+'@clerk/types': patch
+---
+
+Prevent Clerk component flickering when mounted in a Next.js app using App Router

packages/clerk-js/src/core/clerk.redirects.test.ts

@@ -126,56 +126,56 @@ describe('Clerk singleton - Redirects', () => {
  await clerkForProductionInstance.redirectToSignIn({ redirectUrl: 'https://www.example.com/' });
  await clerkForDevelopmentInstance.redirectToSignIn({ redirectUrl: 'https://www.example.com/' });
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
  });
 
  it('redirects to signUpUrl', async () => {
  await clerkForProductionInstance.redirectToSignUp({ redirectUrl: 'https://www.example.com/' });
  await clerkForDevelopmentInstance.redirectToSignUp({ redirectUrl: 'https://www.example.com/' });
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
  });
 
  it('redirects to userProfileUrl', async () => {
  await clerkForProductionInstance.redirectToUserProfile();
  await clerkForDevelopmentInstance.redirectToUserProfile();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/user-profile');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/user-profile');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/user-profile');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/user-profile');
  });
 
  it('redirects to afterSignUp', async () => {
  await clerkForProductionInstance.redirectToAfterSignUp();
  await clerkForDevelopmentInstance.redirectToAfterSignUp();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/');
  });
 
  it('redirects to afterSignIn', async () => {
  await clerkForProductionInstance.redirectToAfterSignIn();
  await clerkForDevelopmentInstance.redirectToAfterSignIn();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/');
  });
 
  it('redirects to create organization', async () => {
  await clerkForProductionInstance.redirectToCreateOrganization();
  await clerkForDevelopmentInstance.redirectToCreateOrganization();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/create-organization');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/create-organization');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/create-organization');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/create-organization');
  });
 
  it('redirects to organization profile', async () => {
  await clerkForProductionInstance.redirectToOrganizationProfile();
  await clerkForDevelopmentInstance.redirectToOrganizationProfile();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/organization-profile');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/organization-profile');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/organization-profile');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/organization-profile');
  });
  });
 

packages/clerk-js/src/core/clerk.test.ts

@@ -571,7 +571,7 @@ describe('Clerk singleton', () => {
  const res = sut.navigate(toUrl);
  expect(res.then).toBeDefined();
  expect(mockHref).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith('/path#hash');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/path#hash');
  expect(logSpy).not.toBeCalled();
  });
 
@@ -591,7 +591,7 @@ describe('Clerk singleton', () => {
  const res = sut.navigate(toUrl);
  expect(res.then).toBeDefined();
  expect(mockHref).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith('/path#hash');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/path#hash');
 
  expect(logSpy).toBeCalledTimes(1);
  expect(logSpy).toBeCalledWith(`Clerk is navigating to: ${toUrl}`);
@@ -721,7 +721,7 @@ describe('Clerk singleton', () => {
 
  await waitFor(() => {
  expect(mockSignUpCreate).toHaveBeenCalledWith({ transfer: true });
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up#/continue');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/continue');
  });
  });
 
@@ -934,7 +934,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/factor-two');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/factor-two');
  });
  });
 
@@ -977,7 +977,7 @@ describe('Clerk singleton', () => {
  });
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/custom-2fa');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/custom-2fa');
  });
  });
 
@@ -1032,7 +1032,7 @@ describe('Clerk singleton', () => {
  });
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/custom-sign-in');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/custom-sign-in');
  });
  });
 
@@ -1088,7 +1088,7 @@ describe('Clerk singleton', () => {
  } as any);
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/custom-sign-in');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/custom-sign-in');
  });
  });
 
@@ -1136,7 +1136,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up');
  });
  });
 
@@ -1184,7 +1184,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up');
  });
  });
 
@@ -1226,7 +1226,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up#/continue');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/continue');
  });
  });
 
@@ -1273,7 +1273,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up#/verify-email-address');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/verify-email-address');
  });
  });
 
@@ -1305,7 +1305,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/factor-one');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/factor-one');
  });
  });
 
@@ -1353,7 +1353,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/factor-one');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/factor-one');
  });
  });
 
@@ -1412,7 +1412,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up');
  });
  });
 
@@ -1463,7 +1463,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in');
  });
  });
 
@@ -1501,7 +1501,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/reset-password');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/reset-password');
  });
  });
  });
@@ -1568,7 +1568,7 @@ describe('Clerk singleton', () => {
 
  await waitFor(() => {
  expect(mockSetActive).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith(redirectUrl);
+ expect(mockNavigate.mock.calls[0][0]).toBe(redirectUrl);
  });
  });
 
@@ -1628,7 +1628,7 @@ describe('Clerk singleton', () => {
 
  await waitFor(() => {
  expect(mockSetActive).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith(redirectUrl);
+ expect(mockNavigate.mock.calls[0][0]).toBe(redirectUrl);
  });
  });
 

packages/clerk-js/src/core/clerk.ts

@@ -726,8 +726,9 @@ export class Clerk implements ClerkInterface {
  return;
  }
 
+ const metadata = options?.metadata ? { __internal_metadata: options?.metadata } : undefined;
  // React router only wants the path, search or hash portion.
- return await customNavigate(stripOrigin(toURL));
+ return await customNavigate(stripOrigin(toURL), metadata);
  };
 
  public buildUrlWithAuth(to: string): string {

packages/clerk-js/src/ui/router/BaseRouter.tsx

@@ -1,4 +1,5 @@
 import { useClerk } from '@clerk/shared/react';
+import type { NavigateOptions } from '@clerk/types';
 import qs from 'qs';
 import React from 'react';
 
@@ -14,7 +15,7 @@ interface BaseRouterProps {
  startPath: string;
  getPath: () => string;
  getQueryString: () => string;
- internalNavigate: (toURL: URL) => Promise<any> | any;
+ internalNavigate: (toURL: URL, options?: NavigateOptions) => Promise<any> | any;
  onExternalNavigate?: () => any;
  refreshEvents?: Array<keyof WindowEventMap>;
  preservedParams?: string[];
@@ -114,7 +115,7 @@ export const BaseRouter = ({
  });
  toURL.search = qs.stringify(toQueryParams);
  }
- const internalNavRes = await internalNavigate(toURL);
+ const internalNavRes = await internalNavigate(toURL, { metadata: { navigationType: 'internal' } });
  setRouteParts({ path: toURL.pathname, queryString: toURL.search });
  return internalNavRes;
  };

packages/nextjs/src/app-router/client/useAwaitableNavigate.ts

@@ -3,7 +3,7 @@
 import { useRouter } from 'next/navigation';
 import { useEffect, useRef, useTransition } from 'react';
 
-type NavigateFunction = ReturnType<typeof useRouter>['push'];
+import type { NextClerkProviderProps } from '../../types';
 
 /**
  * Creates an "awaitable" navigation function that will do its best effort to wait for Next.js to finish its route transition.
@@ -12,31 +12,48 @@ type NavigateFunction = ReturnType<typeof useRouter>['push'];
  * `isPending` to flush the stored promises and ensure the navigates "resolve".
  */
 export const useAwaitableNavigate = () => {
- // eslint-disable-next-line @typescript-eslint/unbound-method
- const { push } = useRouter();
+ const router = useRouter();
  const [isPending, startTransition] = useTransition();
- const clerkNavRef = useRef<(...args: Parameters<NavigateFunction>) => Promise<void>>();
+ const clerkNavRef = useRef<NonNullable<NextClerkProviderProps['routerPush']>>();
  const clerkNavPromiseBuffer = useRef<(() => void)[]>([]);
 
  // Set the navigation function reference only once
  if (!clerkNavRef.current) {
- clerkNavRef.current = (to, opts) => {
+ clerkNavRef.current = ((to, opts) => {
  return new Promise<void>(res => {
  clerkNavPromiseBuffer.current.push(res);
  startTransition(() => {
- push(to, opts);
+ // If the navigation is internal, we should use the history API to navigate
+ // as this is the way to perform a shallow navigation in Next.js App Router
+ // without unmounting/remounting the page or fetching data from the server.
+ if (opts?.__internal_metadata?.navigationType === 'internal') {
+ // In 14.1.0, useSearchParams becomes reactive to shallow updates,
+ // but only if passing `null` as the history state.
+ // Older versions need to maintain the history state for push to work,
+ // without affecting how the Next router works.
+ const state = ((window as any).next?.version ?? '') < '14.1.0' ? history.state : null;
+ window.history.pushState(state, '', to);
+ } else {
+ // If the navigation is external (usually when navigating away from the component but still within the app),
+ // we should use the Next.js router to navigate as it will handle updating the URL and also
+ // fetching the new page if necessary.
+ router.push(to);
+ }
  });
  });
- };
+ }) as NextClerkProviderProps['routerPush'];
  }
 
  // Handle flushing the promise buffer when pending is false. If pending is false and there are promises in the buffer we should be able to safely flush them.
  useEffect(() => {
- if (isPending) return;
+ if (isPending) {
+ return;
+ }
 
  if (clerkNavPromiseBuffer?.current?.length) {
  clerkNavPromiseBuffer.current.forEach(resolve => resolve());
  }
+
  clerkNavPromiseBuffer.current = [];
  }, [isPending]);
 

packages/nextjs/src/client-boundary/usePathnameWithoutCatchAll.tsx

@@ -1,16 +1,23 @@
 import { useRouter } from 'next/compat/router';
+import React from 'react';
 
 export const usePathnameWithoutWithCatchAll = () => {
+ const pathRef = React.useRef<string>();
  // The compat version of useRouter returns null instead of throwing an error
  // when used inside app router instead of pages router
  // we use it to detect if the component is used inside pages or app router
  // so we can use the correct algorithm to get the path
  const pagesRouter = useRouter();
 
  if (pagesRouter) {
- // in pages router things are simpler as the pathname includes the catch all route
- // which starts with [[... and we can just remove it
- return pagesRouter.pathname.replace(/\/\[\[\.\.\..*/, '');
+ if (pathRef.current) {
+ return pathRef.current;
+ } else {
+ // in pages router things are simpler as the pathname includes the catch all route
+ // which starts with [[... and we can just remove it
+ pathRef.current = pagesRouter.pathname.replace(/\/\[\[\.\.\..*/, '');
+ return pathRef.current;
+ }
  }
 
  // require is used to avoid importing next/navigation when the pages router is used,
@@ -38,5 +45,10 @@ export const usePathnameWithoutWithCatchAll = () => {
  .flat(Infinity);
  // so we end up with the pathname where the components are mounted at
  // eg /user/123/profile/security will return /user/123/profile as the path
- return `/${pathParts.slice(0, pathParts.length - catchAllParams.length).join('/')}`;
+ if (pathRef.current) {
+ return pathRef.current;
+ } else {
+ pathRef.current = `/${pathParts.slice(0, pathParts.length - catchAllParams.length).join('/')}`;
+ return pathRef.current;
+ }
 };

.changeset/olive-files-listen.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/nextjs': patch
+'@clerk/types': patch
+---
+
+Prevent Clerk component flickering when mounted in a Next.js app using App Router

packages/clerk-js/src/core/clerk.redirects.test.ts

@@ -126,56 +126,56 @@ describe('Clerk singleton - Redirects', () => {
  await clerkForProductionInstance.redirectToSignIn({ redirectUrl: 'https://www.example.com/' });
  await clerkForDevelopmentInstance.redirectToSignIn({ redirectUrl: 'https://www.example.com/' });
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
  });
 
  it('redirects to signUpUrl', async () => {
  await clerkForProductionInstance.redirectToSignUp({ redirectUrl: 'https://www.example.com/' });
  await clerkForDevelopmentInstance.redirectToSignUp({ redirectUrl: 'https://www.example.com/' });
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
  });
 
  it('redirects to userProfileUrl', async () => {
  await clerkForProductionInstance.redirectToUserProfile();
  await clerkForDevelopmentInstance.redirectToUserProfile();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/user-profile');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/user-profile');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/user-profile');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/user-profile');
  });
 
  it('redirects to afterSignUp', async () => {
  await clerkForProductionInstance.redirectToAfterSignUp();
  await clerkForDevelopmentInstance.redirectToAfterSignUp();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/');
  });
 
  it('redirects to afterSignIn', async () => {
  await clerkForProductionInstance.redirectToAfterSignIn();
  await clerkForDevelopmentInstance.redirectToAfterSignIn();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/');
  });
 
  it('redirects to create organization', async () => {
  await clerkForProductionInstance.redirectToCreateOrganization();
  await clerkForDevelopmentInstance.redirectToCreateOrganization();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/create-organization');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/create-organization');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/create-organization');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/create-organization');
  });
 
  it('redirects to organization profile', async () => {
  await clerkForProductionInstance.redirectToOrganizationProfile();
  await clerkForDevelopmentInstance.redirectToOrganizationProfile();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/organization-profile');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/organization-profile');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/organization-profile');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/organization-profile');
  });
  });
 

packages/clerk-js/src/core/clerk.test.ts

@@ -571,7 +571,7 @@ describe('Clerk singleton', () => {
  const res = sut.navigate(toUrl);
  expect(res.then).toBeDefined();
  expect(mockHref).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith('/path#hash');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/path#hash');
  expect(logSpy).not.toBeCalled();
  });
 
@@ -591,7 +591,7 @@ describe('Clerk singleton', () => {
  const res = sut.navigate(toUrl);
  expect(res.then).toBeDefined();
  expect(mockHref).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith('/path#hash');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/path#hash');
 
  expect(logSpy).toBeCalledTimes(1);
  expect(logSpy).toBeCalledWith(`Clerk is navigating to: ${toUrl}`);
@@ -721,7 +721,7 @@ describe('Clerk singleton', () => {
 
  await waitFor(() => {
  expect(mockSignUpCreate).toHaveBeenCalledWith({ transfer: true });
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up#/continue');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/continue');
  });
  });
 
@@ -934,7 +934,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/factor-two');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/factor-two');
  });
  });
 
@@ -977,7 +977,7 @@ describe('Clerk singleton', () => {
  });
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/custom-2fa');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/custom-2fa');
  });
  });
 
@@ -1032,7 +1032,7 @@ describe('Clerk singleton', () => {
  });
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/custom-sign-in');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/custom-sign-in');
  });
  });
 
@@ -1088,7 +1088,7 @@ describe('Clerk singleton', () => {
  } as any);
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/custom-sign-in');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/custom-sign-in');
  });
  });
 
@@ -1136,7 +1136,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up');
  });
  });
 
@@ -1184,7 +1184,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up');
  });
  });
 
@@ -1226,7 +1226,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up#/continue');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/continue');
  });
  });
 
@@ -1273,7 +1273,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up#/verify-email-address');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/verify-email-address');
  });
  });
 
@@ -1305,7 +1305,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/factor-one');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/factor-one');
  });
  });
 
@@ -1353,7 +1353,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/factor-one');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/factor-one');
  });
  });
 
@@ -1412,7 +1412,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up');
  });
  });
 
@@ -1463,7 +1463,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in');
  });
  });
 
@@ -1501,7 +1501,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/reset-password');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/reset-password');
  });
  });
  });
@@ -1568,7 +1568,7 @@ describe('Clerk singleton', () => {
 
  await waitFor(() => {
  expect(mockSetActive).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith(redirectUrl);
+ expect(mockNavigate.mock.calls[0][0]).toBe(redirectUrl);
  });
  });
 
@@ -1628,7 +1628,7 @@ describe('Clerk singleton', () => {
 
  await waitFor(() => {
  expect(mockSetActive).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith(redirectUrl);
+ expect(mockNavigate.mock.calls[0][0]).toBe(redirectUrl);
  });
  });
 

packages/clerk-js/src/core/clerk.ts

@@ -726,8 +726,9 @@ export class Clerk implements ClerkInterface {
  return;
  }
 
+ const metadata = options?.metadata ? { __internal_metadata: options?.metadata } : undefined;
  // React router only wants the path, search or hash portion.
- return await customNavigate(stripOrigin(toURL));
+ return await customNavigate(stripOrigin(toURL), metadata);
  };
 
  public buildUrlWithAuth(to: string): string {

packages/clerk-js/src/ui/router/BaseRouter.tsx

@@ -1,4 +1,5 @@
 import { useClerk } from '@clerk/shared/react';
+import type { NavigateOptions } from '@clerk/types';
 import qs from 'qs';
 import React from 'react';
 
@@ -14,7 +15,7 @@ interface BaseRouterProps {
  startPath: string;
  getPath: () => string;
  getQueryString: () => string;
- internalNavigate: (toURL: URL) => Promise<any> | any;
+ internalNavigate: (toURL: URL, options?: NavigateOptions) => Promise<any> | any;
  onExternalNavigate?: () => any;
  refreshEvents?: Array<keyof WindowEventMap>;
  preservedParams?: string[];
@@ -114,7 +115,7 @@ export const BaseRouter = ({
  });
  toURL.search = qs.stringify(toQueryParams);
  }
- const internalNavRes = await internalNavigate(toURL);
+ const internalNavRes = await internalNavigate(toURL, { metadata: { navigationType: 'internal' } });
  setRouteParts({ path: toURL.pathname, queryString: toURL.search });
  return internalNavRes;
  };

packages/nextjs/src/app-router/client/useAwaitableNavigate.ts

@@ -3,7 +3,7 @@
 import { useRouter } from 'next/navigation';
 import { useEffect, useRef, useTransition } from 'react';
 
-type NavigateFunction = ReturnType<typeof useRouter>['push'];
+import type { NextClerkProviderProps } from '../../types';
 
 /**
  * Creates an "awaitable" navigation function that will do its best effort to wait for Next.js to finish its route transition.
@@ -12,31 +12,48 @@ type NavigateFunction = ReturnType<typeof useRouter>['push'];
  * `isPending` to flush the stored promises and ensure the navigates "resolve".
  */
 export const useAwaitableNavigate = () => {
- // eslint-disable-next-line @typescript-eslint/unbound-method
- const { push } = useRouter();
+ const router = useRouter();
  const [isPending, startTransition] = useTransition();
- const clerkNavRef = useRef<(...args: Parameters<NavigateFunction>) => Promise<void>>();
+ const clerkNavRef = useRef<NonNullable<NextClerkProviderProps['routerPush']>>();
  const clerkNavPromiseBuffer = useRef<(() => void)[]>([]);
 
  // Set the navigation function reference only once
  if (!clerkNavRef.current) {
- clerkNavRef.current = (to, opts) => {
+ clerkNavRef.current = ((to, opts) => {
  return new Promise<void>(res => {
  clerkNavPromiseBuffer.current.push(res);
  startTransition(() => {
- push(to, opts);
+ // If the navigation is internal, we should use the history API to navigate
+ // as this is the way to perform a shallow navigation in Next.js App Router
+ // without unmounting/remounting the page or fetching data from the server.
+ if (opts?.__internal_metadata?.navigationType === 'internal') {
+ // In 14.1.0, useSearchParams becomes reactive to shallow updates,
+ // but only if passing `null` as the history state.
+ // Older versions need to maintain the history state for push to work,
+ // without affecting how the Next router works.
+ const state = ((window as any).next?.version ?? '') < '14.1.0' ? history.state : null;
+ window.history.pushState(state, '', to);
+ } else {
+ // If the navigation is external (usually when navigating away from the component but still within the app),
+ // we should use the Next.js router to navigate as it will handle updating the URL and also
+ // fetching the new page if necessary.
+ router.push(to);
+ }
  });
  });
- };
+ }) as NextClerkProviderProps['routerPush'];
  }
 
  // Handle flushing the promise buffer when pending is false. If pending is false and there are promises in the buffer we should be able to safely flush them.
  useEffect(() => {
- if (isPending) return;
+ if (isPending) {
+ return;
+ }
 
  if (clerkNavPromiseBuffer?.current?.length) {
  clerkNavPromiseBuffer.current.forEach(resolve => resolve());
  }
+
  clerkNavPromiseBuffer.current = [];
  }, [isPending]);
 

packages/nextjs/src/client-boundary/usePathnameWithoutCatchAll.tsx

@@ -1,16 +1,23 @@
 import { useRouter } from 'next/compat/router';
+import React from 'react';
 
 export const usePathnameWithoutWithCatchAll = () => {
+ const pathRef = React.useRef<string>();
  // The compat version of useRouter returns null instead of throwing an error
  // when used inside app router instead of pages router
  // we use it to detect if the component is used inside pages or app router
  // so we can use the correct algorithm to get the path
  const pagesRouter = useRouter();
 
  if (pagesRouter) {
- // in pages router things are simpler as the pathname includes the catch all route
- // which starts with [[... and we can just remove it
- return pagesRouter.pathname.replace(/\/\[\[\.\.\..*/, '');
+ if (pathRef.current) {
+ return pathRef.current;
+ } else {
+ // in pages router things are simpler as the pathname includes the catch all route
+ // which starts with [[... and we can just remove it
+ pathRef.current = pagesRouter.pathname.replace(/\/\[\[\.\.\..*/, '');
+ return pathRef.current;
+ }
  }
 
  // require is used to avoid importing next/navigation when the pages router is used,
@@ -38,5 +45,10 @@ export const usePathnameWithoutWithCatchAll = () => {
  .flat(Infinity);
  // so we end up with the pathname where the components are mounted at
  // eg /user/123/profile/security will return /user/123/profile as the path
- return `/${pathParts.slice(0, pathParts.length - catchAllParams.length).join('/')}`;
+ if (pathRef.current) {
+ return pathRef.current;
+ } else {
+ pathRef.current = `/${pathParts.slice(0, pathParts.length - catchAllParams.length).join('/')}`;
+ return pathRef.current;
+ }
 };

.changeset/olive-files-listen.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/nextjs': patch
+'@clerk/types': patch
+---
+
+Prevent Clerk component flickering when mounted in a Next.js app using App Router

packages/clerk-js/src/core/clerk.redirects.test.ts

@@ -126,56 +126,56 @@ describe('Clerk singleton - Redirects', () => {
  await clerkForProductionInstance.redirectToSignIn({ redirectUrl: 'https://www.example.com/' });
  await clerkForDevelopmentInstance.redirectToSignIn({ redirectUrl: 'https://www.example.com/' });
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
  });
 
  it('redirects to signUpUrl', async () => {
  await clerkForProductionInstance.redirectToSignUp({ redirectUrl: 'https://www.example.com/' });
  await clerkForDevelopmentInstance.redirectToSignUp({ redirectUrl: 'https://www.example.com/' });
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
  });
 
  it('redirects to userProfileUrl', async () => {
  await clerkForProductionInstance.redirectToUserProfile();
  await clerkForDevelopmentInstance.redirectToUserProfile();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/user-profile');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/user-profile');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/user-profile');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/user-profile');
  });
 
  it('redirects to afterSignUp', async () => {
  await clerkForProductionInstance.redirectToAfterSignUp();
  await clerkForDevelopmentInstance.redirectToAfterSignUp();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/');
  });
 
  it('redirects to afterSignIn', async () => {
  await clerkForProductionInstance.redirectToAfterSignIn();
  await clerkForDevelopmentInstance.redirectToAfterSignIn();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/');
  });
 
  it('redirects to create organization', async () => {
  await clerkForProductionInstance.redirectToCreateOrganization();
  await clerkForDevelopmentInstance.redirectToCreateOrganization();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/create-organization');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/create-organization');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/create-organization');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/create-organization');
  });
 
  it('redirects to organization profile', async () => {
  await clerkForProductionInstance.redirectToOrganizationProfile();
  await clerkForDevelopmentInstance.redirectToOrganizationProfile();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/organization-profile');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/organization-profile');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/organization-profile');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/organization-profile');
  });
  });
 

packages/clerk-js/src/core/clerk.test.ts

@@ -571,7 +571,7 @@ describe('Clerk singleton', () => {
  const res = sut.navigate(toUrl);
  expect(res.then).toBeDefined();
  expect(mockHref).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith('/path#hash');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/path#hash');
  expect(logSpy).not.toBeCalled();
  });
 
@@ -591,7 +591,7 @@ describe('Clerk singleton', () => {
  const res = sut.navigate(toUrl);
  expect(res.then).toBeDefined();
  expect(mockHref).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith('/path#hash');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/path#hash');
 
  expect(logSpy).toBeCalledTimes(1);
  expect(logSpy).toBeCalledWith(`Clerk is navigating to: ${toUrl}`);
@@ -721,7 +721,7 @@ describe('Clerk singleton', () => {
 
  await waitFor(() => {
  expect(mockSignUpCreate).toHaveBeenCalledWith({ transfer: true });
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up#/continue');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/continue');
  });
  });
 
@@ -934,7 +934,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/factor-two');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/factor-two');
  });
  });
 
@@ -977,7 +977,7 @@ describe('Clerk singleton', () => {
  });
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/custom-2fa');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/custom-2fa');
  });
  });
 
@@ -1032,7 +1032,7 @@ describe('Clerk singleton', () => {
  });
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/custom-sign-in');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/custom-sign-in');
  });
  });
 
@@ -1088,7 +1088,7 @@ describe('Clerk singleton', () => {
  } as any);
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/custom-sign-in');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/custom-sign-in');
  });
  });
 
@@ -1136,7 +1136,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up');
  });
  });
 
@@ -1184,7 +1184,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up');
  });
  });
 
@@ -1226,7 +1226,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up#/continue');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/continue');
  });
  });
 
@@ -1273,7 +1273,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up#/verify-email-address');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/verify-email-address');
  });
  });
 
@@ -1305,7 +1305,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/factor-one');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/factor-one');
  });
  });
 
@@ -1353,7 +1353,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/factor-one');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/factor-one');
  });
  });
 
@@ -1412,7 +1412,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up');
  });
  });
 
@@ -1463,7 +1463,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in');
  });
  });
 
@@ -1501,7 +1501,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/reset-password');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/reset-password');
  });
  });
  });
@@ -1568,7 +1568,7 @@ describe('Clerk singleton', () => {
 
  await waitFor(() => {
  expect(mockSetActive).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith(redirectUrl);
+ expect(mockNavigate.mock.calls[0][0]).toBe(redirectUrl);
  });
  });
 
@@ -1628,7 +1628,7 @@ describe('Clerk singleton', () => {
 
  await waitFor(() => {
  expect(mockSetActive).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith(redirectUrl);
+ expect(mockNavigate.mock.calls[0][0]).toBe(redirectUrl);
  });
  });
 

packages/clerk-js/src/core/clerk.ts

@@ -726,8 +726,9 @@ export class Clerk implements ClerkInterface {
  return;
  }
 
+ const metadata = options?.metadata ? { __internal_metadata: options?.metadata } : undefined;
  // React router only wants the path, search or hash portion.
- return await customNavigate(stripOrigin(toURL));
+ return await customNavigate(stripOrigin(toURL), metadata);
  };
 
  public buildUrlWithAuth(to: string): string {

packages/clerk-js/src/ui/router/BaseRouter.tsx

@@ -1,4 +1,5 @@
 import { useClerk } from '@clerk/shared/react';
+import type { NavigateOptions } from '@clerk/types';
 import qs from 'qs';
 import React from 'react';
 
@@ -14,7 +15,7 @@ interface BaseRouterProps {
  startPath: string;
  getPath: () => string;
  getQueryString: () => string;
- internalNavigate: (toURL: URL) => Promise<any> | any;
+ internalNavigate: (toURL: URL, options?: NavigateOptions) => Promise<any> | any;
  onExternalNavigate?: () => any;
  refreshEvents?: Array<keyof WindowEventMap>;
  preservedParams?: string[];
@@ -114,7 +115,7 @@ export const BaseRouter = ({
  });
  toURL.search = qs.stringify(toQueryParams);
  }
- const internalNavRes = await internalNavigate(toURL);
+ const internalNavRes = await internalNavigate(toURL, { metadata: { navigationType: 'internal' } });
  setRouteParts({ path: toURL.pathname, queryString: toURL.search });
  return internalNavRes;
  };

packages/nextjs/src/app-router/client/useAwaitableNavigate.ts

@@ -3,7 +3,7 @@
 import { useRouter } from 'next/navigation';
 import { useEffect, useRef, useTransition } from 'react';
 
-type NavigateFunction = ReturnType<typeof useRouter>['push'];
+import type { NextClerkProviderProps } from '../../types';
 
 /**
  * Creates an "awaitable" navigation function that will do its best effort to wait for Next.js to finish its route transition.
@@ -12,31 +12,48 @@ type NavigateFunction = ReturnType<typeof useRouter>['push'];
  * `isPending` to flush the stored promises and ensure the navigates "resolve".
  */
 export const useAwaitableNavigate = () => {
- // eslint-disable-next-line @typescript-eslint/unbound-method
- const { push } = useRouter();
+ const router = useRouter();
  const [isPending, startTransition] = useTransition();
- const clerkNavRef = useRef<(...args: Parameters<NavigateFunction>) => Promise<void>>();
+ const clerkNavRef = useRef<NonNullable<NextClerkProviderProps['routerPush']>>();
  const clerkNavPromiseBuffer = useRef<(() => void)[]>([]);
 
  // Set the navigation function reference only once
  if (!clerkNavRef.current) {
- clerkNavRef.current = (to, opts) => {
+ clerkNavRef.current = ((to, opts) => {
  return new Promise<void>(res => {
  clerkNavPromiseBuffer.current.push(res);
  startTransition(() => {
- push(to, opts);
+ // If the navigation is internal, we should use the history API to navigate
+ // as this is the way to perform a shallow navigation in Next.js App Router
+ // without unmounting/remounting the page or fetching data from the server.
+ if (opts?.__internal_metadata?.navigationType === 'internal') {
+ // In 14.1.0, useSearchParams becomes reactive to shallow updates,
+ // but only if passing `null` as the history state.
+ // Older versions need to maintain the history state for push to work,
+ // without affecting how the Next router works.
+ const state = ((window as any).next?.version ?? '') < '14.1.0' ? history.state : null;
+ window.history.pushState(state, '', to);
+ } else {
+ // If the navigation is external (usually when navigating away from the component but still within the app),
+ // we should use the Next.js router to navigate as it will handle updating the URL and also
+ // fetching the new page if necessary.
+ router.push(to);
+ }
  });
  });
- };
+ }) as NextClerkProviderProps['routerPush'];
  }
 
  // Handle flushing the promise buffer when pending is false. If pending is false and there are promises in the buffer we should be able to safely flush them.
  useEffect(() => {
- if (isPending) return;
+ if (isPending) {
+ return;
+ }
 
  if (clerkNavPromiseBuffer?.current?.length) {
  clerkNavPromiseBuffer.current.forEach(resolve => resolve());
  }
+
  clerkNavPromiseBuffer.current = [];
  }, [isPending]);
 

packages/nextjs/src/client-boundary/usePathnameWithoutCatchAll.tsx

@@ -1,16 +1,23 @@
 import { useRouter } from 'next/compat/router';
+import React from 'react';
 
 export const usePathnameWithoutWithCatchAll = () => {
+ const pathRef = React.useRef<string>();
  // The compat version of useRouter returns null instead of throwing an error
  // when used inside app router instead of pages router
  // we use it to detect if the component is used inside pages or app router
  // so we can use the correct algorithm to get the path
  const pagesRouter = useRouter();
 
  if (pagesRouter) {
- // in pages router things are simpler as the pathname includes the catch all route
- // which starts with [[... and we can just remove it
- return pagesRouter.pathname.replace(/\/\[\[\.\.\..*/, '');
+ if (pathRef.current) {
+ return pathRef.current;
+ } else {
+ // in pages router things are simpler as the pathname includes the catch all route
+ // which starts with [[... and we can just remove it
+ pathRef.current = pagesRouter.pathname.replace(/\/\[\[\.\.\..*/, '');
+ return pathRef.current;
+ }
  }
 
  // require is used to avoid importing next/navigation when the pages router is used,
@@ -38,5 +45,10 @@ export const usePathnameWithoutWithCatchAll = () => {
  .flat(Infinity);
  // so we end up with the pathname where the components are mounted at
  // eg /user/123/profile/security will return /user/123/profile as the path
- return `/${pathParts.slice(0, pathParts.length - catchAllParams.length).join('/')}`;
+ if (pathRef.current) {
+ return pathRef.current;
+ } else {
+ pathRef.current = `/${pathParts.slice(0, pathParts.length - catchAllParams.length).join('/')}`;
+ return pathRef.current;
+ }
 };

.changeset/olive-files-listen.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/nextjs': patch
+'@clerk/types': patch
+---
+
+Prevent Clerk component flickering when mounted in a Next.js app using App Router

packages/clerk-js/src/core/clerk.redirects.test.ts

@@ -126,56 +126,56 @@ describe('Clerk singleton - Redirects', () => {
  await clerkForProductionInstance.redirectToSignIn({ redirectUrl: 'https://www.example.com/' });
  await clerkForDevelopmentInstance.redirectToSignIn({ redirectUrl: 'https://www.example.com/' });
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
  });
 
  it('redirects to signUpUrl', async () => {
  await clerkForProductionInstance.redirectToSignUp({ redirectUrl: 'https://www.example.com/' });
  await clerkForDevelopmentInstance.redirectToSignUp({ redirectUrl: 'https://www.example.com/' });
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
  });
 
  it('redirects to userProfileUrl', async () => {
  await clerkForProductionInstance.redirectToUserProfile();
  await clerkForDevelopmentInstance.redirectToUserProfile();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/user-profile');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/user-profile');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/user-profile');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/user-profile');
  });
 
  it('redirects to afterSignUp', async () => {
  await clerkForProductionInstance.redirectToAfterSignUp();
  await clerkForDevelopmentInstance.redirectToAfterSignUp();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/');
  });
 
  it('redirects to afterSignIn', async () => {
  await clerkForProductionInstance.redirectToAfterSignIn();
  await clerkForDevelopmentInstance.redirectToAfterSignIn();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/');
  });
 
  it('redirects to create organization', async () => {
  await clerkForProductionInstance.redirectToCreateOrganization();
  await clerkForDevelopmentInstance.redirectToCreateOrganization();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/create-organization');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/create-organization');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/create-organization');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/create-organization');
  });
 
  it('redirects to organization profile', async () => {
  await clerkForProductionInstance.redirectToOrganizationProfile();
  await clerkForDevelopmentInstance.redirectToOrganizationProfile();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/organization-profile');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/organization-profile');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/organization-profile');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/organization-profile');
  });
  });
 

packages/clerk-js/src/core/clerk.test.ts

@@ -571,7 +571,7 @@ describe('Clerk singleton', () => {
  const res = sut.navigate(toUrl);
  expect(res.then).toBeDefined();
  expect(mockHref).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith('/path#hash');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/path#hash');
  expect(logSpy).not.toBeCalled();
  });
 
@@ -591,7 +591,7 @@ describe('Clerk singleton', () => {
  const res = sut.navigate(toUrl);
  expect(res.then).toBeDefined();
  expect(mockHref).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith('/path#hash');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/path#hash');
 
  expect(logSpy).toBeCalledTimes(1);
  expect(logSpy).toBeCalledWith(`Clerk is navigating to: ${toUrl}`);
@@ -721,7 +721,7 @@ describe('Clerk singleton', () => {
 
  await waitFor(() => {
  expect(mockSignUpCreate).toHaveBeenCalledWith({ transfer: true });
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up#/continue');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/continue');
  });
  });
 
@@ -934,7 +934,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/factor-two');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/factor-two');
  });
  });
 
@@ -977,7 +977,7 @@ describe('Clerk singleton', () => {
  });
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/custom-2fa');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/custom-2fa');
  });
  });
 
@@ -1032,7 +1032,7 @@ describe('Clerk singleton', () => {
  });
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/custom-sign-in');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/custom-sign-in');
  });
  });
 
@@ -1088,7 +1088,7 @@ describe('Clerk singleton', () => {
  } as any);
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/custom-sign-in');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/custom-sign-in');
  });
  });
 
@@ -1136,7 +1136,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up');
  });
  });
 
@@ -1184,7 +1184,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up');
  });
  });
 
@@ -1226,7 +1226,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up#/continue');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/continue');
  });
  });
 
@@ -1273,7 +1273,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up#/verify-email-address');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/verify-email-address');
  });
  });
 
@@ -1305,7 +1305,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/factor-one');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/factor-one');
  });
  });
 
@@ -1353,7 +1353,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/factor-one');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/factor-one');
  });
  });
 
@@ -1412,7 +1412,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up');
  });
  });
 
@@ -1463,7 +1463,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in');
  });
  });
 
@@ -1501,7 +1501,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/reset-password');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/reset-password');
  });
  });
  });
@@ -1568,7 +1568,7 @@ describe('Clerk singleton', () => {
 
  await waitFor(() => {
  expect(mockSetActive).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith(redirectUrl);
+ expect(mockNavigate.mock.calls[0][0]).toBe(redirectUrl);
  });
  });
 
@@ -1628,7 +1628,7 @@ describe('Clerk singleton', () => {
 
  await waitFor(() => {
  expect(mockSetActive).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith(redirectUrl);
+ expect(mockNavigate.mock.calls[0][0]).toBe(redirectUrl);
  });
  });
 

packages/clerk-js/src/core/clerk.ts

@@ -726,8 +726,9 @@ export class Clerk implements ClerkInterface {
  return;
  }
 
+ const metadata = options?.metadata ? { __internal_metadata: options?.metadata } : undefined;
  // React router only wants the path, search or hash portion.
- return await customNavigate(stripOrigin(toURL));
+ return await customNavigate(stripOrigin(toURL), metadata);
  };
 
  public buildUrlWithAuth(to: string): string {

packages/clerk-js/src/ui/router/BaseRouter.tsx

@@ -1,4 +1,5 @@
 import { useClerk } from '@clerk/shared/react';
+import type { NavigateOptions } from '@clerk/types';
 import qs from 'qs';
 import React from 'react';
 
@@ -14,7 +15,7 @@ interface BaseRouterProps {
  startPath: string;
  getPath: () => string;
  getQueryString: () => string;
- internalNavigate: (toURL: URL) => Promise<any> | any;
+ internalNavigate: (toURL: URL, options?: NavigateOptions) => Promise<any> | any;
  onExternalNavigate?: () => any;
  refreshEvents?: Array<keyof WindowEventMap>;
  preservedParams?: string[];
@@ -114,7 +115,7 @@ export const BaseRouter = ({
  });
  toURL.search = qs.stringify(toQueryParams);
  }
- const internalNavRes = await internalNavigate(toURL);
+ const internalNavRes = await internalNavigate(toURL, { metadata: { navigationType: 'internal' } });
  setRouteParts({ path: toURL.pathname, queryString: toURL.search });
  return internalNavRes;
  };

packages/nextjs/src/app-router/client/useAwaitableNavigate.ts

@@ -3,7 +3,7 @@
 import { useRouter } from 'next/navigation';
 import { useEffect, useRef, useTransition } from 'react';
 
-type NavigateFunction = ReturnType<typeof useRouter>['push'];
+import type { NextClerkProviderProps } from '../../types';
 
 /**
  * Creates an "awaitable" navigation function that will do its best effort to wait for Next.js to finish its route transition.
@@ -12,31 +12,48 @@ type NavigateFunction = ReturnType<typeof useRouter>['push'];
  * `isPending` to flush the stored promises and ensure the navigates "resolve".
  */
 export const useAwaitableNavigate = () => {
- // eslint-disable-next-line @typescript-eslint/unbound-method
- const { push } = useRouter();
+ const router = useRouter();
  const [isPending, startTransition] = useTransition();
- const clerkNavRef = useRef<(...args: Parameters<NavigateFunction>) => Promise<void>>();
+ const clerkNavRef = useRef<NonNullable<NextClerkProviderProps['routerPush']>>();
  const clerkNavPromiseBuffer = useRef<(() => void)[]>([]);
 
  // Set the navigation function reference only once
  if (!clerkNavRef.current) {
- clerkNavRef.current = (to, opts) => {
+ clerkNavRef.current = ((to, opts) => {
  return new Promise<void>(res => {
  clerkNavPromiseBuffer.current.push(res);
  startTransition(() => {
- push(to, opts);
+ // If the navigation is internal, we should use the history API to navigate
+ // as this is the way to perform a shallow navigation in Next.js App Router
+ // without unmounting/remounting the page or fetching data from the server.
+ if (opts?.__internal_metadata?.navigationType === 'internal') {
+ // In 14.1.0, useSearchParams becomes reactive to shallow updates,
+ // but only if passing `null` as the history state.
+ // Older versions need to maintain the history state for push to work,
+ // without affecting how the Next router works.
+ const state = ((window as any).next?.version ?? '') < '14.1.0' ? history.state : null;
+ window.history.pushState(state, '', to);
+ } else {
+ // If the navigation is external (usually when navigating away from the component but still within the app),
+ // we should use the Next.js router to navigate as it will handle updating the URL and also
+ // fetching the new page if necessary.
+ router.push(to);
+ }
  });
  });
- };
+ }) as NextClerkProviderProps['routerPush'];
  }
 
  // Handle flushing the promise buffer when pending is false. If pending is false and there are promises in the buffer we should be able to safely flush them.
  useEffect(() => {
- if (isPending) return;
+ if (isPending) {
+ return;
+ }
 
  if (clerkNavPromiseBuffer?.current?.length) {
  clerkNavPromiseBuffer.current.forEach(resolve => resolve());
  }
+
  clerkNavPromiseBuffer.current = [];
  }, [isPending]);
 

packages/nextjs/src/client-boundary/usePathnameWithoutCatchAll.tsx

@@ -1,16 +1,23 @@
 import { useRouter } from 'next/compat/router';
+import React from 'react';
 
 export const usePathnameWithoutWithCatchAll = () => {
+ const pathRef = React.useRef<string>();
  // The compat version of useRouter returns null instead of throwing an error
  // when used inside app router instead of pages router
  // we use it to detect if the component is used inside pages or app router
  // so we can use the correct algorithm to get the path
  const pagesRouter = useRouter();
 
  if (pagesRouter) {
- // in pages router things are simpler as the pathname includes the catch all route
- // which starts with [[... and we can just remove it
- return pagesRouter.pathname.replace(/\/\[\[\.\.\..*/, '');
+ if (pathRef.current) {
+ return pathRef.current;
+ } else {
+ // in pages router things are simpler as the pathname includes the catch all route
+ // which starts with [[... and we can just remove it
+ pathRef.current = pagesRouter.pathname.replace(/\/\[\[\.\.\..*/, '');
+ return pathRef.current;
+ }
  }
 
  // require is used to avoid importing next/navigation when the pages router is used,
@@ -38,5 +45,10 @@ export const usePathnameWithoutWithCatchAll = () => {
  .flat(Infinity);
  // so we end up with the pathname where the components are mounted at
  // eg /user/123/profile/security will return /user/123/profile as the path
- return `/${pathParts.slice(0, pathParts.length - catchAllParams.length).join('/')}`;
+ if (pathRef.current) {
+ return pathRef.current;
+ } else {
+ pathRef.current = `/${pathParts.slice(0, pathParts.length - catchAllParams.length).join('/')}`;
+ return pathRef.current;
+ }
 };

.changeset/olive-files-listen.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/nextjs': patch
+'@clerk/types': patch
+---
+
+Prevent Clerk component flickering when mounted in a Next.js app using App Router

packages/clerk-js/src/core/clerk.redirects.test.ts

@@ -126,56 +126,56 @@ describe('Clerk singleton - Redirects', () => {
  await clerkForProductionInstance.redirectToSignIn({ redirectUrl: 'https://www.example.com/' });
  await clerkForDevelopmentInstance.redirectToSignIn({ redirectUrl: 'https://www.example.com/' });
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
  });
 
  it('redirects to signUpUrl', async () => {
  await clerkForProductionInstance.redirectToSignUp({ redirectUrl: 'https://www.example.com/' });
  await clerkForDevelopmentInstance.redirectToSignUp({ redirectUrl: 'https://www.example.com/' });
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
  });
 
  it('redirects to userProfileUrl', async () => {
  await clerkForProductionInstance.redirectToUserProfile();
  await clerkForDevelopmentInstance.redirectToUserProfile();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/user-profile');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/user-profile');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/user-profile');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/user-profile');
  });
 
  it('redirects to afterSignUp', async () => {
  await clerkForProductionInstance.redirectToAfterSignUp();
  await clerkForDevelopmentInstance.redirectToAfterSignUp();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/');
  });
 
  it('redirects to afterSignIn', async () => {
  await clerkForProductionInstance.redirectToAfterSignIn();
  await clerkForDevelopmentInstance.redirectToAfterSignIn();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/');
  });
 
  it('redirects to create organization', async () => {
  await clerkForProductionInstance.redirectToCreateOrganization();
  await clerkForDevelopmentInstance.redirectToCreateOrganization();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/create-organization');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/create-organization');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/create-organization');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/create-organization');
  });
 
  it('redirects to organization profile', async () => {
  await clerkForProductionInstance.redirectToOrganizationProfile();
  await clerkForDevelopmentInstance.redirectToOrganizationProfile();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/organization-profile');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/organization-profile');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/organization-profile');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/organization-profile');
  });
  });
 

packages/clerk-js/src/core/clerk.test.ts

@@ -571,7 +571,7 @@ describe('Clerk singleton', () => {
  const res = sut.navigate(toUrl);
  expect(res.then).toBeDefined();
  expect(mockHref).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith('/path#hash');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/path#hash');
  expect(logSpy).not.toBeCalled();
  });
 
@@ -591,7 +591,7 @@ describe('Clerk singleton', () => {
  const res = sut.navigate(toUrl);
  expect(res.then).toBeDefined();
  expect(mockHref).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith('/path#hash');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/path#hash');
 
  expect(logSpy).toBeCalledTimes(1);
  expect(logSpy).toBeCalledWith(`Clerk is navigating to: ${toUrl}`);
@@ -721,7 +721,7 @@ describe('Clerk singleton', () => {
 
  await waitFor(() => {
  expect(mockSignUpCreate).toHaveBeenCalledWith({ transfer: true });
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up#/continue');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/continue');
  });
  });
 
@@ -934,7 +934,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/factor-two');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/factor-two');
  });
  });
 
@@ -977,7 +977,7 @@ describe('Clerk singleton', () => {
  });
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/custom-2fa');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/custom-2fa');
  });
  });
 
@@ -1032,7 +1032,7 @@ describe('Clerk singleton', () => {
  });
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/custom-sign-in');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/custom-sign-in');
  });
  });
 
@@ -1088,7 +1088,7 @@ describe('Clerk singleton', () => {
  } as any);
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/custom-sign-in');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/custom-sign-in');
  });
  });
 
@@ -1136,7 +1136,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up');
  });
  });
 
@@ -1184,7 +1184,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up');
  });
  });
 
@@ -1226,7 +1226,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up#/continue');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/continue');
  });
  });
 
@@ -1273,7 +1273,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up#/verify-email-address');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/verify-email-address');
  });
  });
 
@@ -1305,7 +1305,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/factor-one');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/factor-one');
  });
  });
 
@@ -1353,7 +1353,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/factor-one');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/factor-one');
  });
  });
 
@@ -1412,7 +1412,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up');
  });
  });
 
@@ -1463,7 +1463,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in');
  });
  });
 
@@ -1501,7 +1501,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/reset-password');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/reset-password');
  });
  });
  });
@@ -1568,7 +1568,7 @@ describe('Clerk singleton', () => {
 
  await waitFor(() => {
  expect(mockSetActive).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith(redirectUrl);
+ expect(mockNavigate.mock.calls[0][0]).toBe(redirectUrl);
  });
  });
 
@@ -1628,7 +1628,7 @@ describe('Clerk singleton', () => {
 
  await waitFor(() => {
  expect(mockSetActive).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith(redirectUrl);
+ expect(mockNavigate.mock.calls[0][0]).toBe(redirectUrl);
  });
  });
 

packages/clerk-js/src/core/clerk.ts

@@ -726,8 +726,9 @@ export class Clerk implements ClerkInterface {
  return;
  }
 
+ const metadata = options?.metadata ? { __internal_metadata: options?.metadata } : undefined;
  // React router only wants the path, search or hash portion.
- return await customNavigate(stripOrigin(toURL));
+ return await customNavigate(stripOrigin(toURL), metadata);
  };
 
  public buildUrlWithAuth(to: string): string {

packages/clerk-js/src/ui/router/BaseRouter.tsx

@@ -1,4 +1,5 @@
 import { useClerk } from '@clerk/shared/react';
+import type { NavigateOptions } from '@clerk/types';
 import qs from 'qs';
 import React from 'react';
 
@@ -14,7 +15,7 @@ interface BaseRouterProps {
  startPath: string;
  getPath: () => string;
  getQueryString: () => string;
- internalNavigate: (toURL: URL) => Promise<any> | any;
+ internalNavigate: (toURL: URL, options?: NavigateOptions) => Promise<any> | any;
  onExternalNavigate?: () => any;
  refreshEvents?: Array<keyof WindowEventMap>;
  preservedParams?: string[];
@@ -114,7 +115,7 @@ export const BaseRouter = ({
  });
  toURL.search = qs.stringify(toQueryParams);
  }
- const internalNavRes = await internalNavigate(toURL);
+ const internalNavRes = await internalNavigate(toURL, { metadata: { navigationType: 'internal' } });
  setRouteParts({ path: toURL.pathname, queryString: toURL.search });
  return internalNavRes;
  };

packages/nextjs/src/app-router/client/useAwaitableNavigate.ts

@@ -3,7 +3,7 @@
 import { useRouter } from 'next/navigation';
 import { useEffect, useRef, useTransition } from 'react';
 
-type NavigateFunction = ReturnType<typeof useRouter>['push'];
+import type { NextClerkProviderProps } from '../../types';
 
 /**
  * Creates an "awaitable" navigation function that will do its best effort to wait for Next.js to finish its route transition.
@@ -12,31 +12,48 @@ type NavigateFunction = ReturnType<typeof useRouter>['push'];
  * `isPending` to flush the stored promises and ensure the navigates "resolve".
  */
 export const useAwaitableNavigate = () => {
- // eslint-disable-next-line @typescript-eslint/unbound-method
- const { push } = useRouter();
+ const router = useRouter();
  const [isPending, startTransition] = useTransition();
- const clerkNavRef = useRef<(...args: Parameters<NavigateFunction>) => Promise<void>>();
+ const clerkNavRef = useRef<NonNullable<NextClerkProviderProps['routerPush']>>();
  const clerkNavPromiseBuffer = useRef<(() => void)[]>([]);
 
  // Set the navigation function reference only once
  if (!clerkNavRef.current) {
- clerkNavRef.current = (to, opts) => {
+ clerkNavRef.current = ((to, opts) => {
  return new Promise<void>(res => {
  clerkNavPromiseBuffer.current.push(res);
  startTransition(() => {
- push(to, opts);
+ // If the navigation is internal, we should use the history API to navigate
+ // as this is the way to perform a shallow navigation in Next.js App Router
+ // without unmounting/remounting the page or fetching data from the server.
+ if (opts?.__internal_metadata?.navigationType === 'internal') {
+ // In 14.1.0, useSearchParams becomes reactive to shallow updates,
+ // but only if passing `null` as the history state.
+ // Older versions need to maintain the history state for push to work,
+ // without affecting how the Next router works.
+ const state = ((window as any).next?.version ?? '') < '14.1.0' ? history.state : null;
+ window.history.pushState(state, '', to);
+ } else {
+ // If the navigation is external (usually when navigating away from the component but still within the app),
+ // we should use the Next.js router to navigate as it will handle updating the URL and also
+ // fetching the new page if necessary.
+ router.push(to);
+ }
  });
  });
- };
+ }) as NextClerkProviderProps['routerPush'];
  }
 
  // Handle flushing the promise buffer when pending is false. If pending is false and there are promises in the buffer we should be able to safely flush them.
  useEffect(() => {
- if (isPending) return;
+ if (isPending) {
+ return;
+ }
 
  if (clerkNavPromiseBuffer?.current?.length) {
  clerkNavPromiseBuffer.current.forEach(resolve => resolve());
  }
+
  clerkNavPromiseBuffer.current = [];
  }, [isPending]);
 

packages/nextjs/src/client-boundary/usePathnameWithoutCatchAll.tsx

@@ -1,16 +1,23 @@
 import { useRouter } from 'next/compat/router';
+import React from 'react';
 
 export const usePathnameWithoutWithCatchAll = () => {
+ const pathRef = React.useRef<string>();
  // The compat version of useRouter returns null instead of throwing an error
  // when used inside app router instead of pages router
  // we use it to detect if the component is used inside pages or app router
  // so we can use the correct algorithm to get the path
  const pagesRouter = useRouter();
 
  if (pagesRouter) {
- // in pages router things are simpler as the pathname includes the catch all route
- // which starts with [[... and we can just remove it
- return pagesRouter.pathname.replace(/\/\[\[\.\.\..*/, '');
+ if (pathRef.current) {
+ return pathRef.current;
+ } else {
+ // in pages router things are simpler as the pathname includes the catch all route
+ // which starts with [[... and we can just remove it
+ pathRef.current = pagesRouter.pathname.replace(/\/\[\[\.\.\..*/, '');
+ return pathRef.current;
+ }
  }
 
  // require is used to avoid importing next/navigation when the pages router is used,
@@ -38,5 +45,10 @@ export const usePathnameWithoutWithCatchAll = () => {
  .flat(Infinity);
  // so we end up with the pathname where the components are mounted at
  // eg /user/123/profile/security will return /user/123/profile as the path
- return `/${pathParts.slice(0, pathParts.length - catchAllParams.length).join('/')}`;
+ if (pathRef.current) {
+ return pathRef.current;
+ } else {
+ pathRef.current = `/${pathParts.slice(0, pathParts.length - catchAllParams.length).join('/')}`;
+ return pathRef.current;
+ }
 };

.changeset/olive-files-listen.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/nextjs': patch
+'@clerk/types': patch
+---
+
+Prevent Clerk component flickering when mounted in a Next.js app using App Router

packages/clerk-js/src/core/clerk.redirects.test.ts

@@ -126,56 +126,56 @@ describe('Clerk singleton - Redirects', () => {
  await clerkForProductionInstance.redirectToSignIn({ redirectUrl: 'https://www.example.com/' });
  await clerkForDevelopmentInstance.redirectToSignIn({ redirectUrl: 'https://www.example.com/' });
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
  });
 
  it('redirects to signUpUrl', async () => {
  await clerkForProductionInstance.redirectToSignUp({ redirectUrl: 'https://www.example.com/' });
  await clerkForDevelopmentInstance.redirectToSignUp({ redirectUrl: 'https://www.example.com/' });
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
  });
 
  it('redirects to userProfileUrl', async () => {
  await clerkForProductionInstance.redirectToUserProfile();
  await clerkForDevelopmentInstance.redirectToUserProfile();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/user-profile');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/user-profile');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/user-profile');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/user-profile');
  });
 
  it('redirects to afterSignUp', async () => {
  await clerkForProductionInstance.redirectToAfterSignUp();
  await clerkForDevelopmentInstance.redirectToAfterSignUp();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/');
  });
 
  it('redirects to afterSignIn', async () => {
  await clerkForProductionInstance.redirectToAfterSignIn();
  await clerkForDevelopmentInstance.redirectToAfterSignIn();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/');
  });
 
  it('redirects to create organization', async () => {
  await clerkForProductionInstance.redirectToCreateOrganization();
  await clerkForDevelopmentInstance.redirectToCreateOrganization();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/create-organization');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/create-organization');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/create-organization');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/create-organization');
  });
 
  it('redirects to organization profile', async () => {
  await clerkForProductionInstance.redirectToOrganizationProfile();
  await clerkForDevelopmentInstance.redirectToOrganizationProfile();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/organization-profile');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/organization-profile');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/organization-profile');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/organization-profile');
  });
  });
 

packages/clerk-js/src/core/clerk.test.ts

@@ -571,7 +571,7 @@ describe('Clerk singleton', () => {
  const res = sut.navigate(toUrl);
  expect(res.then).toBeDefined();
  expect(mockHref).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith('/path#hash');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/path#hash');
  expect(logSpy).not.toBeCalled();
  });
 
@@ -591,7 +591,7 @@ describe('Clerk singleton', () => {
  const res = sut.navigate(toUrl);
  expect(res.then).toBeDefined();
  expect(mockHref).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith('/path#hash');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/path#hash');
 
  expect(logSpy).toBeCalledTimes(1);
  expect(logSpy).toBeCalledWith(`Clerk is navigating to: ${toUrl}`);
@@ -721,7 +721,7 @@ describe('Clerk singleton', () => {
 
  await waitFor(() => {
  expect(mockSignUpCreate).toHaveBeenCalledWith({ transfer: true });
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up#/continue');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/continue');
  });
  });
 
@@ -934,7 +934,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/factor-two');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/factor-two');
  });
  });
 
@@ -977,7 +977,7 @@ describe('Clerk singleton', () => {
  });
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/custom-2fa');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/custom-2fa');
  });
  });
 
@@ -1032,7 +1032,7 @@ describe('Clerk singleton', () => {
  });
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/custom-sign-in');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/custom-sign-in');
  });
  });
 
@@ -1088,7 +1088,7 @@ describe('Clerk singleton', () => {
  } as any);
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/custom-sign-in');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/custom-sign-in');
  });
  });
 
@@ -1136,7 +1136,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up');
  });
  });
 
@@ -1184,7 +1184,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up');
  });
  });
 
@@ -1226,7 +1226,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up#/continue');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/continue');
  });
  });
 
@@ -1273,7 +1273,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up#/verify-email-address');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/verify-email-address');
  });
  });
 
@@ -1305,7 +1305,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/factor-one');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/factor-one');
  });
  });
 
@@ -1353,7 +1353,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/factor-one');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/factor-one');
  });
  });
 
@@ -1412,7 +1412,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up');
  });
  });
 
@@ -1463,7 +1463,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in');
  });
  });
 
@@ -1501,7 +1501,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/reset-password');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/reset-password');
  });
  });
  });
@@ -1568,7 +1568,7 @@ describe('Clerk singleton', () => {
 
  await waitFor(() => {
  expect(mockSetActive).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith(redirectUrl);
+ expect(mockNavigate.mock.calls[0][0]).toBe(redirectUrl);
  });
  });
 
@@ -1628,7 +1628,7 @@ describe('Clerk singleton', () => {
 
  await waitFor(() => {
  expect(mockSetActive).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith(redirectUrl);
+ expect(mockNavigate.mock.calls[0][0]).toBe(redirectUrl);
  });
  });
 

packages/clerk-js/src/core/clerk.ts

@@ -726,8 +726,9 @@ export class Clerk implements ClerkInterface {
  return;
  }
 
+ const metadata = options?.metadata ? { __internal_metadata: options?.metadata } : undefined;
  // React router only wants the path, search or hash portion.
- return await customNavigate(stripOrigin(toURL));
+ return await customNavigate(stripOrigin(toURL), metadata);
  };
 
  public buildUrlWithAuth(to: string): string {

packages/clerk-js/src/ui/router/BaseRouter.tsx

@@ -1,4 +1,5 @@
 import { useClerk } from '@clerk/shared/react';
+import type { NavigateOptions } from '@clerk/types';
 import qs from 'qs';
 import React from 'react';
 
@@ -14,7 +15,7 @@ interface BaseRouterProps {
  startPath: string;
  getPath: () => string;
  getQueryString: () => string;
- internalNavigate: (toURL: URL) => Promise<any> | any;
+ internalNavigate: (toURL: URL, options?: NavigateOptions) => Promise<any> | any;
  onExternalNavigate?: () => any;
  refreshEvents?: Array<keyof WindowEventMap>;
  preservedParams?: string[];
@@ -114,7 +115,7 @@ export const BaseRouter = ({
  });
  toURL.search = qs.stringify(toQueryParams);
  }
- const internalNavRes = await internalNavigate(toURL);
+ const internalNavRes = await internalNavigate(toURL, { metadata: { navigationType: 'internal' } });
  setRouteParts({ path: toURL.pathname, queryString: toURL.search });
  return internalNavRes;
  };

packages/nextjs/src/app-router/client/useAwaitableNavigate.ts

@@ -3,7 +3,7 @@
 import { useRouter } from 'next/navigation';
 import { useEffect, useRef, useTransition } from 'react';
 
-type NavigateFunction = ReturnType<typeof useRouter>['push'];
+import type { NextClerkProviderProps } from '../../types';
 
 /**
  * Creates an "awaitable" navigation function that will do its best effort to wait for Next.js to finish its route transition.
@@ -12,31 +12,48 @@ type NavigateFunction = ReturnType<typeof useRouter>['push'];
  * `isPending` to flush the stored promises and ensure the navigates "resolve".
  */
 export const useAwaitableNavigate = () => {
- // eslint-disable-next-line @typescript-eslint/unbound-method
- const { push } = useRouter();
+ const router = useRouter();
  const [isPending, startTransition] = useTransition();
- const clerkNavRef = useRef<(...args: Parameters<NavigateFunction>) => Promise<void>>();
+ const clerkNavRef = useRef<NonNullable<NextClerkProviderProps['routerPush']>>();
  const clerkNavPromiseBuffer = useRef<(() => void)[]>([]);
 
  // Set the navigation function reference only once
  if (!clerkNavRef.current) {
- clerkNavRef.current = (to, opts) => {
+ clerkNavRef.current = ((to, opts) => {
  return new Promise<void>(res => {
  clerkNavPromiseBuffer.current.push(res);
  startTransition(() => {
- push(to, opts);
+ // If the navigation is internal, we should use the history API to navigate
+ // as this is the way to perform a shallow navigation in Next.js App Router
+ // without unmounting/remounting the page or fetching data from the server.
+ if (opts?.__internal_metadata?.navigationType === 'internal') {
+ // In 14.1.0, useSearchParams becomes reactive to shallow updates,
+ // but only if passing `null` as the history state.
+ // Older versions need to maintain the history state for push to work,
+ // without affecting how the Next router works.
+ const state = ((window as any).next?.version ?? '') < '14.1.0' ? history.state : null;
+ window.history.pushState(state, '', to);
+ } else {
+ // If the navigation is external (usually when navigating away from the component but still within the app),
+ // we should use the Next.js router to navigate as it will handle updating the URL and also
+ // fetching the new page if necessary.
+ router.push(to);
+ }
  });
  });
- };
+ }) as NextClerkProviderProps['routerPush'];
  }
 
  // Handle flushing the promise buffer when pending is false. If pending is false and there are promises in the buffer we should be able to safely flush them.
  useEffect(() => {
- if (isPending) return;
+ if (isPending) {
+ return;
+ }
 
  if (clerkNavPromiseBuffer?.current?.length) {
  clerkNavPromiseBuffer.current.forEach(resolve => resolve());
  }
+
  clerkNavPromiseBuffer.current = [];
  }, [isPending]);
 

packages/nextjs/src/client-boundary/usePathnameWithoutCatchAll.tsx

@@ -1,16 +1,23 @@
 import { useRouter } from 'next/compat/router';
+import React from 'react';
 
 export const usePathnameWithoutWithCatchAll = () => {
+ const pathRef = React.useRef<string>();
  // The compat version of useRouter returns null instead of throwing an error
  // when used inside app router instead of pages router
  // we use it to detect if the component is used inside pages or app router
  // so we can use the correct algorithm to get the path
  const pagesRouter = useRouter();
 
  if (pagesRouter) {
- // in pages router things are simpler as the pathname includes the catch all route
- // which starts with [[... and we can just remove it
- return pagesRouter.pathname.replace(/\/\[\[\.\.\..*/, '');
+ if (pathRef.current) {
+ return pathRef.current;
+ } else {
+ // in pages router things are simpler as the pathname includes the catch all route
+ // which starts with [[... and we can just remove it
+ pathRef.current = pagesRouter.pathname.replace(/\/\[\[\.\.\..*/, '');
+ return pathRef.current;
+ }
  }
 
  // require is used to avoid importing next/navigation when the pages router is used,
@@ -38,5 +45,10 @@ export const usePathnameWithoutWithCatchAll = () => {
  .flat(Infinity);
  // so we end up with the pathname where the components are mounted at
  // eg /user/123/profile/security will return /user/123/profile as the path
- return `/${pathParts.slice(0, pathParts.length - catchAllParams.length).join('/')}`;
+ if (pathRef.current) {
+ return pathRef.current;
+ } else {
+ pathRef.current = `/${pathParts.slice(0, pathParts.length - catchAllParams.length).join('/')}`;
+ return pathRef.current;
+ }
 };

.changeset/olive-files-listen.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/nextjs': patch
+'@clerk/types': patch
+---
+
+Prevent Clerk component flickering when mounted in a Next.js app using App Router

packages/clerk-js/src/core/clerk.redirects.test.ts

@@ -126,56 +126,56 @@ describe('Clerk singleton - Redirects', () => {
  await clerkForProductionInstance.redirectToSignIn({ redirectUrl: 'https://www.example.com/' });
  await clerkForDevelopmentInstance.redirectToSignIn({ redirectUrl: 'https://www.example.com/' });
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/sign-in#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
  });
 
  it('redirects to signUpUrl', async () => {
  await clerkForProductionInstance.redirectToSignUp({ redirectUrl: 'https://www.example.com/' });
  await clerkForDevelopmentInstance.redirectToSignUp({ redirectUrl: 'https://www.example.com/' });
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/sign-up#/?redirect_url=https%3A%2F%2Fwww.example.com%2F');
  });
 
  it('redirects to userProfileUrl', async () => {
  await clerkForProductionInstance.redirectToUserProfile();
  await clerkForDevelopmentInstance.redirectToUserProfile();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/user-profile');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/user-profile');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/user-profile');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/user-profile');
  });
 
  it('redirects to afterSignUp', async () => {
  await clerkForProductionInstance.redirectToAfterSignUp();
  await clerkForDevelopmentInstance.redirectToAfterSignUp();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/');
  });
 
  it('redirects to afterSignIn', async () => {
  await clerkForProductionInstance.redirectToAfterSignIn();
  await clerkForDevelopmentInstance.redirectToAfterSignIn();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/');
  });
 
  it('redirects to create organization', async () => {
  await clerkForProductionInstance.redirectToCreateOrganization();
  await clerkForDevelopmentInstance.redirectToCreateOrganization();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/create-organization');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/create-organization');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/create-organization');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/create-organization');
  });
 
  it('redirects to organization profile', async () => {
  await clerkForProductionInstance.redirectToOrganizationProfile();
  await clerkForDevelopmentInstance.redirectToOrganizationProfile();
 
- expect(mockNavigate).toHaveBeenNthCalledWith(1, '/organization-profile');
- expect(mockNavigate).toHaveBeenNthCalledWith(2, '/organization-profile');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/organization-profile');
+ expect(mockNavigate.mock.calls[1][0]).toBe('/organization-profile');
  });
  });
 

packages/clerk-js/src/core/clerk.test.ts

@@ -571,7 +571,7 @@ describe('Clerk singleton', () => {
  const res = sut.navigate(toUrl);
  expect(res.then).toBeDefined();
  expect(mockHref).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith('/path#hash');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/path#hash');
  expect(logSpy).not.toBeCalled();
  });
 
@@ -591,7 +591,7 @@ describe('Clerk singleton', () => {
  const res = sut.navigate(toUrl);
  expect(res.then).toBeDefined();
  expect(mockHref).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith('/path#hash');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/path#hash');
 
  expect(logSpy).toBeCalledTimes(1);
  expect(logSpy).toBeCalledWith(`Clerk is navigating to: ${toUrl}`);
@@ -721,7 +721,7 @@ describe('Clerk singleton', () => {
 
  await waitFor(() => {
  expect(mockSignUpCreate).toHaveBeenCalledWith({ transfer: true });
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up#/continue');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/continue');
  });
  });
 
@@ -934,7 +934,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/factor-two');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/factor-two');
  });
  });
 
@@ -977,7 +977,7 @@ describe('Clerk singleton', () => {
  });
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/custom-2fa');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/custom-2fa');
  });
  });
 
@@ -1032,7 +1032,7 @@ describe('Clerk singleton', () => {
  });
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/custom-sign-in');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/custom-sign-in');
  });
  });
 
@@ -1088,7 +1088,7 @@ describe('Clerk singleton', () => {
  } as any);
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/custom-sign-in');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/custom-sign-in');
  });
  });
 
@@ -1136,7 +1136,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up');
  });
  });
 
@@ -1184,7 +1184,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up');
  });
  });
 
@@ -1226,7 +1226,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up#/continue');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/continue');
  });
  });
 
@@ -1273,7 +1273,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up#/verify-email-address');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up#/verify-email-address');
  });
  });
 
@@ -1305,7 +1305,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/factor-one');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/factor-one');
  });
  });
 
@@ -1353,7 +1353,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/factor-one');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/factor-one');
  });
  });
 
@@ -1412,7 +1412,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-up');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-up');
  });
  });
 
@@ -1463,7 +1463,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in');
  });
  });
 
@@ -1501,7 +1501,7 @@ describe('Clerk singleton', () => {
  await sut.handleRedirectCallback();
 
  await waitFor(() => {
- expect(mockNavigate).toHaveBeenCalledWith('/sign-in#/reset-password');
+ expect(mockNavigate.mock.calls[0][0]).toBe('/sign-in#/reset-password');
  });
  });
  });
@@ -1568,7 +1568,7 @@ describe('Clerk singleton', () => {
 
  await waitFor(() => {
  expect(mockSetActive).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith(redirectUrl);
+ expect(mockNavigate.mock.calls[0][0]).toBe(redirectUrl);
  });
  });
 
@@ -1628,7 +1628,7 @@ describe('Clerk singleton', () => {
 
  await waitFor(() => {
  expect(mockSetActive).not.toHaveBeenCalled();
- expect(mockNavigate).toHaveBeenCalledWith(redirectUrl);
+ expect(mockNavigate.mock.calls[0][0]).toBe(redirectUrl);
  });
  });
 

packages/clerk-js/src/core/clerk.ts

@@ -726,8 +726,9 @@ export class Clerk implements ClerkInterface {
  return;
  }
 
+ const metadata = options?.metadata ? { __internal_metadata: options?.metadata } : undefined;
  // React router only wants the path, search or hash portion.
- return await customNavigate(stripOrigin(toURL));
+ return await customNavigate(stripOrigin(toURL), metadata);
  };
 
  public buildUrlWithAuth(to: string): string {

packages/clerk-js/src/ui/router/BaseRouter.tsx

@@ -1,4 +1,5 @@
 import { useClerk } from '@clerk/shared/react';
+import type { NavigateOptions } from '@clerk/types';
 import qs from 'qs';
 import React from 'react';
 
@@ -14,7 +15,7 @@ interface BaseRouterProps {
  startPath: string;
  getPath: () => string;
  getQueryString: () => string;
- internalNavigate: (toURL: URL) => Promise<any> | any;
+ internalNavigate: (toURL: URL, options?: NavigateOptions) => Promise<any> | any;
  onExternalNavigate?: () => any;
  refreshEvents?: Array<keyof WindowEventMap>;
  preservedParams?: string[];
@@ -114,7 +115,7 @@ export const BaseRouter = ({
  });
  toURL.search = qs.stringify(toQueryParams);
  }
- const internalNavRes = await internalNavigate(toURL);
+ const internalNavRes = await internalNavigate(toURL, { metadata: { navigationType: 'internal' } });
  setRouteParts({ path: toURL.pathname, queryString: toURL.search });
  return internalNavRes;
  };

packages/nextjs/src/app-router/client/useAwaitableNavigate.ts

@@ -3,7 +3,7 @@
 import { useRouter } from 'next/navigation';
 import { useEffect, useRef, useTransition } from 'react';
 
-type NavigateFunction = ReturnType<typeof useRouter>['push'];
+import type { NextClerkProviderProps } from '../../types';
 
 /**
  * Creates an "awaitable" navigation function that will do its best effort to wait for Next.js to finish its route transition.
@@ -12,31 +12,48 @@ type NavigateFunction = ReturnType<typeof useRouter>['push'];
  * `isPending` to flush the stored promises and ensure the navigates "resolve".
  */
 export const useAwaitableNavigate = () => {
- // eslint-disable-next-line @typescript-eslint/unbound-method
- const { push } = useRouter();
+ const router = useRouter();
  const [isPending, startTransition] = useTransition();
- const clerkNavRef = useRef<(...args: Parameters<NavigateFunction>) => Promise<void>>();
+ const clerkNavRef = useRef<NonNullable<NextClerkProviderProps['routerPush']>>();
  const clerkNavPromiseBuffer = useRef<(() => void)[]>([]);
 
  // Set the navigation function reference only once
  if (!clerkNavRef.current) {
- clerkNavRef.current = (to, opts) => {
+ clerkNavRef.current = ((to, opts) => {
  return new Promise<void>(res => {
  clerkNavPromiseBuffer.current.push(res);
  startTransition(() => {
- push(to, opts);
+ // If the navigation is internal, we should use the history API to navigate
+ // as this is the way to perform a shallow navigation in Next.js App Router
+ // without unmounting/remounting the page or fetching data from the server.
+ if (opts?.__internal_metadata?.navigationType === 'internal') {
+ // In 14.1.0, useSearchParams becomes reactive to shallow updates,
+ // but only if passing `null` as the history state.
+ // Older versions need to maintain the history state for push to work,
+ // without affecting how the Next router works.
+ const state = ((window as any).next?.version ?? '') < '14.1.0' ? history.state : null;
+ window.history.pushState(state, '', to);
+ } else {
+ // If the navigation is external (usually when navigating away from the component but still within the app),
+ // we should use the Next.js router to navigate as it will handle updating the URL and also
+ // fetching the new page if necessary.
+ router.push(to);
+ }
  });
  });
- };
+ }) as NextClerkProviderProps['routerPush'];
  }
 
  // Handle flushing the promise buffer when pending is false. If pending is false and there are promises in the buffer we should be able to safely flush them.
  useEffect(() => {
- if (isPending) return;
+ if (isPending) {
+ return;
+ }
 
  if (clerkNavPromiseBuffer?.current?.length) {
  clerkNavPromiseBuffer.current.forEach(resolve => resolve());
  }
+
  clerkNavPromiseBuffer.current = [];
  }, [isPending]);
 

packages/nextjs/src/client-boundary/usePathnameWithoutCatchAll.tsx

@@ -1,16 +1,23 @@
 import { useRouter } from 'next/compat/router';
+import React from 'react';
 
 export const usePathnameWithoutWithCatchAll = () => {
+ const pathRef = React.useRef<string>();
  // The compat version of useRouter returns null instead of throwing an error
  // when used inside app router instead of pages router
  // we use it to detect if the component is used inside pages or app router
  // so we can use the correct algorithm to get the path
  const pagesRouter = useRouter();
 
  if (pagesRouter) {
- // in pages router things are simpler as the pathname includes the catch all route
- // which starts with [[... and we can just remove it
- return pagesRouter.pathname.replace(/\/\[\[\.\.\..*/, '');
+ if (pathRef.current) {
+ return pathRef.current;
+ } else {
+ // in pages router things are simpler as the pathname includes the catch all route
+ // which starts with [[... and we can just remove it
+ pathRef.current = pagesRouter.pathname.replace(/\/\[\[\.\.\..*/, '');
+ return pathRef.current;
+ }
  }
 
  // require is used to avoid importing next/navigation when the pages router is used,
@@ -38,5 +45,10 @@ export const usePathnameWithoutWithCatchAll = () => {
  .flat(Infinity);
  // so we end up with the pathname where the components are mounted at
  // eg /user/123/profile/security will return /user/123/profile as the path
- return `/${pathParts.slice(0, pathParts.length - catchAllParams.length).join('/')}`;
+ if (pathRef.current) {
+ return pathRef.current;
+ } else {
+ pathRef.current = `/${pathParts.slice(0, pathParts.length - catchAllParams.length).join('/')}`;
+ return pathRef.current;
+ }
 };