feat(clerk-js,types): Add routerDebug option in Clerk to log navigation destination urls (#2223)

Author: dimkl

.changeset/sharp-trains-ring.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/types': minor
+---
+
+Add `routerDebug` option in `Clerk.load()` to log the destination URLs when navigating

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

@@ -516,23 +516,31 @@ describe('Clerk singleton', () => {
 
   describe('.navigate(to)', () => {
     let sut: Clerk;
+    let logSpy;
 
     beforeEach(() => {
+      logSpy = jest.spyOn(console, 'log');
       sut = new Clerk(productionPublishableKey);
     });
 
+    afterEach(() => {
+      logSpy?.mockRestore();
+    });
+
     it('uses window location if a custom navigate is not defined', async () => {
       await sut.load();
       const toUrl = 'http://test.host/';
       await sut.navigate(toUrl);
       expect(mockHref).toHaveBeenCalledWith(toUrl);
+      expect(logSpy).not.toBeCalled();
     });
 
     it('uses window location if a custom navigate is defined but destination has different origin', async () => {
       await sut.load({ routerPush: mockNavigate });
       const toUrl = 'https://www.origindifferent.com/';
       await sut.navigate(toUrl);
       expect(mockHref).toHaveBeenCalledWith(toUrl);
+      expect(logSpy).not.toBeCalled();
     });
 
     it('wraps custom navigate method in a promise if provided and it sync', async () => {
@@ -542,6 +550,29 @@ describe('Clerk singleton', () => {
       expect(res.then).toBeDefined();
       expect(mockHref).not.toHaveBeenCalled();
       expect(mockNavigate).toHaveBeenCalledWith('/path#hash');
+      expect(logSpy).not.toBeCalled();
+    });
+
+    it('logs navigation external navigation when routerDebug is enabled', async () => {
+      await sut.load({ routerDebug: true });
+      const toUrl = 'http://test.host/';
+      await sut.navigate(toUrl);
+      expect(mockHref).toHaveBeenCalledWith(toUrl);
+
+      expect(logSpy).toBeCalledTimes(1);
+      expect(logSpy).toBeCalledWith(`Clerk is navigating to: ${toUrl}`);
+    });
+
+    it('logs navigation custom navigation when routerDebug is enabled', async () => {
+      await sut.load({ routerPush: mockNavigate, routerDebug: true });
+      const toUrl = 'http://test.host/path#hash';
+      const res = sut.navigate(toUrl);
+      expect(res.then).toBeDefined();
+      expect(mockHref).not.toHaveBeenCalled();
+      expect(mockNavigate).toHaveBeenCalledWith('/path#hash');
+
+      expect(logSpy).toBeCalledTimes(1);
+      expect(logSpy).toBeCalledWith(`Clerk is navigating to: ${toUrl}`);
     });
   });
 

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

@@ -165,8 +165,7 @@ export class Clerk implements ClerkInterface {
   #environment?: EnvironmentResource | null;
   //@ts-expect-error with being undefined even though it's not possible - related to issue with ts and error thrower
   #fapiClient: FapiClient;
-  //@ts-expect-error with undefined even though it's not possible - related to issue with ts and error thrower
-  #instanceType: InstanceType;
+  #instanceType?: InstanceType;
   #isReady = false;
 
   #listeners: Array<(emission: Resources) => void> = [];
@@ -675,6 +674,10 @@ export class Clerk implements ClerkInterface {
     const customNavigate =
       options?.replace && this.#options.routerReplace ? this.#options.routerReplace : this.#options.routerPush;
 
+    if (this.#options.routerDebug) {
+      console.log(`Clerk is navigating to: ${toURL}`);
+    }
+
     if (toURL.origin !== window.location.origin || !customNavigate) {
       windowNavigate(toURL);
       return;

packages/types/src/clerk.retheme.ts

@@ -496,17 +496,19 @@ export type BuildUrlWithAuthParams = {
   useQueryParam?: boolean | null;
 };
 
-// TODO: Make sure Isomorphic Clerk navigate can work with the correct type:
-// (to: string) => Promise<unknown>
 export type CustomNavigation = (to: string, options?: NavigateOptions) => Promise<unknown> | void;
 
 export type ClerkThemeOptions = DeepSnakeToCamel<DeepPartial<DisplayThemeJSON>>;
 
 export interface ClerkOptions {
   appearance?: Appearance;
   localization?: LocalizationResource;
+  /**
+   * Navigation
+   */
   routerPush?: (to: string) => Promise<unknown> | unknown;
   routerReplace?: (to: string) => Promise<unknown> | unknown;
+  routerDebug?: boolean;
   polling?: boolean;
   selectInitialSession?: (client: ClientResource) => ActiveSessionResource | null;
   /** Controls if ClerkJS will load with the standard browser setup using Clerk cookies */

packages/types/src/clerk.ts

@@ -496,17 +496,20 @@ export type BuildUrlWithAuthParams = {
   useQueryParam?: boolean | null;
 };
 
-// TODO: Make sure Isomorphic Clerk navigate can work with the correct type:
-// (to: string) => Promise<unknown>
 export type CustomNavigation = (to: string, options?: NavigateOptions) => Promise<unknown> | void;
 
 export type ClerkThemeOptions = DeepSnakeToCamel<DeepPartial<DisplayThemeJSON>>;
 
 export interface ClerkOptions {
   appearance?: Appearance;
   localization?: LocalizationResource;
+  /**
+   * Navigation
+   */
   routerPush?: (to: string) => Promise<unknown> | unknown;
   routerReplace?: (to: string) => Promise<unknown> | unknown;
+  routerDebug?: boolean;
+
   polling?: boolean;
   selectInitialSession?: (client: ClientResource) => ActiveSessionResource | null;
   /** Controls if ClerkJS will load with the standard browser setup using Clerk cookies */