feat(elements): Remove direct reliance on next and clerk-react

.changeset/good-jeans-call.md

@@ -0,0 +1,7 @@
+---
+"@clerk/elements": minor
+"@clerk/nextjs": minor
+"@clerk/shared": minor
+---
+
+Remove `@clerk/elements` reliance on `next` and `@clerk/clerk-react` directly. The host router is now provided by `@clerk/nextjs`.

packages/elements/package.json

@@ -94,9 +94,7 @@
  "typescript": "*"
  },
  "peerDependencies": {
- "@clerk/clerk-react": "^5.0.0",
  "@clerk/shared": "^2.0.0",
- "next": "^13.5.4 || ^14.0.3 || ^15.0.0-rc",
  "react": "^18.0.0 || ^19.0.0-beta",
  "react-dom": "^18.0.0 || ^19.0.0-beta"
  },

packages/elements/src/internals/constants/index.ts

@@ -1,11 +1,18 @@
+import { safeAccess } from '~/utils/safe-access';
+
 export const SSO_CALLBACK_PATH_ROUTE = '/sso-callback';
 export const CHOOSE_SESSION_PATH_ROUTE = '/choose';
 export const MAGIC_LINK_VERIFY_PATH_ROUTE = '/verify';
 
-export const SIGN_IN_DEFAULT_BASE_PATH =
- process.env.CLERK_SIGN_IN_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_IN_URL ?? '/sign-in';
-export const SIGN_UP_DEFAULT_BASE_PATH =
- process.env.CLERK_SIGN_UP_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL ?? '/sign-up';
+// TODO: remove reliance on next-specific variables here
+export const SIGN_IN_DEFAULT_BASE_PATH = safeAccess(
+ () => process.env.CLERK_SIGN_IN_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_IN_URL,
+ '/sign-in',
+);
+export const SIGN_UP_DEFAULT_BASE_PATH = safeAccess(
+ () => process.env.CLERK_SIGN_UP_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL,
+ '/sign-up',
+);
 
 // The version that Next added support for the window.history.pushState and replaceState APIs.
 // ref: https://nextjs.org/blog/next-14-1#windowhistorypushstate-and-windowhistoryreplacestate

packages/elements/src/internals/machines/shared/shared.actors.ts

