feat(tanstack-start): Throw more useful error when clerkHandler is not configured (clerk#3918)

Author: octoper

.changeset/rotten-mangos-hear.md

@@ -0,0 +1,5 @@
+---
+"@clerk/tanstack-start": minor
+---
+
+Throw a more useful error when `clerkHandler()` is not configured in the SSR entrypoint

packages/tanstack-start/README.md

@@ -119,7 +119,9 @@ function RootComponent() {
 function RootDocument({ children }: { children: React.ReactNode }) { ... }
 ```
 
-Also you will need to make on more modification to `app/ssr.tsx`:
+### Setup `clerkHandler` in the SSR entrypoint
+
+You will also need to make on more modification to you SSR entrypoint (default: `app/ssr.tsx`):
 
 - Wrap the `createStartHandler` with `createClerkHandler`
 

packages/tanstack-start/src/client/ClerkProvider.tsx

@@ -3,18 +3,19 @@ import { useRouteContext } from '@tanstack/react-router';
 import { Asset } from '@tanstack/start';
 import { useEffect } from 'react';
 
-import { isClient } from '../utils';
+import { errorThrower, isClient } from '../utils';
+import { clerkHandlerNotConfigured } from '../utils/errors';
 import { ClerkOptionsProvider } from './OptionsContext';
 import type { TanstackStartClerkProviderProps } from './types';
 import { useAwaitableNavigate } from './useAwaitableNavigate';
 
+export * from '@clerk/clerk-react';
+
 const SDK_METADATA = {
   name: PACKAGE_NAME,
   version: PACKAGE_VERSION,
 };
 
-export * from '@clerk/clerk-react';
-
 const awaitableNavigateRef: { current: ReturnType<typeof useAwaitableNavigate> | undefined } = { current: undefined };
 
 export function ClerkProvider({ children, ...providerProps }: TanstackStartClerkProviderProps): JSX.Element {
@@ -27,6 +28,10 @@ export function ClerkProvider({ children, ...providerProps }: TanstackStartClerk
     awaitableNavigateRef.current = awaitableNavigate;
   }, [awaitableNavigate]);
 
+  if (!routerContext?.clerkInitialState?.__internal_clerk_state) {
+    errorThrower.throw(clerkHandlerNotConfigured);
+  }
+
   const clerkInitState = isClient() ? (window as any).__clerk_init_state : routerContext?.clerkInitialState;
 
   const {

packages/tanstack-start/src/utils/errors.ts

@@ -16,3 +16,11 @@ export const noFetchFnCtxPassedInGetAuth = createErrorMessage(`
     ...
   });
   `);
+
+export const clerkHandlerNotConfigured = createErrorMessage(`
+    It looks like you're trying to use Clerk without configuring the Clerk handler.
+
+    To fix this, make sure you have the \`clerkHandler()\` configure in you SSR entry file (example: app/ssr.tsx).
+
+    For more info, check out the docs: https://github.com/clerk/javascript/tree/main/packages/tanstack-start#setup-clerkhandler-in-the-ssr-entrypoint,
+    `);