fix(clerk-js,astro,nuxt,tanstack-react-start,remix,react-router): Introduce helper function to prevent infinite handshake in Netlify (#5656)

wobsoriano · LekoArts · web-flow · commit 27166224e12a · 2025-04-30T20:07:29.000Z
Co-authored-by: Lennart &lt;lekoarts@gmail.com&gt;
diff --git a/.changeset/plenty-hounds-sort.md b/.changeset/plenty-hounds-sort.md
@@ -0,0 +1,11 @@
+---
+"@clerk/astro": patch
+"@clerk/clerk-js": patch
+"@clerk/nuxt": patch
+"@clerk/react-router": patch
+"@clerk/remix": patch
+"@clerk/shared": patch
+"@clerk/tanstack-react-start": patch
+---
+
+Fix handshake redirect loop in applications deployed to Netlify with a Clerk development instance.
diff --git a/packages/astro/src/integration/create-integration.ts b/packages/astro/src/integration/create-integration.ts
@@ -125,10 +125,7 @@ function createIntegration<Params extends HotloadAstroClerkIntegrationParams>()
             'page',
             `
             ${command === 'dev' ? `console.log("${packageName}","Initialize Clerk: page")` : ''}
-            import { removeNetlifyCacheBustParam, runInjectionScript, swapDocument } from "${buildImportPath}";
-
-            // Fix an issue with infinite redirect in Netlify and Clerk dev instance
-            removeNetlifyCacheBustParam();
+            import { runInjectionScript, swapDocument } from "${buildImportPath}";
 
             // Taken from https://github.com/withastro/astro/blob/e10b03e88c22592fbb42d7245b65c4f486ab736d/packages/astro/src/transitions/router.ts#L39.
             // Importing it directly from astro:transitions/client breaks custom client-side routing
diff --git a/packages/astro/src/internal/index.ts b/packages/astro/src/internal/index.ts
@@ -14,4 +14,3 @@ export { runInjectionScript };
 
 export { generateSafeId } from './utils/generateSafeId';
 export { swapDocument } from './swap-document';
-export { NETLIFY_CACHE_BUST_PARAM, removeNetlifyCacheBustParam } from './remove-query-param';
diff --git a/packages/astro/src/internal/remove-query-param.ts b/packages/astro/src/internal/remove-query-param.ts
diff --git a/packages/astro/src/server/clerk-middleware.ts b/packages/astro/src/server/clerk-middleware.ts
@@ -1,14 +1,14 @@
 import type { AuthObject, ClerkClient } from '@clerk/backend';
 import type { AuthenticateRequestOptions, ClerkRequest, RedirectFun, RequestState } from '@clerk/backend/internal';
 import { AuthStatus, constants, createClerkRequest, createRedirect } from '@clerk/backend/internal';
-import { isDevelopmentFromPublishableKey, isDevelopmentFromSecretKey } from '@clerk/shared/keys';
+import { isDevelopmentFromSecretKey } from '@clerk/shared/keys';
+import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
 import { isHttpOrHttps } from '@clerk/shared/proxy';
 import { handleValueOrFn } from '@clerk/shared/utils';
 import type { APIContext } from 'astro';
 
 import { authAsyncStorage } from '#async-local-storage';
 
-import { NETLIFY_CACHE_BUST_PARAM } from '../internal';
 import { buildClerkHotloadScript } from './build-clerk-hotload-script';
 import { clerkClient } from './clerk-client';
 import { createCurrentUser } from './current-user';
@@ -74,7 +74,11 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]): any => {
 
     const locationHeader = requestState.headers.get(constants.Headers.Location);
     if (locationHeader) {
-      handleNetlifyCacheInDevInstance(locationHeader, requestState);
+      handleNetlifyCacheInDevInstance({
+        locationHeader,
+        requestStateHeaders: requestState.headers,
+        publishableKey: requestState.publishableKey,
+      });
 
       const res = new Response(null, { status: 307, headers: requestState.headers });
       return decorateResponseWithObservabilityHeaders(res, requestState);
@@ -234,25 +238,6 @@ Check if signInUrl is missing from your configuration or if it is not an absolut
    PUBLIC_CLERK_SIGN_IN_URL='SOME_URL'
    PUBLIC_CLERK_IS_SATELLITE='true'`;
 
-/**
- * Prevents infinite redirects in Netlify's functions
- * by adding a cache bust parameter to the original redirect URL. This ensures Netlify
- * doesn't serve a cached response during the authentication flow.
- */
-function handleNetlifyCacheInDevInstance(locationHeader: string, requestState: RequestState) {
-  // Only run on Netlify environment and Clerk development instance
-  // eslint-disable-next-line turbo/no-undeclared-env-vars
-  if (import.meta.env.NETLIFY && isDevelopmentFromPublishableKey(requestState.publishableKey)) {
-    const hasHandshakeQueryParam = locationHeader.includes('__clerk_handshake');
-    // If location header is the original URL before the handshake redirects, add cache bust param
-    if (!hasHandshakeQueryParam) {
-      const url = new URL(locationHeader);
-      url.searchParams.append(NETLIFY_CACHE_BUST_PARAM, Date.now().toString());
-      requestState.headers.set('Location', url.toString());
-    }
-  }
-}
-
 function decorateAstroLocal(clerkRequest: ClerkRequest, context: APIContext, requestState: RequestState) {
   const { reason, message, status, token } = requestState;
   context.locals.authToken = token;
diff --git a/packages/clerk-js/src/core/clerk.ts b/packages/clerk-js/src/core/clerk.ts
@@ -5,6 +5,7 @@ import { ClerkRuntimeError, EmailLinkErrorCodeStatus, is4xxError, isClerkAPIResp
 import { parsePublishableKey } from '@clerk/shared/keys';
 import { LocalStorageBroadcastChannel } from '@clerk/shared/localStorageBroadcastChannel';
 import { logger } from '@clerk/shared/logger';
+import { CLERK_NETLIFY_CACHE_BUST_PARAM } from '@clerk/shared/netlifyCacheHandler';
 import { isHttpOrHttps, isValidProxyUrl, proxyUrlToAbsoluteURL } from '@clerk/shared/proxy';
 import {
   eventPrebuiltComponentMounted,
@@ -2622,6 +2623,7 @@ export class Clerk implements ClerkInterface {
   #clearClerkQueryParams = () => {
     try {
       removeClerkQueryParam(CLERK_SYNCED);
+      removeClerkQueryParam(CLERK_NETLIFY_CACHE_BUST_PARAM);
       // @nikos: we're looking into dropping this param completely
       // in the meantime, we're removing it here to keep the URL clean
       removeClerkQueryParam(CLERK_SUFFIXED_COOKIES);
diff --git a/packages/clerk-js/src/utils/getClerkQueryParam.ts b/packages/clerk-js/src/utils/getClerkQueryParam.ts
@@ -1,4 +1,5 @@
 import type { EmailLinkErrorCodeStatus } from '@clerk/shared/error';
+import { CLERK_NETLIFY_CACHE_BUST_PARAM } from '@clerk/shared/netlifyCacheHandler';
 
 import { CLERK_SATELLITE_URL, CLERK_SUFFIXED_COOKIES, CLERK_SYNCED } from '../core/constants';
 
@@ -10,6 +11,7 @@ const _ClerkQueryParams = [
   '__clerk_modal_state',
   '__clerk_handshake',
   '__clerk_help',
+  CLERK_NETLIFY_CACHE_BUST_PARAM,
   CLERK_SYNCED,
   CLERK_SATELLITE_URL,
   CLERK_SUFFIXED_COOKIES,
diff --git a/packages/nuxt/src/runtime/server/clerkMiddleware.ts b/packages/nuxt/src/runtime/server/clerkMiddleware.ts
@@ -1,6 +1,7 @@
 import type { AuthenticateRequestOptions } from '@clerk/backend/internal';
 import { AuthStatus, constants } from '@clerk/backend/internal';
 import { deprecated } from '@clerk/shared/deprecated';
+import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
 import type { EventHandler } from 'h3';
 import { createError, eventHandler, setResponseHeader } from 'h3';
 
@@ -84,6 +85,11 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
 
     const locationHeader = requestState.headers.get(constants.Headers.Location);
     if (locationHeader) {
+      handleNetlifyCacheInDevInstance({
+        locationHeader,
+        requestStateHeaders: requestState.headers,
+        publishableKey: requestState.publishableKey,
+      });
       // Trigger a handshake redirect
       return new Response(null, { status: 307, headers: requestState.headers });
     }
diff --git a/packages/react-router/src/ssr/authenticateRequest.ts b/packages/react-router/src/ssr/authenticateRequest.ts
@@ -1,6 +1,7 @@
 import { createClerkClient } from '@clerk/backend';
 import type { AuthenticateRequestOptions, SignedInState, SignedOutState } from '@clerk/backend/internal';
-import { AuthStatus } from '@clerk/backend/internal';
+import { AuthStatus, constants } from '@clerk/backend/internal';
+import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
 
 import type { LoaderFunctionArgs } from './types';
 import { patchRequest } from './utils';
@@ -33,8 +34,13 @@ export async function authenticateRequest(
     afterSignUpUrl,
   });
 
-  const hasLocationHeader = requestState.headers.get('location');
-  if (hasLocationHeader) {
+  const locationHeader = requestState.headers.get(constants.Headers.Location);
+  if (locationHeader) {
+    handleNetlifyCacheInDevInstance({
+      locationHeader,
+      requestStateHeaders: requestState.headers,
+      publishableKey: requestState.publishableKey,
+    });
     // triggering a handshake redirect
     // eslint-disable-next-line @typescript-eslint/only-throw-error
     throw new Response(null, { status: 307, headers: requestState.headers });
diff --git a/packages/remix/src/ssr/authenticateRequest.ts b/packages/remix/src/ssr/authenticateRequest.ts
@@ -1,6 +1,7 @@
 import { createClerkClient } from '@clerk/backend';
 import type { AuthenticateRequestOptions, SignedInState, SignedOutState } from '@clerk/backend/internal';
-import { AuthStatus } from '@clerk/backend/internal';
+import { AuthStatus, constants } from '@clerk/backend/internal';
+import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
 
 import type { LoaderFunctionArgs } from './types';
 import { patchRequest } from './utils';
@@ -33,8 +34,13 @@ export async function authenticateRequest(
     afterSignUpUrl,
   });
 
-  const hasLocationHeader = requestState.headers.get('location');
-  if (hasLocationHeader) {
+  const locationHeader = requestState.headers.get(constants.Headers.Location);
+  if (locationHeader) {
+    handleNetlifyCacheInDevInstance({
+      locationHeader,
+      requestStateHeaders: requestState.headers,
+      publishableKey: requestState.publishableKey,
+    });
     // triggering a handshake redirect
     // eslint-disable-next-line @typescript-eslint/only-throw-error
     throw new Response(null, { status: 307, headers: requestState.headers });
diff --git a/packages/shared/package.json b/packages/shared/package.json
@@ -120,6 +120,7 @@
     "organization",
     "jwtPayloadParser",
     "eventBus",
+    "netlifyCacheHandler",
     "clerkEventBus"
   ],
   "scripts": {
diff --git a/packages/shared/src/__tests__/netlifyCacheHandler.test.ts b/packages/shared/src/__tests__/netlifyCacheHandler.test.ts
@@ -0,0 +1,63 @@
+/* eslint-disable turbo/no-undeclared-env-vars */
+import { CLERK_NETLIFY_CACHE_BUST_PARAM, handleNetlifyCacheInDevInstance } from '../netlifyCacheHandler';
+
+const mockPublishableKey = 'pk_test_YW55LW9mZabcZS1wYWdlX3BhZ2VfcG9pbnRlci1pZF90ZXN0XzE';
+
+describe('handleNetlifyCacheInDevInstance', () => {
+  beforeEach(() => {
+    delete process.env.URL;
+    delete process.env.NETLIFY;
+  });
+
+  it('should add cache bust parameter when on Netlify and in development', () => {
+    process.env.NETLIFY = 'true';
+    process.env.URL = 'https://example.netlify.app';
+
+    const requestStateHeaders = new Headers({
+      Location: 'https://example.netlify.app',
+    });
+    const locationHeader = requestStateHeaders.get('Location') || '';
+
+    handleNetlifyCacheInDevInstance({
+      locationHeader,
+      requestStateHeaders,
+      publishableKey: mockPublishableKey,
+    });
+
+    const locationUrl = new URL(requestStateHeaders.get('Location') || '');
+    expect(locationUrl.searchParams.has(CLERK_NETLIFY_CACHE_BUST_PARAM)).toBe(true);
+  });
+
+  it('should not modify the Location header if it has the handshake param', () => {
+    process.env.URL = 'https://example.netlify.app';
+    process.env.NETLIFY = 'true';
+
+    const requestStateHeaders = new Headers({
+      Location: 'https://example.netlify.app/redirect?__clerk_handshake=',
+    });
+    const locationHeader = requestStateHeaders.get('Location') || '';
+
+    handleNetlifyCacheInDevInstance({
+      locationHeader,
+      requestStateHeaders,
+      publishableKey: mockPublishableKey,
+    });
+
+    expect(requestStateHeaders.get('Location')).toBe(locationHeader);
+  });
+
+  it('should not modify the Location header if not on Netlify', () => {
+    const requestStateHeaders = new Headers({
+      Location: 'https://example.netlify.app',
+    });
+    const locationHeader = requestStateHeaders.get('Location') || '';
+
+    handleNetlifyCacheInDevInstance({
+      locationHeader,
+      requestStateHeaders,
+      publishableKey: mockPublishableKey,
+    });
+
+    expect(requestStateHeaders.get('Location')).toBe('https://example.netlify.app');
+  });
+});
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
@@ -36,3 +36,4 @@ export { createWorkerTimers } from './workerTimers';
 export { DEV_BROWSER_JWT_KEY, extractDevBrowserJWTFromURL, setDevBrowserJWTInURL } from './devBrowser';
 export { getEnvVariable } from './getEnvVariable';
 export * from './pathMatcher';
+export * from './netlifyCacheHandler';
diff --git a/packages/shared/src/netlifyCacheHandler.ts b/packages/shared/src/netlifyCacheHandler.ts
@@ -0,0 +1,48 @@
+/* eslint-disable turbo/no-undeclared-env-vars */
+import { isDevelopmentFromPublishableKey } from './keys';
+
+/**
+ * Cache busting parameter for Netlify to prevent cached responses
+ * during handshake flows with Clerk development instances.
+ *
+ * Note: This query parameter will be removed in the "@clerk/clerk-js" package.
+ *
+ * @internal
+ */
+export const CLERK_NETLIFY_CACHE_BUST_PARAM = '__clerk_netlify_cache_bust';
+
+/**
+ * Prevents infinite redirects in Netlify's functions by adding a cache bust parameter
+ * to the original redirect URL. This ensures that Netlify doesn't serve a cached response
+ * during the handshake flow.
+ *
+ * The issue happens only on Clerk development instances running on Netlify. This is
+ * a workaround until we find a better solution.
+ *
+ * See https://answers.netlify.com/t/cache-handling-recommendation-for-authentication-handshake-redirects/143969/1
+ *
+ * @internal
+ */
+export function handleNetlifyCacheInDevInstance({
+  locationHeader,
+  requestStateHeaders,
+  publishableKey,
+}: {
+  locationHeader: string;
+  requestStateHeaders: Headers;
+  publishableKey: string;
+}) {
+  const isOnNetlify =
+    process.env.NETLIFY || process.env.URL?.endsWith('netlify.app') || Boolean(process.env.NETLIFY_FUNCTIONS_TOKEN);
+  const isDevelopmentInstance = isDevelopmentFromPublishableKey(publishableKey);
+  if (isOnNetlify && isDevelopmentInstance) {
+    const hasHandshakeQueryParam = locationHeader.includes('__clerk_handshake');
+    // If location header is the original URL before the handshake flow, add cache bust param
+    // The param should be removed in clerk-js
+    if (!hasHandshakeQueryParam) {
+      const url = new URL(locationHeader);
+      url.searchParams.append(CLERK_NETLIFY_CACHE_BUST_PARAM, Date.now().toString());
+      requestStateHeaders.set('Location', url.toString());
+    }
+  }
+}
diff --git a/packages/tanstack-react-start/src/server/authenticateRequest.ts b/packages/tanstack-react-start/src/server/authenticateRequest.ts
@@ -1,6 +1,7 @@
 import { createClerkClient } from '@clerk/backend';
 import type { AuthenticateRequestOptions, SignedInState, SignedOutState } from '@clerk/backend/internal';
-import { AuthStatus } from '@clerk/backend/internal';
+import { AuthStatus, constants } from '@clerk/backend/internal';
+import { handleNetlifyCacheInDevInstance } from '@clerk/shared/netlifyCacheHandler';
 
 import { errorThrower } from '../utils';
 import { patchRequest } from './utils';
@@ -32,8 +33,13 @@ export async function authenticateRequest(
     afterSignUpUrl,
   });
 
-  const hasLocationHeader = requestState.headers.get('location');
-  if (hasLocationHeader) {
+  const locationHeader = requestState.headers.get(constants.Headers.Location);
+  if (locationHeader) {
+    handleNetlifyCacheInDevInstance({
+      locationHeader,
+      requestStateHeaders: requestState.headers,
+      publishableKey: requestState.publishableKey,
+    });
     // triggering a handshake redirect
     // eslint-disable-next-line @typescript-eslint/only-throw-error
     throw new Response(null, { status: 307, headers: requestState.headers });

Original file line number	Diff line number	Diff line change
`@@ -14,4 +14,3 @@ export { runInjectionScript };`
`14`	`14`
`15`	`15`	`export { generateSafeId } from './utils/generateSafeId';`
`16`	`16`	`export { swapDocument } from './swap-document';`
`17`		`-export { NETLIFY_CACHE_BUST_PARAM, removeNetlifyCacheBustParam } from './remove-query-param';`