chore(types,clerk-react): Make routerPush / routerReplace both required or both optional (#2227)

* chore(types): Use `Without` generic to resolve issues with `Omit` and complex types

* chore(types): Make `routerPush` and `routerReplace` options both required or both optional

In order to use unions we converted the `ClerkOptions`
interface to type to compose the union for mutual required
or optional for `routerPush` and `routerReplace` options.

* chore(repo): Ignore test runner files and CHANGELOG.md from formatting

Fixed the 3 slowed formatted files (filename ignored -> ms saved):
- packages/backend/tests/cloudflare-miniflare/worker.js -> 1582ms
- packages/backend/tests/edge-runtime/bundle.js -> 1477ms
- packages/clerk-js/CHANGELOG.md -> 177ms

* chore(repo): Add changeset

* chore(repo): Update ui-retheme-changes-reminder to notify for files with retheme variant

* Update .changeset/tiny-forks-sit.md

Co-authored-by: Lennart <lekoarts@gmail.com>

---------

Co-authored-by: Lennart <lekoarts@gmail.com>

Author: dimkl

.changeset/tiny-forks-sit.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-react': minor
+'@clerk/types': minor
+---
+
+Update the TypeScript types of `<ClerkProvider />`. If you use the `routerPush` prop you're now required to also provide the `routerReplace` prop (or other way around). You can also not provide them at all since both props are optional.

.github/workflows/ui-retheme-changes-reminder.yml

@@ -6,7 +6,13 @@ on:
       - main
     paths:
       - 'packages/clerk-js/src/ui/**'
-
+      # files with matching `*.retheme.ts` retheme variant
+      - 'packages/localizations/src/en-US.ts'
+      - 'packages/localizations/src/index.ts'
+      - 'packages/types/src/appearance.ts'
+      - 'packages/types/src/clerk.ts'
+      - 'packages/types/src/index.ts'
+      - 'packages/types/src/localization.ts'
 jobs:
   check-changes:
     runs-on: ubuntu-latest

.prettierignore

@@ -15,4 +15,6 @@ dist
 examples
 node_modules
 package-lock.json
-playground
+playground
+packages/backend/tests/**/*.js
+/**/CHANGELOG.md

packages/react/src/contexts/__tests__/ClerkProvider.test.tsx

@@ -224,4 +224,23 @@ describe('ClerkProvider', () => {
       expectTypeOf({ publishableKey: 'test' }).not.toMatchTypeOf<ClerkProviderProps>();
     });
   });
+
+  describe('navigation options', () => {
+    it('expects both routerPush & routerReplace to pass', () => {
+      expectTypeOf({
+        publishableKey: 'test',
+        children: '',
+        routerPush: () => {},
+        routerReplace: () => {},
+      }).toMatchTypeOf<ClerkProviderProps>();
+    });
+
+    it('errors if one of routerPush / routerReplace is passed', () => {
+      expectTypeOf({
+        publishableKey: 'test',
+        children: '',
+        routerPush: () => {},
+      }).not.toMatchTypeOf<ClerkProviderProps>();
+    });
+  });
 });

packages/react/src/types.ts

@@ -11,6 +11,7 @@ import type {
   SignInRedirectOptions,
   SignUpRedirectOptions,
   UserResource,
+  Without,
 } from '@clerk/types';
 import type React from 'react';
 
@@ -23,7 +24,7 @@ declare global {
   }
 }
 
-export type IsomorphicClerkOptions = Omit<ClerkOptions, 'isSatellite'> & {
+export type IsomorphicClerkOptions = Without<ClerkOptions, 'isSatellite'> & {
   Clerk?: ClerkProp;
   clerkJSUrl?: string;
   clerkJSVariant?: 'headless' | '';
@@ -37,19 +38,10 @@ export type ClerkProviderProps = IsomorphicClerkOptions & {
   initialState?: InitialState;
 };
 
-// TODO(@dimkl): replacing it with the following make nextjs type tests fail
-//   `Exclude<IsomorphicClerkOptions, 'publishableKey'> & { publishableKey?: string }`
-// find another way to reduce the duplication.
-export type ClerkProviderOptionsWrapper = Omit<ClerkOptions, 'isSatellite'> & {
-  Clerk?: ClerkProp;
-  clerkJSUrl?: string;
-  clerkJSVariant?: 'headless' | '';
-  clerkJSVersion?: string;
-  sdkMetadata?: SDKMetadata;
+export type ClerkProviderOptionsWrapper = Without<IsomorphicClerkOptions, 'publishableKey'> & {
   publishableKey?: string;
-} & MultiDomainAndOrProxy & {
-    children: React.ReactNode;
-  };
+  children: React.ReactNode;
+};
 
 export interface BrowserClerkConstructor {
   new (publishableKey: string, options?: DomainOrProxyUrl): BrowserClerk;
@@ -75,7 +67,7 @@ export interface MountProps {
 }
 
 export interface HeadlessBrowserClerk extends Clerk {
-  load: (opts?: Omit<ClerkOptions, 'isSatellite'>) => Promise<void>;
+  load: (opts?: Without<ClerkOptions, 'isSatellite'>) => Promise<void>;
   updateClient: (client: ClientResource) => void;
 }
 

packages/types/src/clerk.retheme.ts

@@ -495,7 +495,25 @@ export type CustomNavigation = (to: string, options?: NavigateOptions) => Promis
 
 export type ClerkThemeOptions = DeepSnakeToCamel<DeepPartial<DisplayThemeJSON>>;
 
-export interface ClerkOptions {
+/**
+ * Navigation options used to replace or push history changes.
+ * Both `routerPush` & `routerReplace` OR none options should be passed.
+ */
+type ClerkOptionsNavigationFn =
+  | {
+      routerPush?: never;
+      routerReplace?: never;
+    }
+  | {
+      routerPush: (to: string) => Promise<unknown> | unknown;
+      routerReplace: (to: string) => Promise<unknown> | unknown;
+    };
+
+type ClerkOptionsNavigation = ClerkOptionsNavigationFn & {
+  routerDebug?: boolean;
+};
+
+export type ClerkOptions = ClerkOptionsNavigation & {
   appearance?: Appearance;
   localization?: LocalizationResource;
   /**
@@ -535,7 +553,7 @@ export interface ClerkOptions {
       };
 
   sdkMetadata?: SDKMetadata;
-}
+};
 
 export interface NavigateOptions {
   replace?: boolean;

packages/types/src/clerk.ts

@@ -495,16 +495,27 @@ export type CustomNavigation = (to: string, options?: NavigateOptions) => Promis
 
 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;
+/**
+ * Navigation options used to replace or push history changes.
+ * Both `routerPush` & `routerReplace` OR none options should be passed.
+ */
+type ClerkOptionsNavigationFn =
+  | {
+      routerPush?: never;
+      routerReplace?: never;
+    }
+  | {
+      routerPush: (to: string) => Promise<unknown> | unknown;
+      routerReplace: (to: string) => Promise<unknown> | unknown;
+    };
+
+type ClerkOptionsNavigation = ClerkOptionsNavigationFn & {
   routerDebug?: boolean;
+};
 
+export type ClerkOptions = ClerkOptionsNavigation & {
+  appearance?: Appearance;
+  localization?: LocalizationResource;
   polling?: boolean;
   selectInitialSession?: (client: ClientResource) => ActiveSessionResource | null;
   /** Controls if ClerkJS will load with the standard browser setup using Clerk cookies */
@@ -536,7 +547,7 @@ export interface ClerkOptions {
       };
 
   sdkMetadata?: SDKMetadata;
-}
+};
 
 export interface NavigateOptions {
   replace?: boolean;