@@ -10,7 +10,7 @@ export const clerkLoader = fromCallback<EventObject, Clerk | LoadedClerk>(({ sen
  if (clerk.loaded) {
  reportLoaded();
  } else if ('addOnLoaded' in clerk) {
- // @ts-expect-error - Expects `addOnLoaded` from @clerk/clerk-react's IsomorphicClerk.
+ // @ts-expect-error - Expects `addOnLoaded` from @clerk/shared/react's IsomorphicClerk.
  clerk.addOnLoaded(reportLoaded);
  } else {
  sendBack({ type: 'ERROR', message: 'Clerk client could not be loaded' });

packages/elements/src/internals/utils/inspector/browser/index.ts

@@ -1,12 +1,16 @@
 import { isTruthy } from '@clerk/shared/underscore';
 import { createBrowserInspector } from '@statelyai/inspect';
 
+import { safeAccess } from '~/utils/safe-access';
+
 export const getInspector = () => {
  if (
  __DEV__ &&
  typeof window !== 'undefined' &&
  process.env.NODE_ENV === 'development' &&
- isTruthy(process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG_UI ?? process.env.CLERK_ELEMENTS_DEBUG_UI)
+ isTruthy(
+ safeAccess(() => process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG_UI ?? process.env.CLERK_ELEMENTS_DEBUG_UI, false),
+ )
  ) {
  const { inspect } = createBrowserInspector({
  autoStart: true,

packages/elements/src/internals/utils/inspector/console/index.ts

@@ -1,16 +1,20 @@
 import { isTruthy } from '@clerk/shared/underscore';
 
+import { safeAccess } from '~/utils/safe-access';
+
 import { createConsoleInspector } from './console';
 
 export function getInspector() {
  if (
  __DEV__ &&
  process.env.NODE_ENV === 'development' &&
- isTruthy(process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG ?? process.env.CLERK_ELEMENTS_DEBUG)
+ isTruthy(
+ safeAccess(() => process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG_UI ?? process.env.CLERK_ELEMENTS_DEBUG_UI, false),
+ )
  ) {
  return createConsoleInspector({
  enabled: true,
- debugServer: isTruthy(process.env.CLERK_ELEMENTS_DEBUG_SERVER),
+ debugServer: isTruthy(safeAccess(() => process.env.CLERK_ELEMENTS_DEBUG_SERVER, false)),
  });
  }
  return undefined;

packages/elements/src/react/common/form/input.tsx

@@ -1,5 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
 import { logger } from '@clerk/shared/logger';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import type {
  Control as RadixControl,

packages/elements/src/react/common/loading.tsx

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import type { OAuthProvider, SamlStrategy, Web3Provider } from '@clerk/types';
 import { useSelector } from '@xstate/react';

packages/elements/src/react/hooks/use-password.hook.ts

@@ -1,5 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
 import { noop } from '@clerk/shared';
+import { useClerk } from '@clerk/shared/react';
 import type { PasswordSettingsData, PasswordValidation } from '@clerk/types';
 import * as React from 'react';
 

packages/elements/src/react/hooks/use-third-party-provider.hook.ts

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import type { OAuthProvider, SamlStrategy, Web3Provider } from '@clerk/types';
 import type React from 'react';
 import { useCallback } from 'react';

packages/elements/src/react/router/index.ts

@@ -1,3 +1,2 @@
-export { useNextRouter } from './next';
 export { Route, Router, useClerkRouter } from '@clerk/shared/router';
 export { useVirtualRouter } from './virtual';

packages/elements/src/react/sign-in/root.tsx

@@ -1,4 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
+import { useClerkHostRouter } from '@clerk/shared/router';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import { useSelector } from '@xstate/react';
 import React, { useEffect } from 'react';
@@ -9,7 +10,7 @@ import { FormStoreProvider, useFormStore } from '~/internals/machines/form/form.
 import type { SignInRouterInitEvent } from '~/internals/machines/sign-in';
 import { SignInRouterMachine } from '~/internals/machines/sign-in';
 import { inspect } from '~/internals/utils/inspector';
-import { Router, useClerkRouter, useNextRouter, useVirtualRouter } from '~/react/router';
+import { Router, useClerkRouter, useVirtualRouter } from '~/react/router';
 import { SignInRouterCtx } from '~/react/sign-in/context';
 
 import { Form } from '../common/form';
@@ -39,8 +40,7 @@ function SignInFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  return;
  }
 
- // @ts-expect-error -- This is actually an IsomorphicClerk instance
- clerk.addOnLoaded(() => {
+ const cb = () => {
  const evt: SignInRouterInitEvent = {
  type: 'INIT',
  clerk,
@@ -53,7 +53,14 @@ function SignInFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  if (actor.getSnapshot().can(evt)) {
  actor.send(evt);
  }
- });
+ };
+
+ if ('addOnLoaded' in clerk) {
+ // @ts-expect-error - addOnLoaded doesn't exist on the clerk type, but it does on IsomorphicClerk, which can be hit when Elements is used standalone
+ clerk.addOnLoaded(cb);
+ } else {
+ cb();
+ }
 
  // Ensure that the latest instantiated formRef is attached to the router
  if (formRef && actor.getSnapshot().can({ type: 'RESET.STEP' })) {
@@ -123,8 +130,7 @@ export function SignInRoot({
  }),
  );
 
- // TODO: eventually we'll rely on the framework SDK to specify its host router, but for now we'll default to Next.js
- const router = (routing === ROUTING.virtual ? useVirtualRouter : useNextRouter)();
+ const router = (routing === ROUTING.virtual ? useVirtualRouter : useClerkHostRouter)();
  const isRootPath = path === router.pathname();
 
  return (

packages/elements/src/react/sign-in/step.tsx

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 
 import { ClerkElementsRuntimeError } from '~/internals/errors';

packages/elements/src/react/sign-up/root.tsx

@@ -1,4 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
+import { useClerkHostRouter } from '@clerk/shared/router';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import { useSelector } from '@xstate/react';
 import { useEffect } from 'react';
@@ -9,7 +10,7 @@ import { FormStoreProvider, useFormStore } from '~/internals/machines/form/form.
 import type { SignUpRouterInitEvent } from '~/internals/machines/sign-up';
 import { SignUpRouterMachine } from '~/internals/machines/sign-up';
 import { inspect } from '~/internals/utils/inspector';
-import { Router, useClerkRouter, useNextRouter, useVirtualRouter } from '~/react/router';
+import { Router, useClerkRouter, useVirtualRouter } from '~/react/router';
 import { SignUpRouterCtx } from '~/react/sign-up/context';
 
 import { Form } from '../common/form';
@@ -39,8 +40,7 @@ function SignUpFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  return;
  }
 
- // @ts-expect-error -- This is actually an IsomorphicClerk instance
- clerk.addOnLoaded(() => {
+ const cb = () => {
  const evt: SignUpRouterInitEvent = {
  type: 'INIT',
  clerk,
@@ -61,7 +61,14 @@ function SignUpFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  formRef,
  });
  }
- });
+ };
+
+ if ('addOnLoaded' in clerk) {
+ // @ts-expect-error - addOnLoaded doesn't exist on the clerk type, but it does on IsomorphicClerk, which can be hit when Elements is used standalone
+ clerk.addOnLoaded(cb);
+ } else {
+ cb();
+ }
  // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [clerk, exampleMode, formRef?.id, !!router, clerk.loaded]);
 
@@ -122,8 +129,7 @@ export function SignUpRoot({
  }),
  );
 
- // TODO: eventually we'll rely on the framework SDK to specify its host router, but for now we'll default to Next.js
- const router = (routing === ROUTING.virtual ? useVirtualRouter : useNextRouter)();
+ const router = (routing === ROUTING.virtual ? useVirtualRouter : useClerkHostRouter)();
  const isRootPath = path === router.pathname();
 
  return (

packages/elements/src/react/sign-up/step.tsx

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 
 import { ClerkElementsRuntimeError } from '~/internals/errors';

packages/elements/src/utils/safe-access.ts

@@ -0,0 +1,7 @@
+export function safeAccess(fn: any, fallback: any) {
+ try {
+ return fn();
+ } catch (e) {
+ return fallback;
+ }
+}

packages/nextjs/src/app-router/client/ClerkProvider.tsx

@@ -1,6 +1,8 @@
 'use client';
 import { ClerkProvider as ReactClerkProvider } from '@clerk/clerk-react';
-import { useRouter } from 'next/navigation';
+import type { ClerkHostRouter } from '@clerk/shared/router';
+import { ClerkHostRouterContext } from '@clerk/shared/router';
+import { usePathname, useRouter, useSearchParams } from 'next/navigation';
 import React, { useEffect, useTransition } from 'react';
 
 import { useSafeLayoutEffect } from '../../client-boundary/hooks/useSafeLayoutEffect';
@@ -17,12 +19,48 @@ declare global {
  __clerk_nav_await: Array<(value: void) => void>;
  __clerk_nav: (to: string) => Promise<void>;
  __clerk_internal_invalidateCachePromise: () => void | undefined;
+ next?: {
+ version: string;
+ };
  }
 }
 
+// The version that Next added support for the window.history.pushState and replaceState APIs.
+// ref: https://nextjs.org/blog/next-14-1#windowhistorypushstate-and-windowhistoryreplacestate
+export const NEXT_WINDOW_HISTORY_SUPPORT_VERSION = '14.1.0';
+
+/**
+ * Clerk router integration with Next.js's router.
+ */
+export const useNextRouter = (): ClerkHostRouter => {
+ const router = useRouter();
+ const pathname = usePathname();
+ // eslint-disable-next-line react-hooks/rules-of-hooks -- The order doesn't differ between renders as we're checking the execution environment.
+ const searchParams = typeof window === 'undefined' ? new URLSearchParams() : useSearchParams();
+
+ // The window.history APIs seem to prevent Next.js from triggering a full page re-render, allowing us to
+ // preserve internal state between steps.
+ const canUseWindowHistoryAPIs =
+ typeof window !== 'undefined' && window.next && window.next.version >= NEXT_WINDOW_HISTORY_SUPPORT_VERSION;
+
+ return {
+ mode: 'path',
+ name: 'NextRouter',
+ push: (path: string) => router.push(path),
+ replace: (path: string) =>
+ canUseWindowHistoryAPIs ? window.history.replaceState(null, '', path) : router.replace(path),
+ shallowPush(path: string) {
+ canUseWindowHistoryAPIs ? window.history.pushState(null, '', path) : router.push(path, {});
+ },
+ pathname: () => pathname,
+ searchParams: () => searchParams,
+ };
+};
+
 export const ClientClerkProvider = (props: NextClerkProviderProps) => {
  const { __unstable_invokeMiddlewareOnAuthStateChange = true, children } = props;
  const router = useRouter();
+ const clerkRouter = useNextRouter();
  const push = useAwaitablePush();
  const replace = useAwaitableReplace();
  const [isPending, startTransition] = useTransition();
@@ -57,7 +95,6 @@ export const ClientClerkProvider = (props: NextClerkProviderProps) => {
  return new Promise(res => {
  window.__clerk_internal_invalidateCachePromise = res;
  startTransition(() => {
- //@ts-expect-error next exists on window
  if (window.next?.version && typeof window.next.version === 'string' && window.next.version.startsWith('13')) {
  router.refresh();
  } else {
@@ -84,7 +121,7 @@ export const ClientClerkProvider = (props: NextClerkProviderProps) => {
  <ClerkNextOptionsProvider options={mergedProps}>
  <ReactClerkProvider {...mergedProps}>
  <ClerkJSScript router='app' />
-{children}
+<ClerkHostRouterContext.Provider value={clerkRouter}>{children}</ClerkHostRouterContext.Provider>
  </ReactClerkProvider>
  </ClerkNextOptionsProvider>
  );

.changeset/good-jeans-call.md

@@ -0,0 +1,7 @@
+---
+"@clerk/elements": minor
+"@clerk/nextjs": minor
+"@clerk/shared": minor
+---
+
+Remove `@clerk/elements` reliance on `next` and `@clerk/clerk-react` directly. The host router is now provided by `@clerk/nextjs`.

packages/elements/package.json

@@ -94,9 +94,7 @@
  "typescript": "*"
  },
  "peerDependencies": {
- "@clerk/clerk-react": "^5.0.0",
  "@clerk/shared": "^2.0.0",
- "next": "^13.5.4 || ^14.0.3 || ^15.0.0-rc",
  "react": "^18.0.0 || ^19.0.0-beta",
  "react-dom": "^18.0.0 || ^19.0.0-beta"
  },

packages/elements/src/internals/constants/index.ts

@@ -1,11 +1,18 @@
+import { safeAccess } from '~/utils/safe-access';
+
 export const SSO_CALLBACK_PATH_ROUTE = '/sso-callback';
 export const CHOOSE_SESSION_PATH_ROUTE = '/choose';
 export const MAGIC_LINK_VERIFY_PATH_ROUTE = '/verify';
 
-export const SIGN_IN_DEFAULT_BASE_PATH =
- process.env.CLERK_SIGN_IN_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_IN_URL ?? '/sign-in';
-export const SIGN_UP_DEFAULT_BASE_PATH =
- process.env.CLERK_SIGN_UP_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL ?? '/sign-up';
+// TODO: remove reliance on next-specific variables here
+export const SIGN_IN_DEFAULT_BASE_PATH = safeAccess(
+ () => process.env.CLERK_SIGN_IN_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_IN_URL,
+ '/sign-in',
+);
+export const SIGN_UP_DEFAULT_BASE_PATH = safeAccess(
+ () => process.env.CLERK_SIGN_UP_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL,
+ '/sign-up',
+);
 
 // The version that Next added support for the window.history.pushState and replaceState APIs.
 // ref: https://nextjs.org/blog/next-14-1#windowhistorypushstate-and-windowhistoryreplacestate

packages/elements/src/internals/machines/shared/shared.actors.ts

@@ -10,7 +10,7 @@ export const clerkLoader = fromCallback<EventObject, Clerk | LoadedClerk>(({ sen
  if (clerk.loaded) {
  reportLoaded();
  } else if ('addOnLoaded' in clerk) {
- // @ts-expect-error - Expects `addOnLoaded` from @clerk/clerk-react's IsomorphicClerk.
+ // @ts-expect-error - Expects `addOnLoaded` from @clerk/shared/react's IsomorphicClerk.
  clerk.addOnLoaded(reportLoaded);
  } else {
  sendBack({ type: 'ERROR', message: 'Clerk client could not be loaded' });

packages/elements/src/internals/utils/inspector/browser/index.ts

@@ -1,12 +1,16 @@
 import { isTruthy } from '@clerk/shared/underscore';
 import { createBrowserInspector } from '@statelyai/inspect';
 
+import { safeAccess } from '~/utils/safe-access';
+
 export const getInspector = () => {
  if (
  __DEV__ &&
  typeof window !== 'undefined' &&
  process.env.NODE_ENV === 'development' &&
- isTruthy(process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG_UI ?? process.env.CLERK_ELEMENTS_DEBUG_UI)
+ isTruthy(
+ safeAccess(() => process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG_UI ?? process.env.CLERK_ELEMENTS_DEBUG_UI, false),
+ )
  ) {
  const { inspect } = createBrowserInspector({
  autoStart: true,

packages/elements/src/internals/utils/inspector/console/index.ts

@@ -1,16 +1,20 @@
 import { isTruthy } from '@clerk/shared/underscore';
 
+import { safeAccess } from '~/utils/safe-access';
+
 import { createConsoleInspector } from './console';
 
 export function getInspector() {
  if (
  __DEV__ &&
  process.env.NODE_ENV === 'development' &&
- isTruthy(process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG ?? process.env.CLERK_ELEMENTS_DEBUG)
+ isTruthy(
+ safeAccess(() => process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG_UI ?? process.env.CLERK_ELEMENTS_DEBUG_UI, false),
+ )
  ) {
  return createConsoleInspector({
  enabled: true,
- debugServer: isTruthy(process.env.CLERK_ELEMENTS_DEBUG_SERVER),
+ debugServer: isTruthy(safeAccess(() => process.env.CLERK_ELEMENTS_DEBUG_SERVER, false)),
  });
  }
  return undefined;

packages/elements/src/react/common/form/input.tsx

@@ -1,5 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
 import { logger } from '@clerk/shared/logger';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import type {
  Control as RadixControl,

packages/elements/src/react/common/loading.tsx

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import type { OAuthProvider, SamlStrategy, Web3Provider } from '@clerk/types';
 import { useSelector } from '@xstate/react';

packages/elements/src/react/hooks/use-password.hook.ts

@@ -1,5 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
 import { noop } from '@clerk/shared';
+import { useClerk } from '@clerk/shared/react';
 import type { PasswordSettingsData, PasswordValidation } from '@clerk/types';
 import * as React from 'react';
 

packages/elements/src/react/hooks/use-third-party-provider.hook.ts

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import type { OAuthProvider, SamlStrategy, Web3Provider } from '@clerk/types';
 import type React from 'react';
 import { useCallback } from 'react';

packages/elements/src/react/router/index.ts

@@ -1,3 +1,2 @@
-export { useNextRouter } from './next';
 export { Route, Router, useClerkRouter } from '@clerk/shared/router';
 export { useVirtualRouter } from './virtual';

packages/elements/src/react/sign-in/root.tsx

@@ -1,4 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
+import { useClerkHostRouter } from '@clerk/shared/router';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import { useSelector } from '@xstate/react';
 import React, { useEffect } from 'react';
@@ -9,7 +10,7 @@ import { FormStoreProvider, useFormStore } from '~/internals/machines/form/form.
 import type { SignInRouterInitEvent } from '~/internals/machines/sign-in';
 import { SignInRouterMachine } from '~/internals/machines/sign-in';
 import { inspect } from '~/internals/utils/inspector';
-import { Router, useClerkRouter, useNextRouter, useVirtualRouter } from '~/react/router';
+import { Router, useClerkRouter, useVirtualRouter } from '~/react/router';
 import { SignInRouterCtx } from '~/react/sign-in/context';
 
 import { Form } from '../common/form';
@@ -39,8 +40,7 @@ function SignInFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  return;
  }
 
- // @ts-expect-error -- This is actually an IsomorphicClerk instance
- clerk.addOnLoaded(() => {
+ const cb = () => {
  const evt: SignInRouterInitEvent = {
  type: 'INIT',
  clerk,
@@ -53,7 +53,14 @@ function SignInFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  if (actor.getSnapshot().can(evt)) {
  actor.send(evt);
  }
- });
+ };
+
+ if ('addOnLoaded' in clerk) {
+ // @ts-expect-error - addOnLoaded doesn't exist on the clerk type, but it does on IsomorphicClerk, which can be hit when Elements is used standalone
+ clerk.addOnLoaded(cb);
+ } else {
+ cb();
+ }
 
  // Ensure that the latest instantiated formRef is attached to the router
  if (formRef && actor.getSnapshot().can({ type: 'RESET.STEP' })) {
@@ -123,8 +130,7 @@ export function SignInRoot({
  }),
  );
 
- // TODO: eventually we'll rely on the framework SDK to specify its host router, but for now we'll default to Next.js
- const router = (routing === ROUTING.virtual ? useVirtualRouter : useNextRouter)();
+ const router = (routing === ROUTING.virtual ? useVirtualRouter : useClerkHostRouter)();
  const isRootPath = path === router.pathname();
 
  return (

packages/elements/src/react/sign-in/step.tsx

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 
 import { ClerkElementsRuntimeError } from '~/internals/errors';

packages/elements/src/react/sign-up/root.tsx

@@ -1,4 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
+import { useClerkHostRouter } from '@clerk/shared/router';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import { useSelector } from '@xstate/react';
 import { useEffect } from 'react';
@@ -9,7 +10,7 @@ import { FormStoreProvider, useFormStore } from '~/internals/machines/form/form.
 import type { SignUpRouterInitEvent } from '~/internals/machines/sign-up';
 import { SignUpRouterMachine } from '~/internals/machines/sign-up';
 import { inspect } from '~/internals/utils/inspector';
-import { Router, useClerkRouter, useNextRouter, useVirtualRouter } from '~/react/router';
+import { Router, useClerkRouter, useVirtualRouter } from '~/react/router';
 import { SignUpRouterCtx } from '~/react/sign-up/context';
 
 import { Form } from '../common/form';
@@ -39,8 +40,7 @@ function SignUpFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  return;
  }
 
- // @ts-expect-error -- This is actually an IsomorphicClerk instance
- clerk.addOnLoaded(() => {
+ const cb = () => {
  const evt: SignUpRouterInitEvent = {
  type: 'INIT',
  clerk,
@@ -61,7 +61,14 @@ function SignUpFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  formRef,
  });
  }
- });
+ };
+
+ if ('addOnLoaded' in clerk) {
+ // @ts-expect-error - addOnLoaded doesn't exist on the clerk type, but it does on IsomorphicClerk, which can be hit when Elements is used standalone
+ clerk.addOnLoaded(cb);
+ } else {
+ cb();
+ }
  // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [clerk, exampleMode, formRef?.id, !!router, clerk.loaded]);
 
@@ -122,8 +129,7 @@ export function SignUpRoot({
  }),
  );
 
- // TODO: eventually we'll rely on the framework SDK to specify its host router, but for now we'll default to Next.js
- const router = (routing === ROUTING.virtual ? useVirtualRouter : useNextRouter)();
+ const router = (routing === ROUTING.virtual ? useVirtualRouter : useClerkHostRouter)();
  const isRootPath = path === router.pathname();
 
  return (

packages/elements/src/react/sign-up/step.tsx

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 
 import { ClerkElementsRuntimeError } from '~/internals/errors';

packages/elements/src/utils/safe-access.ts

@@ -0,0 +1,7 @@
+export function safeAccess(fn: any, fallback: any) {
+ try {
+ return fn();
+ } catch (e) {
+ return fallback;
+ }
+}

packages/nextjs/src/app-router/client/ClerkProvider.tsx

@@ -1,6 +1,8 @@
 'use client';
 import { ClerkProvider as ReactClerkProvider } from '@clerk/clerk-react';
-import { useRouter } from 'next/navigation';
+import type { ClerkHostRouter } from '@clerk/shared/router';
+import { ClerkHostRouterContext } from '@clerk/shared/router';
+import { usePathname, useRouter, useSearchParams } from 'next/navigation';
 import React, { useEffect, useTransition } from 'react';
 
 import { useSafeLayoutEffect } from '../../client-boundary/hooks/useSafeLayoutEffect';
@@ -17,12 +19,48 @@ declare global {
  __clerk_nav_await: Array<(value: void) => void>;
  __clerk_nav: (to: string) => Promise<void>;
  __clerk_internal_invalidateCachePromise: () => void | undefined;
+ next?: {
+ version: string;
+ };
  }
 }
 
+// The version that Next added support for the window.history.pushState and replaceState APIs.
+// ref: https://nextjs.org/blog/next-14-1#windowhistorypushstate-and-windowhistoryreplacestate
+export const NEXT_WINDOW_HISTORY_SUPPORT_VERSION = '14.1.0';
+
+/**
+ * Clerk router integration with Next.js's router.
+ */
+export const useNextRouter = (): ClerkHostRouter => {
+ const router = useRouter();
+ const pathname = usePathname();
+ // eslint-disable-next-line react-hooks/rules-of-hooks -- The order doesn't differ between renders as we're checking the execution environment.
+ const searchParams = typeof window === 'undefined' ? new URLSearchParams() : useSearchParams();
+
+ // The window.history APIs seem to prevent Next.js from triggering a full page re-render, allowing us to
+ // preserve internal state between steps.
+ const canUseWindowHistoryAPIs =
+ typeof window !== 'undefined' && window.next && window.next.version >= NEXT_WINDOW_HISTORY_SUPPORT_VERSION;
+
+ return {
+ mode: 'path',
+ name: 'NextRouter',
+ push: (path: string) => router.push(path),
+ replace: (path: string) =>
+ canUseWindowHistoryAPIs ? window.history.replaceState(null, '', path) : router.replace(path),
+ shallowPush(path: string) {
+ canUseWindowHistoryAPIs ? window.history.pushState(null, '', path) : router.push(path, {});
+ },
+ pathname: () => pathname,
+ searchParams: () => searchParams,
+ };
+};
+
 export const ClientClerkProvider = (props: NextClerkProviderProps) => {
  const { __unstable_invokeMiddlewareOnAuthStateChange = true, children } = props;
  const router = useRouter();
+ const clerkRouter = useNextRouter();
  const push = useAwaitablePush();
  const replace = useAwaitableReplace();
  const [isPending, startTransition] = useTransition();
@@ -57,7 +95,6 @@ export const ClientClerkProvider = (props: NextClerkProviderProps) => {
  return new Promise(res => {
  window.__clerk_internal_invalidateCachePromise = res;
  startTransition(() => {
- //@ts-expect-error next exists on window
  if (window.next?.version && typeof window.next.version === 'string' && window.next.version.startsWith('13')) {
  router.refresh();
  } else {
@@ -84,7 +121,7 @@ export const ClientClerkProvider = (props: NextClerkProviderProps) => {
  <ClerkNextOptionsProvider options={mergedProps}>
  <ReactClerkProvider {...mergedProps}>
  <ClerkJSScript router='app' />
-{children}
+<ClerkHostRouterContext.Provider value={clerkRouter}>{children}</ClerkHostRouterContext.Provider>
  </ReactClerkProvider>
  </ClerkNextOptionsProvider>
  );

.changeset/good-jeans-call.md

@@ -0,0 +1,7 @@
+---
+"@clerk/elements": minor
+"@clerk/nextjs": minor
+"@clerk/shared": minor
+---
+
+Remove `@clerk/elements` reliance on `next` and `@clerk/clerk-react` directly. The host router is now provided by `@clerk/nextjs`.

packages/elements/package.json

@@ -94,9 +94,7 @@
  "typescript": "*"
  },
  "peerDependencies": {
- "@clerk/clerk-react": "^5.0.0",
  "@clerk/shared": "^2.0.0",
- "next": "^13.5.4 || ^14.0.3 || ^15.0.0-rc",
  "react": "^18.0.0 || ^19.0.0-beta",
  "react-dom": "^18.0.0 || ^19.0.0-beta"
  },

packages/elements/src/internals/constants/index.ts

@@ -1,11 +1,18 @@
+import { safeAccess } from '~/utils/safe-access';
+
 export const SSO_CALLBACK_PATH_ROUTE = '/sso-callback';
 export const CHOOSE_SESSION_PATH_ROUTE = '/choose';
 export const MAGIC_LINK_VERIFY_PATH_ROUTE = '/verify';
 
-export const SIGN_IN_DEFAULT_BASE_PATH =
- process.env.CLERK_SIGN_IN_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_IN_URL ?? '/sign-in';
-export const SIGN_UP_DEFAULT_BASE_PATH =
- process.env.CLERK_SIGN_UP_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL ?? '/sign-up';
+// TODO: remove reliance on next-specific variables here
+export const SIGN_IN_DEFAULT_BASE_PATH = safeAccess(
+ () => process.env.CLERK_SIGN_IN_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_IN_URL,
+ '/sign-in',
+);
+export const SIGN_UP_DEFAULT_BASE_PATH = safeAccess(
+ () => process.env.CLERK_SIGN_UP_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL,
+ '/sign-up',
+);
 
 // The version that Next added support for the window.history.pushState and replaceState APIs.
 // ref: https://nextjs.org/blog/next-14-1#windowhistorypushstate-and-windowhistoryreplacestate

packages/elements/src/internals/machines/shared/shared.actors.ts

@@ -10,7 +10,7 @@ export const clerkLoader = fromCallback<EventObject, Clerk | LoadedClerk>(({ sen
  if (clerk.loaded) {
  reportLoaded();
  } else if ('addOnLoaded' in clerk) {
- // @ts-expect-error - Expects `addOnLoaded` from @clerk/clerk-react's IsomorphicClerk.
+ // @ts-expect-error - Expects `addOnLoaded` from @clerk/shared/react's IsomorphicClerk.
  clerk.addOnLoaded(reportLoaded);
  } else {
  sendBack({ type: 'ERROR', message: 'Clerk client could not be loaded' });

packages/elements/src/internals/utils/inspector/browser/index.ts

@@ -1,12 +1,16 @@
 import { isTruthy } from '@clerk/shared/underscore';
 import { createBrowserInspector } from '@statelyai/inspect';
 
+import { safeAccess } from '~/utils/safe-access';
+
 export const getInspector = () => {
  if (
  __DEV__ &&
  typeof window !== 'undefined' &&
  process.env.NODE_ENV === 'development' &&
- isTruthy(process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG_UI ?? process.env.CLERK_ELEMENTS_DEBUG_UI)
+ isTruthy(
+ safeAccess(() => process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG_UI ?? process.env.CLERK_ELEMENTS_DEBUG_UI, false),
+ )
  ) {
  const { inspect } = createBrowserInspector({
  autoStart: true,

packages/elements/src/internals/utils/inspector/console/index.ts

@@ -1,16 +1,20 @@
 import { isTruthy } from '@clerk/shared/underscore';
 
+import { safeAccess } from '~/utils/safe-access';
+
 import { createConsoleInspector } from './console';
 
 export function getInspector() {
  if (
  __DEV__ &&
  process.env.NODE_ENV === 'development' &&
- isTruthy(process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG ?? process.env.CLERK_ELEMENTS_DEBUG)
+ isTruthy(
+ safeAccess(() => process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG_UI ?? process.env.CLERK_ELEMENTS_DEBUG_UI, false),
+ )
  ) {
  return createConsoleInspector({
  enabled: true,
- debugServer: isTruthy(process.env.CLERK_ELEMENTS_DEBUG_SERVER),
+ debugServer: isTruthy(safeAccess(() => process.env.CLERK_ELEMENTS_DEBUG_SERVER, false)),
  });
  }
  return undefined;

packages/elements/src/react/common/form/input.tsx

@@ -1,5 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
 import { logger } from '@clerk/shared/logger';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import type {
  Control as RadixControl,

packages/elements/src/react/common/loading.tsx

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import type { OAuthProvider, SamlStrategy, Web3Provider } from '@clerk/types';
 import { useSelector } from '@xstate/react';

packages/elements/src/react/hooks/use-password.hook.ts

@@ -1,5 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
 import { noop } from '@clerk/shared';
+import { useClerk } from '@clerk/shared/react';
 import type { PasswordSettingsData, PasswordValidation } from '@clerk/types';
 import * as React from 'react';
 

packages/elements/src/react/hooks/use-third-party-provider.hook.ts

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import type { OAuthProvider, SamlStrategy, Web3Provider } from '@clerk/types';
 import type React from 'react';
 import { useCallback } from 'react';

packages/elements/src/react/router/index.ts

@@ -1,3 +1,2 @@
-export { useNextRouter } from './next';
 export { Route, Router, useClerkRouter } from '@clerk/shared/router';
 export { useVirtualRouter } from './virtual';

packages/elements/src/react/sign-in/root.tsx

@@ -1,4 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
+import { useClerkHostRouter } from '@clerk/shared/router';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import { useSelector } from '@xstate/react';
 import React, { useEffect } from 'react';
@@ -9,7 +10,7 @@ import { FormStoreProvider, useFormStore } from '~/internals/machines/form/form.
 import type { SignInRouterInitEvent } from '~/internals/machines/sign-in';
 import { SignInRouterMachine } from '~/internals/machines/sign-in';
 import { inspect } from '~/internals/utils/inspector';
-import { Router, useClerkRouter, useNextRouter, useVirtualRouter } from '~/react/router';
+import { Router, useClerkRouter, useVirtualRouter } from '~/react/router';
 import { SignInRouterCtx } from '~/react/sign-in/context';
 
 import { Form } from '../common/form';
@@ -39,8 +40,7 @@ function SignInFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  return;
  }
 
- // @ts-expect-error -- This is actually an IsomorphicClerk instance
- clerk.addOnLoaded(() => {
+ const cb = () => {
  const evt: SignInRouterInitEvent = {
  type: 'INIT',
  clerk,
@@ -53,7 +53,14 @@ function SignInFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  if (actor.getSnapshot().can(evt)) {
  actor.send(evt);
  }
- });
+ };
+
+ if ('addOnLoaded' in clerk) {
+ // @ts-expect-error - addOnLoaded doesn't exist on the clerk type, but it does on IsomorphicClerk, which can be hit when Elements is used standalone
+ clerk.addOnLoaded(cb);
+ } else {
+ cb();
+ }
 
  // Ensure that the latest instantiated formRef is attached to the router
  if (formRef && actor.getSnapshot().can({ type: 'RESET.STEP' })) {
@@ -123,8 +130,7 @@ export function SignInRoot({
  }),
  );
 
- // TODO: eventually we'll rely on the framework SDK to specify its host router, but for now we'll default to Next.js
- const router = (routing === ROUTING.virtual ? useVirtualRouter : useNextRouter)();
+ const router = (routing === ROUTING.virtual ? useVirtualRouter : useClerkHostRouter)();
  const isRootPath = path === router.pathname();
 
  return (

packages/elements/src/react/sign-in/step.tsx

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 
 import { ClerkElementsRuntimeError } from '~/internals/errors';

packages/elements/src/react/sign-up/root.tsx

@@ -1,4 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
+import { useClerkHostRouter } from '@clerk/shared/router';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import { useSelector } from '@xstate/react';
 import { useEffect } from 'react';
@@ -9,7 +10,7 @@ import { FormStoreProvider, useFormStore } from '~/internals/machines/form/form.
 import type { SignUpRouterInitEvent } from '~/internals/machines/sign-up';
 import { SignUpRouterMachine } from '~/internals/machines/sign-up';
 import { inspect } from '~/internals/utils/inspector';
-import { Router, useClerkRouter, useNextRouter, useVirtualRouter } from '~/react/router';
+import { Router, useClerkRouter, useVirtualRouter } from '~/react/router';
 import { SignUpRouterCtx } from '~/react/sign-up/context';
 
 import { Form } from '../common/form';
@@ -39,8 +40,7 @@ function SignUpFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  return;
  }
 
- // @ts-expect-error -- This is actually an IsomorphicClerk instance
- clerk.addOnLoaded(() => {
+ const cb = () => {
  const evt: SignUpRouterInitEvent = {
  type: 'INIT',
  clerk,
@@ -61,7 +61,14 @@ function SignUpFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  formRef,
  });
  }
- });
+ };
+
+ if ('addOnLoaded' in clerk) {
+ // @ts-expect-error - addOnLoaded doesn't exist on the clerk type, but it does on IsomorphicClerk, which can be hit when Elements is used standalone
+ clerk.addOnLoaded(cb);
+ } else {
+ cb();
+ }
  // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [clerk, exampleMode, formRef?.id, !!router, clerk.loaded]);
 
@@ -122,8 +129,7 @@ export function SignUpRoot({
  }),
  );
 
- // TODO: eventually we'll rely on the framework SDK to specify its host router, but for now we'll default to Next.js
- const router = (routing === ROUTING.virtual ? useVirtualRouter : useNextRouter)();
+ const router = (routing === ROUTING.virtual ? useVirtualRouter : useClerkHostRouter)();
  const isRootPath = path === router.pathname();
 
  return (

packages/elements/src/react/sign-up/step.tsx

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 
 import { ClerkElementsRuntimeError } from '~/internals/errors';

packages/elements/src/utils/safe-access.ts

@@ -0,0 +1,7 @@
+export function safeAccess(fn: any, fallback: any) {
+ try {
+ return fn();
+ } catch (e) {
+ return fallback;
+ }
+}

packages/nextjs/src/app-router/client/ClerkProvider.tsx

@@ -1,6 +1,8 @@
 'use client';
 import { ClerkProvider as ReactClerkProvider } from '@clerk/clerk-react';
-import { useRouter } from 'next/navigation';
+import type { ClerkHostRouter } from '@clerk/shared/router';
+import { ClerkHostRouterContext } from '@clerk/shared/router';
+import { usePathname, useRouter, useSearchParams } from 'next/navigation';
 import React, { useEffect, useTransition } from 'react';
 
 import { useSafeLayoutEffect } from '../../client-boundary/hooks/useSafeLayoutEffect';
@@ -17,12 +19,48 @@ declare global {
  __clerk_nav_await: Array<(value: void) => void>;
  __clerk_nav: (to: string) => Promise<void>;
  __clerk_internal_invalidateCachePromise: () => void | undefined;
+ next?: {
+ version: string;
+ };
  }
 }
 
+// The version that Next added support for the window.history.pushState and replaceState APIs.
+// ref: https://nextjs.org/blog/next-14-1#windowhistorypushstate-and-windowhistoryreplacestate
+export const NEXT_WINDOW_HISTORY_SUPPORT_VERSION = '14.1.0';
+
+/**
+ * Clerk router integration with Next.js's router.
+ */
+export const useNextRouter = (): ClerkHostRouter => {
+ const router = useRouter();
+ const pathname = usePathname();
+ // eslint-disable-next-line react-hooks/rules-of-hooks -- The order doesn't differ between renders as we're checking the execution environment.
+ const searchParams = typeof window === 'undefined' ? new URLSearchParams() : useSearchParams();
+
+ // The window.history APIs seem to prevent Next.js from triggering a full page re-render, allowing us to
+ // preserve internal state between steps.
+ const canUseWindowHistoryAPIs =
+ typeof window !== 'undefined' && window.next && window.next.version >= NEXT_WINDOW_HISTORY_SUPPORT_VERSION;
+
+ return {
+ mode: 'path',
+ name: 'NextRouter',
+ push: (path: string) => router.push(path),
+ replace: (path: string) =>
+ canUseWindowHistoryAPIs ? window.history.replaceState(null, '', path) : router.replace(path),
+ shallowPush(path: string) {
+ canUseWindowHistoryAPIs ? window.history.pushState(null, '', path) : router.push(path, {});
+ },
+ pathname: () => pathname,
+ searchParams: () => searchParams,
+ };
+};
+
 export const ClientClerkProvider = (props: NextClerkProviderProps) => {
  const { __unstable_invokeMiddlewareOnAuthStateChange = true, children } = props;
  const router = useRouter();
+ const clerkRouter = useNextRouter();
  const push = useAwaitablePush();
  const replace = useAwaitableReplace();
  const [isPending, startTransition] = useTransition();
@@ -57,7 +95,6 @@ export const ClientClerkProvider = (props: NextClerkProviderProps) => {
  return new Promise(res => {
  window.__clerk_internal_invalidateCachePromise = res;
  startTransition(() => {
- //@ts-expect-error next exists on window
  if (window.next?.version && typeof window.next.version === 'string' && window.next.version.startsWith('13')) {
  router.refresh();
  } else {
@@ -84,7 +121,7 @@ export const ClientClerkProvider = (props: NextClerkProviderProps) => {
  <ClerkNextOptionsProvider options={mergedProps}>
  <ReactClerkProvider {...mergedProps}>
  <ClerkJSScript router='app' />
-{children}
+<ClerkHostRouterContext.Provider value={clerkRouter}>{children}</ClerkHostRouterContext.Provider>
  </ReactClerkProvider>
  </ClerkNextOptionsProvider>
  );

.changeset/good-jeans-call.md

@@ -0,0 +1,7 @@
+---
+"@clerk/elements": minor
+"@clerk/nextjs": minor
+"@clerk/shared": minor
+---
+
+Remove `@clerk/elements` reliance on `next` and `@clerk/clerk-react` directly. The host router is now provided by `@clerk/nextjs`.

packages/elements/package.json

@@ -94,9 +94,7 @@
  "typescript": "*"
  },
  "peerDependencies": {
- "@clerk/clerk-react": "^5.0.0",
  "@clerk/shared": "^2.0.0",
- "next": "^13.5.4 || ^14.0.3 || ^15.0.0-rc",
  "react": "^18.0.0 || ^19.0.0-beta",
  "react-dom": "^18.0.0 || ^19.0.0-beta"
  },

packages/elements/src/internals/constants/index.ts

@@ -1,11 +1,18 @@
+import { safeAccess } from '~/utils/safe-access';
+
 export const SSO_CALLBACK_PATH_ROUTE = '/sso-callback';
 export const CHOOSE_SESSION_PATH_ROUTE = '/choose';
 export const MAGIC_LINK_VERIFY_PATH_ROUTE = '/verify';
 
-export const SIGN_IN_DEFAULT_BASE_PATH =
- process.env.CLERK_SIGN_IN_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_IN_URL ?? '/sign-in';
-export const SIGN_UP_DEFAULT_BASE_PATH =
- process.env.CLERK_SIGN_UP_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL ?? '/sign-up';
+// TODO: remove reliance on next-specific variables here
+export const SIGN_IN_DEFAULT_BASE_PATH = safeAccess(
+ () => process.env.CLERK_SIGN_IN_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_IN_URL,
+ '/sign-in',
+);
+export const SIGN_UP_DEFAULT_BASE_PATH = safeAccess(
+ () => process.env.CLERK_SIGN_UP_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL,
+ '/sign-up',
+);
 
 // The version that Next added support for the window.history.pushState and replaceState APIs.
 // ref: https://nextjs.org/blog/next-14-1#windowhistorypushstate-and-windowhistoryreplacestate

packages/elements/src/internals/machines/shared/shared.actors.ts

@@ -10,7 +10,7 @@ export const clerkLoader = fromCallback<EventObject, Clerk | LoadedClerk>(({ sen
  if (clerk.loaded) {
  reportLoaded();
  } else if ('addOnLoaded' in clerk) {
- // @ts-expect-error - Expects `addOnLoaded` from @clerk/clerk-react's IsomorphicClerk.
+ // @ts-expect-error - Expects `addOnLoaded` from @clerk/shared/react's IsomorphicClerk.
  clerk.addOnLoaded(reportLoaded);
  } else {
  sendBack({ type: 'ERROR', message: 'Clerk client could not be loaded' });

packages/elements/src/internals/utils/inspector/browser/index.ts

@@ -1,12 +1,16 @@
 import { isTruthy } from '@clerk/shared/underscore';
 import { createBrowserInspector } from '@statelyai/inspect';
 
+import { safeAccess } from '~/utils/safe-access';
+
 export const getInspector = () => {
  if (
  __DEV__ &&
  typeof window !== 'undefined' &&
  process.env.NODE_ENV === 'development' &&
- isTruthy(process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG_UI ?? process.env.CLERK_ELEMENTS_DEBUG_UI)
+ isTruthy(
+ safeAccess(() => process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG_UI ?? process.env.CLERK_ELEMENTS_DEBUG_UI, false),
+ )
  ) {
  const { inspect } = createBrowserInspector({
  autoStart: true,

packages/elements/src/internals/utils/inspector/console/index.ts

@@ -1,16 +1,20 @@
 import { isTruthy } from '@clerk/shared/underscore';
 
+import { safeAccess } from '~/utils/safe-access';
+
 import { createConsoleInspector } from './console';
 
 export function getInspector() {
  if (
  __DEV__ &&
  process.env.NODE_ENV === 'development' &&
- isTruthy(process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG ?? process.env.CLERK_ELEMENTS_DEBUG)
+ isTruthy(
+ safeAccess(() => process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG_UI ?? process.env.CLERK_ELEMENTS_DEBUG_UI, false),
+ )
  ) {
  return createConsoleInspector({
  enabled: true,
- debugServer: isTruthy(process.env.CLERK_ELEMENTS_DEBUG_SERVER),
+ debugServer: isTruthy(safeAccess(() => process.env.CLERK_ELEMENTS_DEBUG_SERVER, false)),
  });
  }
  return undefined;

packages/elements/src/react/common/form/input.tsx

@@ -1,5 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
 import { logger } from '@clerk/shared/logger';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import type {
  Control as RadixControl,

packages/elements/src/react/common/loading.tsx

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import type { OAuthProvider, SamlStrategy, Web3Provider } from '@clerk/types';
 import { useSelector } from '@xstate/react';

packages/elements/src/react/hooks/use-password.hook.ts

@@ -1,5 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
 import { noop } from '@clerk/shared';
+import { useClerk } from '@clerk/shared/react';
 import type { PasswordSettingsData, PasswordValidation } from '@clerk/types';
 import * as React from 'react';
 

packages/elements/src/react/hooks/use-third-party-provider.hook.ts

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import type { OAuthProvider, SamlStrategy, Web3Provider } from '@clerk/types';
 import type React from 'react';
 import { useCallback } from 'react';

packages/elements/src/react/router/index.ts

@@ -1,3 +1,2 @@
-export { useNextRouter } from './next';
 export { Route, Router, useClerkRouter } from '@clerk/shared/router';
 export { useVirtualRouter } from './virtual';

packages/elements/src/react/sign-in/root.tsx

@@ -1,4 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
+import { useClerkHostRouter } from '@clerk/shared/router';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import { useSelector } from '@xstate/react';
 import React, { useEffect } from 'react';
@@ -9,7 +10,7 @@ import { FormStoreProvider, useFormStore } from '~/internals/machines/form/form.
 import type { SignInRouterInitEvent } from '~/internals/machines/sign-in';
 import { SignInRouterMachine } from '~/internals/machines/sign-in';
 import { inspect } from '~/internals/utils/inspector';
-import { Router, useClerkRouter, useNextRouter, useVirtualRouter } from '~/react/router';
+import { Router, useClerkRouter, useVirtualRouter } from '~/react/router';
 import { SignInRouterCtx } from '~/react/sign-in/context';
 
 import { Form } from '../common/form';
@@ -39,8 +40,7 @@ function SignInFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  return;
  }
 
- // @ts-expect-error -- This is actually an IsomorphicClerk instance
- clerk.addOnLoaded(() => {
+ const cb = () => {
  const evt: SignInRouterInitEvent = {
  type: 'INIT',
  clerk,
@@ -53,7 +53,14 @@ function SignInFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  if (actor.getSnapshot().can(evt)) {
  actor.send(evt);
  }
- });
+ };
+
+ if ('addOnLoaded' in clerk) {
+ // @ts-expect-error - addOnLoaded doesn't exist on the clerk type, but it does on IsomorphicClerk, which can be hit when Elements is used standalone
+ clerk.addOnLoaded(cb);
+ } else {
+ cb();
+ }
 
  // Ensure that the latest instantiated formRef is attached to the router
  if (formRef && actor.getSnapshot().can({ type: 'RESET.STEP' })) {
@@ -123,8 +130,7 @@ export function SignInRoot({
  }),
  );
 
- // TODO: eventually we'll rely on the framework SDK to specify its host router, but for now we'll default to Next.js
- const router = (routing === ROUTING.virtual ? useVirtualRouter : useNextRouter)();
+ const router = (routing === ROUTING.virtual ? useVirtualRouter : useClerkHostRouter)();
  const isRootPath = path === router.pathname();
 
  return (

packages/elements/src/react/sign-in/step.tsx

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 
 import { ClerkElementsRuntimeError } from '~/internals/errors';

packages/elements/src/react/sign-up/root.tsx

@@ -1,4 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
+import { useClerkHostRouter } from '@clerk/shared/router';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import { useSelector } from '@xstate/react';
 import { useEffect } from 'react';
@@ -9,7 +10,7 @@ import { FormStoreProvider, useFormStore } from '~/internals/machines/form/form.
 import type { SignUpRouterInitEvent } from '~/internals/machines/sign-up';
 import { SignUpRouterMachine } from '~/internals/machines/sign-up';
 import { inspect } from '~/internals/utils/inspector';
-import { Router, useClerkRouter, useNextRouter, useVirtualRouter } from '~/react/router';
+import { Router, useClerkRouter, useVirtualRouter } from '~/react/router';
 import { SignUpRouterCtx } from '~/react/sign-up/context';
 
 import { Form } from '../common/form';
@@ -39,8 +40,7 @@ function SignUpFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  return;
  }
 
- // @ts-expect-error -- This is actually an IsomorphicClerk instance
- clerk.addOnLoaded(() => {
+ const cb = () => {
  const evt: SignUpRouterInitEvent = {
  type: 'INIT',
  clerk,
@@ -61,7 +61,14 @@ function SignUpFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  formRef,
  });
  }
- });
+ };
+
+ if ('addOnLoaded' in clerk) {
+ // @ts-expect-error - addOnLoaded doesn't exist on the clerk type, but it does on IsomorphicClerk, which can be hit when Elements is used standalone
+ clerk.addOnLoaded(cb);
+ } else {
+ cb();
+ }
  // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [clerk, exampleMode, formRef?.id, !!router, clerk.loaded]);
 
@@ -122,8 +129,7 @@ export function SignUpRoot({
  }),
  );
 
- // TODO: eventually we'll rely on the framework SDK to specify its host router, but for now we'll default to Next.js
- const router = (routing === ROUTING.virtual ? useVirtualRouter : useNextRouter)();
+ const router = (routing === ROUTING.virtual ? useVirtualRouter : useClerkHostRouter)();
  const isRootPath = path === router.pathname();
 
  return (

packages/elements/src/react/sign-up/step.tsx

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 
 import { ClerkElementsRuntimeError } from '~/internals/errors';

packages/elements/src/utils/safe-access.ts

@@ -0,0 +1,7 @@
+export function safeAccess(fn: any, fallback: any) {
+ try {
+ return fn();
+ } catch (e) {
+ return fallback;
+ }
+}

packages/nextjs/src/app-router/client/ClerkProvider.tsx

@@ -1,6 +1,8 @@
 'use client';
 import { ClerkProvider as ReactClerkProvider } from '@clerk/clerk-react';
-import { useRouter } from 'next/navigation';
+import type { ClerkHostRouter } from '@clerk/shared/router';
+import { ClerkHostRouterContext } from '@clerk/shared/router';
+import { usePathname, useRouter, useSearchParams } from 'next/navigation';
 import React, { useEffect, useTransition } from 'react';
 
 import { useSafeLayoutEffect } from '../../client-boundary/hooks/useSafeLayoutEffect';
@@ -17,12 +19,48 @@ declare global {
  __clerk_nav_await: Array<(value: void) => void>;
  __clerk_nav: (to: string) => Promise<void>;
  __clerk_internal_invalidateCachePromise: () => void | undefined;
+ next?: {
+ version: string;
+ };
  }
 }
 
+// The version that Next added support for the window.history.pushState and replaceState APIs.
+// ref: https://nextjs.org/blog/next-14-1#windowhistorypushstate-and-windowhistoryreplacestate
+export const NEXT_WINDOW_HISTORY_SUPPORT_VERSION = '14.1.0';
+
+/**
+ * Clerk router integration with Next.js's router.
+ */
+export const useNextRouter = (): ClerkHostRouter => {
+ const router = useRouter();
+ const pathname = usePathname();
+ // eslint-disable-next-line react-hooks/rules-of-hooks -- The order doesn't differ between renders as we're checking the execution environment.
+ const searchParams = typeof window === 'undefined' ? new URLSearchParams() : useSearchParams();
+
+ // The window.history APIs seem to prevent Next.js from triggering a full page re-render, allowing us to
+ // preserve internal state between steps.
+ const canUseWindowHistoryAPIs =
+ typeof window !== 'undefined' && window.next && window.next.version >= NEXT_WINDOW_HISTORY_SUPPORT_VERSION;
+
+ return {
+ mode: 'path',
+ name: 'NextRouter',
+ push: (path: string) => router.push(path),
+ replace: (path: string) =>
+ canUseWindowHistoryAPIs ? window.history.replaceState(null, '', path) : router.replace(path),
+ shallowPush(path: string) {
+ canUseWindowHistoryAPIs ? window.history.pushState(null, '', path) : router.push(path, {});
+ },
+ pathname: () => pathname,
+ searchParams: () => searchParams,
+ };
+};
+
 export const ClientClerkProvider = (props: NextClerkProviderProps) => {
  const { __unstable_invokeMiddlewareOnAuthStateChange = true, children } = props;
  const router = useRouter();
+ const clerkRouter = useNextRouter();
  const push = useAwaitablePush();
  const replace = useAwaitableReplace();
  const [isPending, startTransition] = useTransition();
@@ -57,7 +95,6 @@ export const ClientClerkProvider = (props: NextClerkProviderProps) => {
  return new Promise(res => {
  window.__clerk_internal_invalidateCachePromise = res;
  startTransition(() => {
- //@ts-expect-error next exists on window
  if (window.next?.version && typeof window.next.version === 'string' && window.next.version.startsWith('13')) {
  router.refresh();
  } else {
@@ -84,7 +121,7 @@ export const ClientClerkProvider = (props: NextClerkProviderProps) => {
  <ClerkNextOptionsProvider options={mergedProps}>
  <ReactClerkProvider {...mergedProps}>
  <ClerkJSScript router='app' />
-{children}
+<ClerkHostRouterContext.Provider value={clerkRouter}>{children}</ClerkHostRouterContext.Provider>
  </ReactClerkProvider>
  </ClerkNextOptionsProvider>
  );

.changeset/good-jeans-call.md

@@ -0,0 +1,7 @@
+---
+"@clerk/elements": minor
+"@clerk/nextjs": minor
+"@clerk/shared": minor
+---
+
+Remove `@clerk/elements` reliance on `next` and `@clerk/clerk-react` directly. The host router is now provided by `@clerk/nextjs`.

packages/elements/package.json

@@ -94,9 +94,7 @@
  "typescript": "*"
  },
  "peerDependencies": {
- "@clerk/clerk-react": "^5.0.0",
  "@clerk/shared": "^2.0.0",
- "next": "^13.5.4 || ^14.0.3 || ^15.0.0-rc",
  "react": "^18.0.0 || ^19.0.0-beta",
  "react-dom": "^18.0.0 || ^19.0.0-beta"
  },

packages/elements/src/internals/constants/index.ts

@@ -1,11 +1,18 @@
+import { safeAccess } from '~/utils/safe-access';
+
 export const SSO_CALLBACK_PATH_ROUTE = '/sso-callback';
 export const CHOOSE_SESSION_PATH_ROUTE = '/choose';
 export const MAGIC_LINK_VERIFY_PATH_ROUTE = '/verify';
 
-export const SIGN_IN_DEFAULT_BASE_PATH =
- process.env.CLERK_SIGN_IN_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_IN_URL ?? '/sign-in';
-export const SIGN_UP_DEFAULT_BASE_PATH =
- process.env.CLERK_SIGN_UP_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL ?? '/sign-up';
+// TODO: remove reliance on next-specific variables here
+export const SIGN_IN_DEFAULT_BASE_PATH = safeAccess(
+ () => process.env.CLERK_SIGN_IN_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_IN_URL,
+ '/sign-in',
+);
+export const SIGN_UP_DEFAULT_BASE_PATH = safeAccess(
+ () => process.env.CLERK_SIGN_UP_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL,
+ '/sign-up',
+);
 
 // The version that Next added support for the window.history.pushState and replaceState APIs.
 // ref: https://nextjs.org/blog/next-14-1#windowhistorypushstate-and-windowhistoryreplacestate

packages/elements/src/internals/machines/shared/shared.actors.ts

@@ -10,7 +10,7 @@ export const clerkLoader = fromCallback<EventObject, Clerk | LoadedClerk>(({ sen
  if (clerk.loaded) {
  reportLoaded();
  } else if ('addOnLoaded' in clerk) {
- // @ts-expect-error - Expects `addOnLoaded` from @clerk/clerk-react's IsomorphicClerk.
+ // @ts-expect-error - Expects `addOnLoaded` from @clerk/shared/react's IsomorphicClerk.
  clerk.addOnLoaded(reportLoaded);
  } else {
  sendBack({ type: 'ERROR', message: 'Clerk client could not be loaded' });

packages/elements/src/internals/utils/inspector/browser/index.ts

@@ -1,12 +1,16 @@
 import { isTruthy } from '@clerk/shared/underscore';
 import { createBrowserInspector } from '@statelyai/inspect';
 
+import { safeAccess } from '~/utils/safe-access';
+
 export const getInspector = () => {
  if (
  __DEV__ &&
  typeof window !== 'undefined' &&
  process.env.NODE_ENV === 'development' &&
- isTruthy(process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG_UI ?? process.env.CLERK_ELEMENTS_DEBUG_UI)
+ isTruthy(
+ safeAccess(() => process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG_UI ?? process.env.CLERK_ELEMENTS_DEBUG_UI, false),
+ )
  ) {
  const { inspect } = createBrowserInspector({
  autoStart: true,

packages/elements/src/internals/utils/inspector/console/index.ts

@@ -1,16 +1,20 @@
 import { isTruthy } from '@clerk/shared/underscore';
 
+import { safeAccess } from '~/utils/safe-access';
+
 import { createConsoleInspector } from './console';
 
 export function getInspector() {
  if (
  __DEV__ &&
  process.env.NODE_ENV === 'development' &&
- isTruthy(process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG ?? process.env.CLERK_ELEMENTS_DEBUG)
+ isTruthy(
+ safeAccess(() => process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG_UI ?? process.env.CLERK_ELEMENTS_DEBUG_UI, false),
+ )
  ) {
  return createConsoleInspector({
  enabled: true,
- debugServer: isTruthy(process.env.CLERK_ELEMENTS_DEBUG_SERVER),
+ debugServer: isTruthy(safeAccess(() => process.env.CLERK_ELEMENTS_DEBUG_SERVER, false)),
  });
  }
  return undefined;

packages/elements/src/react/common/form/input.tsx

@@ -1,5 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
 import { logger } from '@clerk/shared/logger';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import type {
  Control as RadixControl,

packages/elements/src/react/common/loading.tsx

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import type { OAuthProvider, SamlStrategy, Web3Provider } from '@clerk/types';
 import { useSelector } from '@xstate/react';

packages/elements/src/react/hooks/use-password.hook.ts

@@ -1,5 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
 import { noop } from '@clerk/shared';
+import { useClerk } from '@clerk/shared/react';
 import type { PasswordSettingsData, PasswordValidation } from '@clerk/types';
 import * as React from 'react';
 

packages/elements/src/react/hooks/use-third-party-provider.hook.ts

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import type { OAuthProvider, SamlStrategy, Web3Provider } from '@clerk/types';
 import type React from 'react';
 import { useCallback } from 'react';

packages/elements/src/react/router/index.ts

@@ -1,3 +1,2 @@
-export { useNextRouter } from './next';
 export { Route, Router, useClerkRouter } from '@clerk/shared/router';
 export { useVirtualRouter } from './virtual';

packages/elements/src/react/sign-in/root.tsx

@@ -1,4 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
+import { useClerkHostRouter } from '@clerk/shared/router';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import { useSelector } from '@xstate/react';
 import React, { useEffect } from 'react';
@@ -9,7 +10,7 @@ import { FormStoreProvider, useFormStore } from '~/internals/machines/form/form.
 import type { SignInRouterInitEvent } from '~/internals/machines/sign-in';
 import { SignInRouterMachine } from '~/internals/machines/sign-in';
 import { inspect } from '~/internals/utils/inspector';
-import { Router, useClerkRouter, useNextRouter, useVirtualRouter } from '~/react/router';
+import { Router, useClerkRouter, useVirtualRouter } from '~/react/router';
 import { SignInRouterCtx } from '~/react/sign-in/context';
 
 import { Form } from '../common/form';
@@ -39,8 +40,7 @@ function SignInFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  return;
  }
 
- // @ts-expect-error -- This is actually an IsomorphicClerk instance
- clerk.addOnLoaded(() => {
+ const cb = () => {
  const evt: SignInRouterInitEvent = {
  type: 'INIT',
  clerk,
@@ -53,7 +53,14 @@ function SignInFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  if (actor.getSnapshot().can(evt)) {
  actor.send(evt);
  }
- });
+ };
+
+ if ('addOnLoaded' in clerk) {
+ // @ts-expect-error - addOnLoaded doesn't exist on the clerk type, but it does on IsomorphicClerk, which can be hit when Elements is used standalone
+ clerk.addOnLoaded(cb);
+ } else {
+ cb();
+ }
 
  // Ensure that the latest instantiated formRef is attached to the router
  if (formRef && actor.getSnapshot().can({ type: 'RESET.STEP' })) {
@@ -123,8 +130,7 @@ export function SignInRoot({
  }),
  );
 
- // TODO: eventually we'll rely on the framework SDK to specify its host router, but for now we'll default to Next.js
- const router = (routing === ROUTING.virtual ? useVirtualRouter : useNextRouter)();
+ const router = (routing === ROUTING.virtual ? useVirtualRouter : useClerkHostRouter)();
  const isRootPath = path === router.pathname();
 
  return (

packages/elements/src/react/sign-in/step.tsx

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 
 import { ClerkElementsRuntimeError } from '~/internals/errors';

packages/elements/src/react/sign-up/root.tsx

@@ -1,4 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
+import { useClerkHostRouter } from '@clerk/shared/router';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import { useSelector } from '@xstate/react';
 import { useEffect } from 'react';
@@ -9,7 +10,7 @@ import { FormStoreProvider, useFormStore } from '~/internals/machines/form/form.
 import type { SignUpRouterInitEvent } from '~/internals/machines/sign-up';
 import { SignUpRouterMachine } from '~/internals/machines/sign-up';
 import { inspect } from '~/internals/utils/inspector';
-import { Router, useClerkRouter, useNextRouter, useVirtualRouter } from '~/react/router';
+import { Router, useClerkRouter, useVirtualRouter } from '~/react/router';
 import { SignUpRouterCtx } from '~/react/sign-up/context';
 
 import { Form } from '../common/form';
@@ -39,8 +40,7 @@ function SignUpFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  return;
  }
 
- // @ts-expect-error -- This is actually an IsomorphicClerk instance
- clerk.addOnLoaded(() => {
+ const cb = () => {
  const evt: SignUpRouterInitEvent = {
  type: 'INIT',
  clerk,
@@ -61,7 +61,14 @@ function SignUpFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  formRef,
  });
  }
- });
+ };
+
+ if ('addOnLoaded' in clerk) {
+ // @ts-expect-error - addOnLoaded doesn't exist on the clerk type, but it does on IsomorphicClerk, which can be hit when Elements is used standalone
+ clerk.addOnLoaded(cb);
+ } else {
+ cb();
+ }
  // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [clerk, exampleMode, formRef?.id, !!router, clerk.loaded]);
 
@@ -122,8 +129,7 @@ export function SignUpRoot({
  }),
  );
 
- // TODO: eventually we'll rely on the framework SDK to specify its host router, but for now we'll default to Next.js
- const router = (routing === ROUTING.virtual ? useVirtualRouter : useNextRouter)();
+ const router = (routing === ROUTING.virtual ? useVirtualRouter : useClerkHostRouter)();
  const isRootPath = path === router.pathname();
 
  return (

packages/elements/src/react/sign-up/step.tsx

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 
 import { ClerkElementsRuntimeError } from '~/internals/errors';

packages/elements/src/utils/safe-access.ts

@@ -0,0 +1,7 @@
+export function safeAccess(fn: any, fallback: any) {
+ try {
+ return fn();
+ } catch (e) {
+ return fallback;
+ }
+}

packages/nextjs/src/app-router/client/ClerkProvider.tsx

@@ -1,6 +1,8 @@
 'use client';
 import { ClerkProvider as ReactClerkProvider } from '@clerk/clerk-react';
-import { useRouter } from 'next/navigation';
+import type { ClerkHostRouter } from '@clerk/shared/router';
+import { ClerkHostRouterContext } from '@clerk/shared/router';
+import { usePathname, useRouter, useSearchParams } from 'next/navigation';
 import React, { useEffect, useTransition } from 'react';
 
 import { useSafeLayoutEffect } from '../../client-boundary/hooks/useSafeLayoutEffect';
@@ -17,12 +19,48 @@ declare global {
  __clerk_nav_await: Array<(value: void) => void>;
  __clerk_nav: (to: string) => Promise<void>;
  __clerk_internal_invalidateCachePromise: () => void | undefined;
+ next?: {
+ version: string;
+ };
  }
 }
 
+// The version that Next added support for the window.history.pushState and replaceState APIs.
+// ref: https://nextjs.org/blog/next-14-1#windowhistorypushstate-and-windowhistoryreplacestate
+export const NEXT_WINDOW_HISTORY_SUPPORT_VERSION = '14.1.0';
+
+/**
+ * Clerk router integration with Next.js's router.
+ */
+export const useNextRouter = (): ClerkHostRouter => {
+ const router = useRouter();
+ const pathname = usePathname();
+ // eslint-disable-next-line react-hooks/rules-of-hooks -- The order doesn't differ between renders as we're checking the execution environment.
+ const searchParams = typeof window === 'undefined' ? new URLSearchParams() : useSearchParams();
+
+ // The window.history APIs seem to prevent Next.js from triggering a full page re-render, allowing us to
+ // preserve internal state between steps.
+ const canUseWindowHistoryAPIs =
+ typeof window !== 'undefined' && window.next && window.next.version >= NEXT_WINDOW_HISTORY_SUPPORT_VERSION;
+
+ return {
+ mode: 'path',
+ name: 'NextRouter',
+ push: (path: string) => router.push(path),
+ replace: (path: string) =>
+ canUseWindowHistoryAPIs ? window.history.replaceState(null, '', path) : router.replace(path),
+ shallowPush(path: string) {
+ canUseWindowHistoryAPIs ? window.history.pushState(null, '', path) : router.push(path, {});
+ },
+ pathname: () => pathname,
+ searchParams: () => searchParams,
+ };
+};
+
 export const ClientClerkProvider = (props: NextClerkProviderProps) => {
  const { __unstable_invokeMiddlewareOnAuthStateChange = true, children } = props;
  const router = useRouter();
+ const clerkRouter = useNextRouter();
  const push = useAwaitablePush();
  const replace = useAwaitableReplace();
  const [isPending, startTransition] = useTransition();
@@ -57,7 +95,6 @@ export const ClientClerkProvider = (props: NextClerkProviderProps) => {
  return new Promise(res => {
  window.__clerk_internal_invalidateCachePromise = res;
  startTransition(() => {
- //@ts-expect-error next exists on window
  if (window.next?.version && typeof window.next.version === 'string' && window.next.version.startsWith('13')) {
  router.refresh();
  } else {
@@ -84,7 +121,7 @@ export const ClientClerkProvider = (props: NextClerkProviderProps) => {
  <ClerkNextOptionsProvider options={mergedProps}>
  <ReactClerkProvider {...mergedProps}>
  <ClerkJSScript router='app' />
-{children}
+<ClerkHostRouterContext.Provider value={clerkRouter}>{children}</ClerkHostRouterContext.Provider>
  </ReactClerkProvider>
  </ClerkNextOptionsProvider>
  );

.changeset/good-jeans-call.md

@@ -0,0 +1,7 @@
+---
+"@clerk/elements": minor
+"@clerk/nextjs": minor
+"@clerk/shared": minor
+---
+
+Remove `@clerk/elements` reliance on `next` and `@clerk/clerk-react` directly. The host router is now provided by `@clerk/nextjs`.

packages/elements/package.json

@@ -94,9 +94,7 @@
  "typescript": "*"
  },
  "peerDependencies": {
- "@clerk/clerk-react": "^5.0.0",
  "@clerk/shared": "^2.0.0",
- "next": "^13.5.4 || ^14.0.3 || ^15.0.0-rc",
  "react": "^18.0.0 || ^19.0.0-beta",
  "react-dom": "^18.0.0 || ^19.0.0-beta"
  },

packages/elements/src/internals/constants/index.ts

@@ -1,11 +1,18 @@
+import { safeAccess } from '~/utils/safe-access';
+
 export const SSO_CALLBACK_PATH_ROUTE = '/sso-callback';
 export const CHOOSE_SESSION_PATH_ROUTE = '/choose';
 export const MAGIC_LINK_VERIFY_PATH_ROUTE = '/verify';
 
-export const SIGN_IN_DEFAULT_BASE_PATH =
- process.env.CLERK_SIGN_IN_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_IN_URL ?? '/sign-in';
-export const SIGN_UP_DEFAULT_BASE_PATH =
- process.env.CLERK_SIGN_UP_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL ?? '/sign-up';
+// TODO: remove reliance on next-specific variables here
+export const SIGN_IN_DEFAULT_BASE_PATH = safeAccess(
+ () => process.env.CLERK_SIGN_IN_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_IN_URL,
+ '/sign-in',
+);
+export const SIGN_UP_DEFAULT_BASE_PATH = safeAccess(
+ () => process.env.CLERK_SIGN_UP_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL,
+ '/sign-up',
+);
 
 // The version that Next added support for the window.history.pushState and replaceState APIs.
 // ref: https://nextjs.org/blog/next-14-1#windowhistorypushstate-and-windowhistoryreplacestate

packages/elements/src/internals/machines/shared/shared.actors.ts

@@ -10,7 +10,7 @@ export const clerkLoader = fromCallback<EventObject, Clerk | LoadedClerk>(({ sen
  if (clerk.loaded) {
  reportLoaded();
  } else if ('addOnLoaded' in clerk) {
- // @ts-expect-error - Expects `addOnLoaded` from @clerk/clerk-react's IsomorphicClerk.
+ // @ts-expect-error - Expects `addOnLoaded` from @clerk/shared/react's IsomorphicClerk.
  clerk.addOnLoaded(reportLoaded);
  } else {
  sendBack({ type: 'ERROR', message: 'Clerk client could not be loaded' });

packages/elements/src/internals/utils/inspector/browser/index.ts

@@ -1,12 +1,16 @@
 import { isTruthy } from '@clerk/shared/underscore';
 import { createBrowserInspector } from '@statelyai/inspect';
 
+import { safeAccess } from '~/utils/safe-access';
+
 export const getInspector = () => {
  if (
  __DEV__ &&
  typeof window !== 'undefined' &&
  process.env.NODE_ENV === 'development' &&
- isTruthy(process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG_UI ?? process.env.CLERK_ELEMENTS_DEBUG_UI)
+ isTruthy(
+ safeAccess(() => process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG_UI ?? process.env.CLERK_ELEMENTS_DEBUG_UI, false),
+ )
  ) {
  const { inspect } = createBrowserInspector({
  autoStart: true,

packages/elements/src/internals/utils/inspector/console/index.ts

@@ -1,16 +1,20 @@
 import { isTruthy } from '@clerk/shared/underscore';
 
+import { safeAccess } from '~/utils/safe-access';
+
 import { createConsoleInspector } from './console';
 
 export function getInspector() {
  if (
  __DEV__ &&
  process.env.NODE_ENV === 'development' &&
- isTruthy(process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG ?? process.env.CLERK_ELEMENTS_DEBUG)
+ isTruthy(
+ safeAccess(() => process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG_UI ?? process.env.CLERK_ELEMENTS_DEBUG_UI, false),
+ )
  ) {
  return createConsoleInspector({
  enabled: true,
- debugServer: isTruthy(process.env.CLERK_ELEMENTS_DEBUG_SERVER),
+ debugServer: isTruthy(safeAccess(() => process.env.CLERK_ELEMENTS_DEBUG_SERVER, false)),
  });
  }
  return undefined;

packages/elements/src/react/common/form/input.tsx

@@ -1,5 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
 import { logger } from '@clerk/shared/logger';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import type {
  Control as RadixControl,

packages/elements/src/react/common/loading.tsx

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import type { OAuthProvider, SamlStrategy, Web3Provider } from '@clerk/types';
 import { useSelector } from '@xstate/react';

packages/elements/src/react/hooks/use-password.hook.ts

@@ -1,5 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
 import { noop } from '@clerk/shared';
+import { useClerk } from '@clerk/shared/react';
 import type { PasswordSettingsData, PasswordValidation } from '@clerk/types';
 import * as React from 'react';
 

packages/elements/src/react/hooks/use-third-party-provider.hook.ts

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import type { OAuthProvider, SamlStrategy, Web3Provider } from '@clerk/types';
 import type React from 'react';
 import { useCallback } from 'react';

packages/elements/src/react/router/index.ts

@@ -1,3 +1,2 @@
-export { useNextRouter } from './next';
 export { Route, Router, useClerkRouter } from '@clerk/shared/router';
 export { useVirtualRouter } from './virtual';

packages/elements/src/react/sign-in/root.tsx

@@ -1,4 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
+import { useClerkHostRouter } from '@clerk/shared/router';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import { useSelector } from '@xstate/react';
 import React, { useEffect } from 'react';
@@ -9,7 +10,7 @@ import { FormStoreProvider, useFormStore } from '~/internals/machines/form/form.
 import type { SignInRouterInitEvent } from '~/internals/machines/sign-in';
 import { SignInRouterMachine } from '~/internals/machines/sign-in';
 import { inspect } from '~/internals/utils/inspector';
-import { Router, useClerkRouter, useNextRouter, useVirtualRouter } from '~/react/router';
+import { Router, useClerkRouter, useVirtualRouter } from '~/react/router';
 import { SignInRouterCtx } from '~/react/sign-in/context';
 
 import { Form } from '../common/form';
@@ -39,8 +40,7 @@ function SignInFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  return;
  }
 
- // @ts-expect-error -- This is actually an IsomorphicClerk instance
- clerk.addOnLoaded(() => {
+ const cb = () => {
  const evt: SignInRouterInitEvent = {
  type: 'INIT',
  clerk,
@@ -53,7 +53,14 @@ function SignInFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  if (actor.getSnapshot().can(evt)) {
  actor.send(evt);
  }
- });
+ };
+
+ if ('addOnLoaded' in clerk) {
+ // @ts-expect-error - addOnLoaded doesn't exist on the clerk type, but it does on IsomorphicClerk, which can be hit when Elements is used standalone
+ clerk.addOnLoaded(cb);
+ } else {
+ cb();
+ }
 
  // Ensure that the latest instantiated formRef is attached to the router
  if (formRef && actor.getSnapshot().can({ type: 'RESET.STEP' })) {
@@ -123,8 +130,7 @@ export function SignInRoot({
  }),
  );
 
- // TODO: eventually we'll rely on the framework SDK to specify its host router, but for now we'll default to Next.js
- const router = (routing === ROUTING.virtual ? useVirtualRouter : useNextRouter)();
+ const router = (routing === ROUTING.virtual ? useVirtualRouter : useClerkHostRouter)();
  const isRootPath = path === router.pathname();
 
  return (

packages/elements/src/react/sign-in/step.tsx

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 
 import { ClerkElementsRuntimeError } from '~/internals/errors';

packages/elements/src/react/sign-up/root.tsx

@@ -1,4 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
+import { useClerkHostRouter } from '@clerk/shared/router';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import { useSelector } from '@xstate/react';
 import { useEffect } from 'react';
@@ -9,7 +10,7 @@ import { FormStoreProvider, useFormStore } from '~/internals/machines/form/form.
 import type { SignUpRouterInitEvent } from '~/internals/machines/sign-up';
 import { SignUpRouterMachine } from '~/internals/machines/sign-up';
 import { inspect } from '~/internals/utils/inspector';
-import { Router, useClerkRouter, useNextRouter, useVirtualRouter } from '~/react/router';
+import { Router, useClerkRouter, useVirtualRouter } from '~/react/router';
 import { SignUpRouterCtx } from '~/react/sign-up/context';
 
 import { Form } from '../common/form';
@@ -39,8 +40,7 @@ function SignUpFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  return;
  }
 
- // @ts-expect-error -- This is actually an IsomorphicClerk instance
- clerk.addOnLoaded(() => {
+ const cb = () => {
  const evt: SignUpRouterInitEvent = {
  type: 'INIT',
  clerk,
@@ -61,7 +61,14 @@ function SignUpFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  formRef,
  });
  }
- });
+ };
+
+ if ('addOnLoaded' in clerk) {
+ // @ts-expect-error - addOnLoaded doesn't exist on the clerk type, but it does on IsomorphicClerk, which can be hit when Elements is used standalone
+ clerk.addOnLoaded(cb);
+ } else {
+ cb();
+ }
  // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [clerk, exampleMode, formRef?.id, !!router, clerk.loaded]);
 
@@ -122,8 +129,7 @@ export function SignUpRoot({
  }),
  );
 
- // TODO: eventually we'll rely on the framework SDK to specify its host router, but for now we'll default to Next.js
- const router = (routing === ROUTING.virtual ? useVirtualRouter : useNextRouter)();
+ const router = (routing === ROUTING.virtual ? useVirtualRouter : useClerkHostRouter)();
  const isRootPath = path === router.pathname();
 
  return (

packages/elements/src/react/sign-up/step.tsx

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 
 import { ClerkElementsRuntimeError } from '~/internals/errors';

packages/elements/src/utils/safe-access.ts

@@ -0,0 +1,7 @@
+export function safeAccess(fn: any, fallback: any) {
+ try {
+ return fn();
+ } catch (e) {
+ return fallback;
+ }
+}

packages/nextjs/src/app-router/client/ClerkProvider.tsx

@@ -1,6 +1,8 @@
 'use client';
 import { ClerkProvider as ReactClerkProvider } from '@clerk/clerk-react';
-import { useRouter } from 'next/navigation';
+import type { ClerkHostRouter } from '@clerk/shared/router';
+import { ClerkHostRouterContext } from '@clerk/shared/router';
+import { usePathname, useRouter, useSearchParams } from 'next/navigation';
 import React, { useEffect, useTransition } from 'react';
 
 import { useSafeLayoutEffect } from '../../client-boundary/hooks/useSafeLayoutEffect';
@@ -17,12 +19,48 @@ declare global {
  __clerk_nav_await: Array<(value: void) => void>;
  __clerk_nav: (to: string) => Promise<void>;
  __clerk_internal_invalidateCachePromise: () => void | undefined;
+ next?: {
+ version: string;
+ };
  }
 }
 
+// The version that Next added support for the window.history.pushState and replaceState APIs.
+// ref: https://nextjs.org/blog/next-14-1#windowhistorypushstate-and-windowhistoryreplacestate
+export const NEXT_WINDOW_HISTORY_SUPPORT_VERSION = '14.1.0';
+
+/**
+ * Clerk router integration with Next.js's router.
+ */
+export const useNextRouter = (): ClerkHostRouter => {
+ const router = useRouter();
+ const pathname = usePathname();
+ // eslint-disable-next-line react-hooks/rules-of-hooks -- The order doesn't differ between renders as we're checking the execution environment.
+ const searchParams = typeof window === 'undefined' ? new URLSearchParams() : useSearchParams();
+
+ // The window.history APIs seem to prevent Next.js from triggering a full page re-render, allowing us to
+ // preserve internal state between steps.
+ const canUseWindowHistoryAPIs =
+ typeof window !== 'undefined' && window.next && window.next.version >= NEXT_WINDOW_HISTORY_SUPPORT_VERSION;
+
+ return {
+ mode: 'path',
+ name: 'NextRouter',
+ push: (path: string) => router.push(path),
+ replace: (path: string) =>
+ canUseWindowHistoryAPIs ? window.history.replaceState(null, '', path) : router.replace(path),
+ shallowPush(path: string) {
+ canUseWindowHistoryAPIs ? window.history.pushState(null, '', path) : router.push(path, {});
+ },
+ pathname: () => pathname,
+ searchParams: () => searchParams,
+ };
+};
+
 export const ClientClerkProvider = (props: NextClerkProviderProps) => {
  const { __unstable_invokeMiddlewareOnAuthStateChange = true, children } = props;
  const router = useRouter();
+ const clerkRouter = useNextRouter();
  const push = useAwaitablePush();
  const replace = useAwaitableReplace();
  const [isPending, startTransition] = useTransition();
@@ -57,7 +95,6 @@ export const ClientClerkProvider = (props: NextClerkProviderProps) => {
  return new Promise(res => {
  window.__clerk_internal_invalidateCachePromise = res;
  startTransition(() => {
- //@ts-expect-error next exists on window
  if (window.next?.version && typeof window.next.version === 'string' && window.next.version.startsWith('13')) {
  router.refresh();
  } else {
@@ -84,7 +121,7 @@ export const ClientClerkProvider = (props: NextClerkProviderProps) => {
  <ClerkNextOptionsProvider options={mergedProps}>
  <ReactClerkProvider {...mergedProps}>
  <ClerkJSScript router='app' />
-{children}
+<ClerkHostRouterContext.Provider value={clerkRouter}>{children}</ClerkHostRouterContext.Provider>
  </ReactClerkProvider>
  </ClerkNextOptionsProvider>
  );

.changeset/good-jeans-call.md

@@ -0,0 +1,7 @@
+---
+"@clerk/elements": minor
+"@clerk/nextjs": minor
+"@clerk/shared": minor
+---
+
+Remove `@clerk/elements` reliance on `next` and `@clerk/clerk-react` directly. The host router is now provided by `@clerk/nextjs`.

packages/elements/package.json

@@ -94,9 +94,7 @@
  "typescript": "*"
  },
  "peerDependencies": {
- "@clerk/clerk-react": "^5.0.0",
  "@clerk/shared": "^2.0.0",
- "next": "^13.5.4 || ^14.0.3 || ^15.0.0-rc",
  "react": "^18.0.0 || ^19.0.0-beta",
  "react-dom": "^18.0.0 || ^19.0.0-beta"
  },

packages/elements/src/internals/constants/index.ts

@@ -1,11 +1,18 @@
+import { safeAccess } from '~/utils/safe-access';
+
 export const SSO_CALLBACK_PATH_ROUTE = '/sso-callback';
 export const CHOOSE_SESSION_PATH_ROUTE = '/choose';
 export const MAGIC_LINK_VERIFY_PATH_ROUTE = '/verify';
 
-export const SIGN_IN_DEFAULT_BASE_PATH =
- process.env.CLERK_SIGN_IN_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_IN_URL ?? '/sign-in';
-export const SIGN_UP_DEFAULT_BASE_PATH =
- process.env.CLERK_SIGN_UP_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL ?? '/sign-up';
+// TODO: remove reliance on next-specific variables here
+export const SIGN_IN_DEFAULT_BASE_PATH = safeAccess(
+ () => process.env.CLERK_SIGN_IN_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_IN_URL,
+ '/sign-in',
+);
+export const SIGN_UP_DEFAULT_BASE_PATH = safeAccess(
+ () => process.env.CLERK_SIGN_UP_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL,
+ '/sign-up',
+);
 
 // The version that Next added support for the window.history.pushState and replaceState APIs.
 // ref: https://nextjs.org/blog/next-14-1#windowhistorypushstate-and-windowhistoryreplacestate

packages/elements/src/internals/machines/shared/shared.actors.ts

@@ -10,7 +10,7 @@ export const clerkLoader = fromCallback<EventObject, Clerk | LoadedClerk>(({ sen
  if (clerk.loaded) {
  reportLoaded();
  } else if ('addOnLoaded' in clerk) {
- // @ts-expect-error - Expects `addOnLoaded` from @clerk/clerk-react's IsomorphicClerk.
+ // @ts-expect-error - Expects `addOnLoaded` from @clerk/shared/react's IsomorphicClerk.
  clerk.addOnLoaded(reportLoaded);
  } else {
  sendBack({ type: 'ERROR', message: 'Clerk client could not be loaded' });

packages/elements/src/internals/utils/inspector/browser/index.ts

@@ -1,12 +1,16 @@
 import { isTruthy } from '@clerk/shared/underscore';
 import { createBrowserInspector } from '@statelyai/inspect';
 
+import { safeAccess } from '~/utils/safe-access';
+
 export const getInspector = () => {
  if (
  __DEV__ &&
  typeof window !== 'undefined' &&
  process.env.NODE_ENV === 'development' &&
- isTruthy(process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG_UI ?? process.env.CLERK_ELEMENTS_DEBUG_UI)
+ isTruthy(
+ safeAccess(() => process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG_UI ?? process.env.CLERK_ELEMENTS_DEBUG_UI, false),
+ )
  ) {
  const { inspect } = createBrowserInspector({
  autoStart: true,

packages/elements/src/internals/utils/inspector/console/index.ts

@@ -1,16 +1,20 @@
 import { isTruthy } from '@clerk/shared/underscore';
 
+import { safeAccess } from '~/utils/safe-access';
+
 import { createConsoleInspector } from './console';
 
 export function getInspector() {
  if (
  __DEV__ &&
  process.env.NODE_ENV === 'development' &&
- isTruthy(process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG ?? process.env.CLERK_ELEMENTS_DEBUG)
+ isTruthy(
+ safeAccess(() => process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG_UI ?? process.env.CLERK_ELEMENTS_DEBUG_UI, false),
+ )
  ) {
  return createConsoleInspector({
  enabled: true,
- debugServer: isTruthy(process.env.CLERK_ELEMENTS_DEBUG_SERVER),
+ debugServer: isTruthy(safeAccess(() => process.env.CLERK_ELEMENTS_DEBUG_SERVER, false)),
  });
  }
  return undefined;

packages/elements/src/react/common/form/input.tsx

@@ -1,5 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
 import { logger } from '@clerk/shared/logger';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import type {
  Control as RadixControl,

packages/elements/src/react/common/loading.tsx

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import type { OAuthProvider, SamlStrategy, Web3Provider } from '@clerk/types';
 import { useSelector } from '@xstate/react';

packages/elements/src/react/hooks/use-password.hook.ts

@@ -1,5 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
 import { noop } from '@clerk/shared';
+import { useClerk } from '@clerk/shared/react';
 import type { PasswordSettingsData, PasswordValidation } from '@clerk/types';
 import * as React from 'react';
 

packages/elements/src/react/hooks/use-third-party-provider.hook.ts

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import type { OAuthProvider, SamlStrategy, Web3Provider } from '@clerk/types';
 import type React from 'react';
 import { useCallback } from 'react';

packages/elements/src/react/router/index.ts

@@ -1,3 +1,2 @@
-export { useNextRouter } from './next';
 export { Route, Router, useClerkRouter } from '@clerk/shared/router';
 export { useVirtualRouter } from './virtual';

packages/elements/src/react/sign-in/root.tsx

@@ -1,4 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
+import { useClerkHostRouter } from '@clerk/shared/router';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import { useSelector } from '@xstate/react';
 import React, { useEffect } from 'react';
@@ -9,7 +10,7 @@ import { FormStoreProvider, useFormStore } from '~/internals/machines/form/form.
 import type { SignInRouterInitEvent } from '~/internals/machines/sign-in';
 import { SignInRouterMachine } from '~/internals/machines/sign-in';
 import { inspect } from '~/internals/utils/inspector';
-import { Router, useClerkRouter, useNextRouter, useVirtualRouter } from '~/react/router';
+import { Router, useClerkRouter, useVirtualRouter } from '~/react/router';
 import { SignInRouterCtx } from '~/react/sign-in/context';
 
 import { Form } from '../common/form';
@@ -39,8 +40,7 @@ function SignInFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  return;
  }
 
- // @ts-expect-error -- This is actually an IsomorphicClerk instance
- clerk.addOnLoaded(() => {
+ const cb = () => {
  const evt: SignInRouterInitEvent = {
  type: 'INIT',
  clerk,
@@ -53,7 +53,14 @@ function SignInFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  if (actor.getSnapshot().can(evt)) {
  actor.send(evt);
  }
- });
+ };
+
+ if ('addOnLoaded' in clerk) {
+ // @ts-expect-error - addOnLoaded doesn't exist on the clerk type, but it does on IsomorphicClerk, which can be hit when Elements is used standalone
+ clerk.addOnLoaded(cb);
+ } else {
+ cb();
+ }
 
  // Ensure that the latest instantiated formRef is attached to the router
  if (formRef && actor.getSnapshot().can({ type: 'RESET.STEP' })) {
@@ -123,8 +130,7 @@ export function SignInRoot({
  }),
  );
 
- // TODO: eventually we'll rely on the framework SDK to specify its host router, but for now we'll default to Next.js
- const router = (routing === ROUTING.virtual ? useVirtualRouter : useNextRouter)();
+ const router = (routing === ROUTING.virtual ? useVirtualRouter : useClerkHostRouter)();
  const isRootPath = path === router.pathname();
 
  return (

packages/elements/src/react/sign-in/step.tsx

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 
 import { ClerkElementsRuntimeError } from '~/internals/errors';

packages/elements/src/react/sign-up/root.tsx

@@ -1,4 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
+import { useClerkHostRouter } from '@clerk/shared/router';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import { useSelector } from '@xstate/react';
 import { useEffect } from 'react';
@@ -9,7 +10,7 @@ import { FormStoreProvider, useFormStore } from '~/internals/machines/form/form.
 import type { SignUpRouterInitEvent } from '~/internals/machines/sign-up';
 import { SignUpRouterMachine } from '~/internals/machines/sign-up';
 import { inspect } from '~/internals/utils/inspector';
-import { Router, useClerkRouter, useNextRouter, useVirtualRouter } from '~/react/router';
+import { Router, useClerkRouter, useVirtualRouter } from '~/react/router';
 import { SignUpRouterCtx } from '~/react/sign-up/context';
 
 import { Form } from '../common/form';
@@ -39,8 +40,7 @@ function SignUpFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  return;
  }
 
- // @ts-expect-error -- This is actually an IsomorphicClerk instance
- clerk.addOnLoaded(() => {
+ const cb = () => {
  const evt: SignUpRouterInitEvent = {
  type: 'INIT',
  clerk,
@@ -61,7 +61,14 @@ function SignUpFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  formRef,
  });
  }
- });
+ };
+
+ if ('addOnLoaded' in clerk) {
+ // @ts-expect-error - addOnLoaded doesn't exist on the clerk type, but it does on IsomorphicClerk, which can be hit when Elements is used standalone
+ clerk.addOnLoaded(cb);
+ } else {
+ cb();
+ }
  // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [clerk, exampleMode, formRef?.id, !!router, clerk.loaded]);
 
@@ -122,8 +129,7 @@ export function SignUpRoot({
  }),
  );
 
- // TODO: eventually we'll rely on the framework SDK to specify its host router, but for now we'll default to Next.js
- const router = (routing === ROUTING.virtual ? useVirtualRouter : useNextRouter)();
+ const router = (routing === ROUTING.virtual ? useVirtualRouter : useClerkHostRouter)();
  const isRootPath = path === router.pathname();
 
  return (

packages/elements/src/react/sign-up/step.tsx

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 
 import { ClerkElementsRuntimeError } from '~/internals/errors';

packages/elements/src/utils/safe-access.ts

@@ -0,0 +1,7 @@
+export function safeAccess(fn: any, fallback: any) {
+ try {
+ return fn();
+ } catch (e) {
+ return fallback;
+ }
+}

packages/nextjs/src/app-router/client/ClerkProvider.tsx

@@ -1,6 +1,8 @@
 'use client';
 import { ClerkProvider as ReactClerkProvider } from '@clerk/clerk-react';
-import { useRouter } from 'next/navigation';
+import type { ClerkHostRouter } from '@clerk/shared/router';
+import { ClerkHostRouterContext } from '@clerk/shared/router';
+import { usePathname, useRouter, useSearchParams } from 'next/navigation';
 import React, { useEffect, useTransition } from 'react';
 
 import { useSafeLayoutEffect } from '../../client-boundary/hooks/useSafeLayoutEffect';
@@ -17,12 +19,48 @@ declare global {
  __clerk_nav_await: Array<(value: void) => void>;
  __clerk_nav: (to: string) => Promise<void>;
  __clerk_internal_invalidateCachePromise: () => void | undefined;
+ next?: {
+ version: string;
+ };
  }
 }
 
+// The version that Next added support for the window.history.pushState and replaceState APIs.
+// ref: https://nextjs.org/blog/next-14-1#windowhistorypushstate-and-windowhistoryreplacestate
+export const NEXT_WINDOW_HISTORY_SUPPORT_VERSION = '14.1.0';
+
+/**
+ * Clerk router integration with Next.js's router.
+ */
+export const useNextRouter = (): ClerkHostRouter => {
+ const router = useRouter();
+ const pathname = usePathname();
+ // eslint-disable-next-line react-hooks/rules-of-hooks -- The order doesn't differ between renders as we're checking the execution environment.
+ const searchParams = typeof window === 'undefined' ? new URLSearchParams() : useSearchParams();
+
+ // The window.history APIs seem to prevent Next.js from triggering a full page re-render, allowing us to
+ // preserve internal state between steps.
+ const canUseWindowHistoryAPIs =
+ typeof window !== 'undefined' && window.next && window.next.version >= NEXT_WINDOW_HISTORY_SUPPORT_VERSION;
+
+ return {
+ mode: 'path',
+ name: 'NextRouter',
+ push: (path: string) => router.push(path),
+ replace: (path: string) =>
+ canUseWindowHistoryAPIs ? window.history.replaceState(null, '', path) : router.replace(path),
+ shallowPush(path: string) {
+ canUseWindowHistoryAPIs ? window.history.pushState(null, '', path) : router.push(path, {});
+ },
+ pathname: () => pathname,
+ searchParams: () => searchParams,
+ };
+};
+
 export const ClientClerkProvider = (props: NextClerkProviderProps) => {
  const { __unstable_invokeMiddlewareOnAuthStateChange = true, children } = props;
  const router = useRouter();
+ const clerkRouter = useNextRouter();
  const push = useAwaitablePush();
  const replace = useAwaitableReplace();
  const [isPending, startTransition] = useTransition();
@@ -57,7 +95,6 @@ export const ClientClerkProvider = (props: NextClerkProviderProps) => {
  return new Promise(res => {
  window.__clerk_internal_invalidateCachePromise = res;
  startTransition(() => {
- //@ts-expect-error next exists on window
  if (window.next?.version && typeof window.next.version === 'string' && window.next.version.startsWith('13')) {
  router.refresh();
  } else {
@@ -84,7 +121,7 @@ export const ClientClerkProvider = (props: NextClerkProviderProps) => {
  <ClerkNextOptionsProvider options={mergedProps}>
  <ReactClerkProvider {...mergedProps}>
  <ClerkJSScript router='app' />
-{children}
+<ClerkHostRouterContext.Provider value={clerkRouter}>{children}</ClerkHostRouterContext.Provider>
  </ReactClerkProvider>
  </ClerkNextOptionsProvider>
  );

.changeset/good-jeans-call.md

@@ -0,0 +1,7 @@
+---
+"@clerk/elements": minor
+"@clerk/nextjs": minor
+"@clerk/shared": minor
+---
+
+Remove `@clerk/elements` reliance on `next` and `@clerk/clerk-react` directly. The host router is now provided by `@clerk/nextjs`.

packages/elements/package.json

@@ -94,9 +94,7 @@
  "typescript": "*"
  },
  "peerDependencies": {
- "@clerk/clerk-react": "^5.0.0",
  "@clerk/shared": "^2.0.0",
- "next": "^13.5.4 || ^14.0.3 || ^15.0.0-rc",
  "react": "^18.0.0 || ^19.0.0-beta",
  "react-dom": "^18.0.0 || ^19.0.0-beta"
  },

packages/elements/src/internals/constants/index.ts

@@ -1,11 +1,18 @@
+import { safeAccess } from '~/utils/safe-access';
+
 export const SSO_CALLBACK_PATH_ROUTE = '/sso-callback';
 export const CHOOSE_SESSION_PATH_ROUTE = '/choose';
 export const MAGIC_LINK_VERIFY_PATH_ROUTE = '/verify';
 
-export const SIGN_IN_DEFAULT_BASE_PATH =
- process.env.CLERK_SIGN_IN_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_IN_URL ?? '/sign-in';
-export const SIGN_UP_DEFAULT_BASE_PATH =
- process.env.CLERK_SIGN_UP_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL ?? '/sign-up';
+// TODO: remove reliance on next-specific variables here
+export const SIGN_IN_DEFAULT_BASE_PATH = safeAccess(
+ () => process.env.CLERK_SIGN_IN_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_IN_URL,
+ '/sign-in',
+);
+export const SIGN_UP_DEFAULT_BASE_PATH = safeAccess(
+ () => process.env.CLERK_SIGN_UP_URL ?? process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL,
+ '/sign-up',
+);
 
 // The version that Next added support for the window.history.pushState and replaceState APIs.
 // ref: https://nextjs.org/blog/next-14-1#windowhistorypushstate-and-windowhistoryreplacestate

packages/elements/src/internals/machines/shared/shared.actors.ts

@@ -10,7 +10,7 @@ export const clerkLoader = fromCallback<EventObject, Clerk | LoadedClerk>(({ sen
  if (clerk.loaded) {
  reportLoaded();
  } else if ('addOnLoaded' in clerk) {
- // @ts-expect-error - Expects `addOnLoaded` from @clerk/clerk-react's IsomorphicClerk.
+ // @ts-expect-error - Expects `addOnLoaded` from @clerk/shared/react's IsomorphicClerk.
  clerk.addOnLoaded(reportLoaded);
  } else {
  sendBack({ type: 'ERROR', message: 'Clerk client could not be loaded' });

packages/elements/src/internals/utils/inspector/browser/index.ts

@@ -1,12 +1,16 @@
 import { isTruthy } from '@clerk/shared/underscore';
 import { createBrowserInspector } from '@statelyai/inspect';
 
+import { safeAccess } from '~/utils/safe-access';
+
 export const getInspector = () => {
  if (
  __DEV__ &&
  typeof window !== 'undefined' &&
  process.env.NODE_ENV === 'development' &&
- isTruthy(process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG_UI ?? process.env.CLERK_ELEMENTS_DEBUG_UI)
+ isTruthy(
+ safeAccess(() => process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG_UI ?? process.env.CLERK_ELEMENTS_DEBUG_UI, false),
+ )
  ) {
  const { inspect } = createBrowserInspector({
  autoStart: true,

packages/elements/src/internals/utils/inspector/console/index.ts

@@ -1,16 +1,20 @@
 import { isTruthy } from '@clerk/shared/underscore';
 
+import { safeAccess } from '~/utils/safe-access';
+
 import { createConsoleInspector } from './console';
 
 export function getInspector() {
  if (
  __DEV__ &&
  process.env.NODE_ENV === 'development' &&
- isTruthy(process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG ?? process.env.CLERK_ELEMENTS_DEBUG)
+ isTruthy(
+ safeAccess(() => process.env.NEXT_PUBLIC_CLERK_ELEMENTS_DEBUG_UI ?? process.env.CLERK_ELEMENTS_DEBUG_UI, false),
+ )
  ) {
  return createConsoleInspector({
  enabled: true,
- debugServer: isTruthy(process.env.CLERK_ELEMENTS_DEBUG_SERVER),
+ debugServer: isTruthy(safeAccess(() => process.env.CLERK_ELEMENTS_DEBUG_SERVER, false)),
  });
  }
  return undefined;

packages/elements/src/react/common/form/input.tsx

@@ -1,5 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
 import { logger } from '@clerk/shared/logger';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import type {
  Control as RadixControl,

packages/elements/src/react/common/loading.tsx

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import type { OAuthProvider, SamlStrategy, Web3Provider } from '@clerk/types';
 import { useSelector } from '@xstate/react';

packages/elements/src/react/hooks/use-password.hook.ts

@@ -1,5 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
 import { noop } from '@clerk/shared';
+import { useClerk } from '@clerk/shared/react';
 import type { PasswordSettingsData, PasswordValidation } from '@clerk/types';
 import * as React from 'react';
 

packages/elements/src/react/hooks/use-third-party-provider.hook.ts

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import type { OAuthProvider, SamlStrategy, Web3Provider } from '@clerk/types';
 import type React from 'react';
 import { useCallback } from 'react';

packages/elements/src/react/router/index.ts

@@ -1,3 +1,2 @@
-export { useNextRouter } from './next';
 export { Route, Router, useClerkRouter } from '@clerk/shared/router';
 export { useVirtualRouter } from './virtual';

packages/elements/src/react/sign-in/root.tsx

@@ -1,4 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
+import { useClerkHostRouter } from '@clerk/shared/router';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import { useSelector } from '@xstate/react';
 import React, { useEffect } from 'react';
@@ -9,7 +10,7 @@ import { FormStoreProvider, useFormStore } from '~/internals/machines/form/form.
 import type { SignInRouterInitEvent } from '~/internals/machines/sign-in';
 import { SignInRouterMachine } from '~/internals/machines/sign-in';
 import { inspect } from '~/internals/utils/inspector';
-import { Router, useClerkRouter, useNextRouter, useVirtualRouter } from '~/react/router';
+import { Router, useClerkRouter, useVirtualRouter } from '~/react/router';
 import { SignInRouterCtx } from '~/react/sign-in/context';
 
 import { Form } from '../common/form';
@@ -39,8 +40,7 @@ function SignInFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  return;
  }
 
- // @ts-expect-error -- This is actually an IsomorphicClerk instance
- clerk.addOnLoaded(() => {
+ const cb = () => {
  const evt: SignInRouterInitEvent = {
  type: 'INIT',
  clerk,
@@ -53,7 +53,14 @@ function SignInFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  if (actor.getSnapshot().can(evt)) {
  actor.send(evt);
  }
- });
+ };
+
+ if ('addOnLoaded' in clerk) {
+ // @ts-expect-error - addOnLoaded doesn't exist on the clerk type, but it does on IsomorphicClerk, which can be hit when Elements is used standalone
+ clerk.addOnLoaded(cb);
+ } else {
+ cb();
+ }
 
  // Ensure that the latest instantiated formRef is attached to the router
  if (formRef && actor.getSnapshot().can({ type: 'RESET.STEP' })) {
@@ -123,8 +130,7 @@ export function SignInRoot({
  }),
  );
 
- // TODO: eventually we'll rely on the framework SDK to specify its host router, but for now we'll default to Next.js
- const router = (routing === ROUTING.virtual ? useVirtualRouter : useNextRouter)();
+ const router = (routing === ROUTING.virtual ? useVirtualRouter : useClerkHostRouter)();
  const isRootPath = path === router.pathname();
 
  return (

packages/elements/src/react/sign-in/step.tsx

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 
 import { ClerkElementsRuntimeError } from '~/internals/errors';

packages/elements/src/react/sign-up/root.tsx

@@ -1,4 +1,5 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
+import { useClerkHostRouter } from '@clerk/shared/router';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import { useSelector } from '@xstate/react';
 import { useEffect } from 'react';
@@ -9,7 +10,7 @@ import { FormStoreProvider, useFormStore } from '~/internals/machines/form/form.
 import type { SignUpRouterInitEvent } from '~/internals/machines/sign-up';
 import { SignUpRouterMachine } from '~/internals/machines/sign-up';
 import { inspect } from '~/internals/utils/inspector';
-import { Router, useClerkRouter, useNextRouter, useVirtualRouter } from '~/react/router';
+import { Router, useClerkRouter, useVirtualRouter } from '~/react/router';
 import { SignUpRouterCtx } from '~/react/sign-up/context';
 
 import { Form } from '../common/form';
@@ -39,8 +40,7 @@ function SignUpFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  return;
  }
 
- // @ts-expect-error -- This is actually an IsomorphicClerk instance
- clerk.addOnLoaded(() => {
+ const cb = () => {
  const evt: SignUpRouterInitEvent = {
  type: 'INIT',
  clerk,
@@ -61,7 +61,14 @@ function SignUpFlowProvider({ children, exampleMode, fallback, isRootPath }: Sig
  formRef,
  });
  }
- });
+ };
+
+ if ('addOnLoaded' in clerk) {
+ // @ts-expect-error - addOnLoaded doesn't exist on the clerk type, but it does on IsomorphicClerk, which can be hit when Elements is used standalone
+ clerk.addOnLoaded(cb);
+ } else {
+ cb();
+ }
  // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [clerk, exampleMode, formRef?.id, !!router, clerk.loaded]);
 
@@ -122,8 +129,7 @@ export function SignUpRoot({
  }),
  );
 
- // TODO: eventually we'll rely on the framework SDK to specify its host router, but for now we'll default to Next.js
- const router = (routing === ROUTING.virtual ? useVirtualRouter : useNextRouter)();
+ const router = (routing === ROUTING.virtual ? useVirtualRouter : useClerkHostRouter)();
  const isRootPath = path === router.pathname();
 
  return (

packages/elements/src/react/sign-up/step.tsx

@@ -1,4 +1,4 @@
-import { useClerk } from '@clerk/clerk-react';
+import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 
 import { ClerkElementsRuntimeError } from '~/internals/errors';

packages/elements/src/utils/safe-access.ts

@@ -0,0 +1,7 @@
+export function safeAccess(fn: any, fallback: any) {
+ try {
+ return fn();
+ } catch (e) {
+ return fallback;
+ }
+}

packages/nextjs/src/app-router/client/ClerkProvider.tsx

@@ -1,6 +1,8 @@
 'use client';
 import { ClerkProvider as ReactClerkProvider } from '@clerk/clerk-react';
-import { useRouter } from 'next/navigation';
+import type { ClerkHostRouter } from '@clerk/shared/router';
+import { ClerkHostRouterContext } from '@clerk/shared/router';
+import { usePathname, useRouter, useSearchParams } from 'next/navigation';
 import React, { useEffect, useTransition } from 'react';
 
 import { useSafeLayoutEffect } from '../../client-boundary/hooks/useSafeLayoutEffect';
@@ -17,12 +19,48 @@ declare global {
  __clerk_nav_await: Array<(value: void) => void>;
  __clerk_nav: (to: string) => Promise<void>;
  __clerk_internal_invalidateCachePromise: () => void | undefined;
+ next?: {
+ version: string;
+ };
  }
 }
 
+// The version that Next added support for the window.history.pushState and replaceState APIs.
+// ref: https://nextjs.org/blog/next-14-1#windowhistorypushstate-and-windowhistoryreplacestate
+export const NEXT_WINDOW_HISTORY_SUPPORT_VERSION = '14.1.0';
+
+/**
+ * Clerk router integration with Next.js's router.
+ */
+export const useNextRouter = (): ClerkHostRouter => {
+ const router = useRouter();
+ const pathname = usePathname();
+ // eslint-disable-next-line react-hooks/rules-of-hooks -- The order doesn't differ between renders as we're checking the execution environment.
+ const searchParams = typeof window === 'undefined' ? new URLSearchParams() : useSearchParams();
+
+ // The window.history APIs seem to prevent Next.js from triggering a full page re-render, allowing us to
+ // preserve internal state between steps.
+ const canUseWindowHistoryAPIs =
+ typeof window !== 'undefined' && window.next && window.next.version >= NEXT_WINDOW_HISTORY_SUPPORT_VERSION;
+
+ return {
+ mode: 'path',
+ name: 'NextRouter',
+ push: (path: string) => router.push(path),
+ replace: (path: string) =>
+ canUseWindowHistoryAPIs ? window.history.replaceState(null, '', path) : router.replace(path),
+ shallowPush(path: string) {
+ canUseWindowHistoryAPIs ? window.history.pushState(null, '', path) : router.push(path, {});
+ },
+ pathname: () => pathname,
+ searchParams: () => searchParams,
+ };
+};
+
 export const ClientClerkProvider = (props: NextClerkProviderProps) => {
  const { __unstable_invokeMiddlewareOnAuthStateChange = true, children } = props;
  const router = useRouter();
+ const clerkRouter = useNextRouter();
  const push = useAwaitablePush();
  const replace = useAwaitableReplace();
  const [isPending, startTransition] = useTransition();
@@ -57,7 +95,6 @@ export const ClientClerkProvider = (props: NextClerkProviderProps) => {
  return new Promise(res => {
  window.__clerk_internal_invalidateCachePromise = res;
  startTransition(() => {
- //@ts-expect-error next exists on window
  if (window.next?.version && typeof window.next.version === 'string' && window.next.version.startsWith('13')) {
  router.refresh();
  } else {
@@ -84,7 +121,7 @@ export const ClientClerkProvider = (props: NextClerkProviderProps) => {
  <ClerkNextOptionsProvider options={mergedProps}>
  <ReactClerkProvider {...mergedProps}>
  <ClerkJSScript router='app' />
-{children}
+<ClerkHostRouterContext.Provider value={clerkRouter}>{children}</ClerkHostRouterContext.Provider>
  </ReactClerkProvider>
  </ClerkNextOptionsProvider>
  );