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;
+  }
 };