feat(nextjs): Support auth().redirectToSignUp() (#5533)

panteliselef · web-flow · commit 4e0dfdbee098 · 2025-04-07T14:02:48.000+03:00
diff --git a/.changeset/spicy-lizards-take.md b/.changeset/spicy-lizards-take.md
@@ -0,0 +1,17 @@
+---
+'@clerk/nextjs': minor
+---
+
+- Introduce `auth().redirectToSignUp()` that can be used in API routes and pages. Originally effort by [@sambarnes](https://github.com/clerk/javascript/pull/5407)
+
+```ts
+import { clerkMiddleware } from '@clerk/nextjs/server';
+
+export default clerkMiddleware(async (auth) => {
+  const { userId, redirectToSignUp } = await auth();
+
+  if (!userId) {
+    return redirectToSignUp();
+  }
+});
+```
diff --git a/packages/backend/src/createRedirect.ts b/packages/backend/src/createRedirect.ts
@@ -97,7 +97,18 @@ export const createRedirect: CreateRedirect = params => {
     }
 
     const accountsSignUpUrl = `${accountsBaseUrl}/sign-up`;
-    const targetUrl = signUpUrl || accountsSignUpUrl;
+
+    // Allows redirection to SignInOrUp path
+    function buildSignUpUrl(signIn: string | URL | undefined) {
+      if (!signIn) {
+        return;
+      }
+      const url = new URL(signIn, baseUrl);
+      url.pathname = `${url.pathname}/create`;
+      return url.toString();
+    }
+
+    const targetUrl = signUpUrl || buildSignUpUrl(signInUrl) || accountsSignUpUrl;
 
     if (hasPendingStatus) {
       return redirectToTasks(targetUrl, { returnBackUrl });
diff --git a/packages/nextjs/src/app-router/server/auth.ts b/packages/nextjs/src/app-router/server/auth.ts
@@ -25,6 +25,16 @@ type Auth = AuthObject & {
    * `auth()` on the server-side can only access redirect URLs defined via [environment variables](https://clerk.com/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) or [`clerkMiddleware` dynamic keys](https://clerk.com/docs/references/nextjs/clerk-middleware#dynamic-keys).
    */
   redirectToSignIn: RedirectFun<ReturnType<typeof redirect>>;
+
+  /**
+   * The `auth()` helper returns the `redirectToSignUp()` method, which you can use to redirect the user to the sign-up page.
+   *
+   * @param [returnBackUrl] {string | URL} - The URL to redirect the user back to after they sign up.
+   *
+   * @note
+   * `auth()` on the server-side can only access redirect URLs defined via [environment variables](https://clerk.com/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) or [`clerkMiddleware` dynamic keys](https://clerk.com/docs/references/nextjs/clerk-middleware#dynamic-keys).
+   */
+  redirectToSignUp: RedirectFun<ReturnType<typeof redirect>>;
 };
 
 export interface AuthFn {
@@ -83,29 +93,44 @@ export const auth: AuthFn = async () => {
 
   const clerkUrl = getAuthKeyFromRequest(request, 'ClerkUrl');
 
-  const redirectToSignIn: RedirectFun<never> = (opts = {}) => {
+  const createRedirectForRequest = (...args: Parameters<RedirectFun<never>>) => {
+    const { returnBackUrl } = args[0] || {};
     const clerkRequest = createClerkRequest(request);
     const devBrowserToken =
       clerkRequest.clerkUrl.searchParams.get(constants.QueryParameters.DevBrowser) ||
       clerkRequest.cookies.get(constants.Cookies.DevBrowser);
 
     const encryptedRequestData = getHeader(request, constants.Headers.ClerkRequestData);
     const decryptedRequestData = decryptClerkRequestData(encryptedRequestData);
+    return [
+      createRedirect({
+        redirectAdapter: redirect,
+        devBrowserToken: devBrowserToken,
+        baseUrl: clerkRequest.clerkUrl.toString(),
+        publishableKey: decryptedRequestData.publishableKey || PUBLISHABLE_KEY,
+        signInUrl: decryptedRequestData.signInUrl || SIGN_IN_URL,
+        signUpUrl: decryptedRequestData.signUpUrl || SIGN_UP_URL,
+        sessionStatus: authObject.sessionStatus,
+      }),
+      returnBackUrl === null ? '' : returnBackUrl || clerkUrl?.toString(),
+    ] as const;
+  };
+
+  const redirectToSignIn: RedirectFun<never> = (opts = {}) => {
+    const [r, returnBackUrl] = createRedirectForRequest(opts);
+    return r.redirectToSignIn({
+      returnBackUrl,
+    });
+  };
 
-    return createRedirect({
-      redirectAdapter: redirect,
-      devBrowserToken: devBrowserToken,
-      baseUrl: clerkRequest.clerkUrl.toString(),
-      publishableKey: decryptedRequestData.publishableKey || PUBLISHABLE_KEY,
-      signInUrl: decryptedRequestData.signInUrl || SIGN_IN_URL,
-      signUpUrl: decryptedRequestData.signUpUrl || SIGN_UP_URL,
-      sessionStatus: authObject.sessionStatus,
-    }).redirectToSignIn({
-      returnBackUrl: opts.returnBackUrl === null ? '' : opts.returnBackUrl || clerkUrl?.toString(),
+  const redirectToSignUp: RedirectFun<never> = (opts = {}) => {
+    const [r, returnBackUrl] = createRedirectForRequest(opts);
+    return r.redirectToSignUp({
+      returnBackUrl,
     });
   };
 
-  return Object.assign(authObject, { redirectToSignIn });
+  return Object.assign(authObject, { redirectToSignIn, redirectToSignUp });
 };
 
 auth.protect = async (...args: any[]) => {
diff --git a/packages/nextjs/src/server/__tests__/clerkMiddleware.test.ts b/packages/nextjs/src/server/__tests__/clerkMiddleware.test.ts
@@ -12,6 +12,8 @@ import { clerkMiddleware } from '../clerkMiddleware';
 import { createRouteMatcher } from '../routeMatcher';
 import { decryptClerkRequestData } from '../utils';
 
+vi.mock('../clerkClient');
+
 const publishableKey = 'pk_test_Y2xlcmsuaW5jbHVkZWQua2F0eWRpZC05Mi5sY2wuZGV2JA';
 const authenticateRequestMock = vi.fn().mockResolvedValue({
   toAuth: () => ({
@@ -21,15 +23,6 @@ const authenticateRequestMock = vi.fn().mockResolvedValue({
   publishableKey,
 });
 
-vi.mock('../clerkClient', () => {
-  return {
-    clerkClient: () => ({
-      authenticateRequest: authenticateRequestMock,
-      telemetry: { record: vi.fn() },
-    }),
-  };
-});
-
 /**
  * Disable console warnings about config matchers
  */
@@ -45,6 +38,14 @@ afterAll(() => {
   global.console.log = consoleLog;
 });
 
+beforeEach(() => {
+  vi.mocked(clerkClient).mockResolvedValue({
+    authenticateRequest: authenticateRequestMock,
+    // @ts-expect-error - mock
+    telemetry: { record: vi.fn() },
+  });
+});
+
 // Removing this mock will cause the clerkMiddleware tests to fail due to missing publishable key
 // This mock SHOULD exist before the imports
 vi.mock(import('../constants.js'), async importOriginal => {
@@ -301,84 +302,121 @@ describe('clerkMiddleware(params)', () => {
     });
   });
 
-  describe('auth().redirectToSignIn()', () => {
-    it('redirects to sign-in url when redirectToSignIn is called and the request is a page request', async () => {
+  describe.each([
+    {
+      name: 'auth().redirectToSignIn()',
+      util: 'redirectToSignIn',
+      locationHeader: 'sign-in',
+    } as const,
+    {
+      name: 'auth().redirectToSignUp()',
+      util: 'redirectToSignUp',
+      locationHeader: 'sign-up',
+    } as const,
+  ])('$name', ({ util, locationHeader }) => {
+    it(`redirects to ${locationHeader} url when ${util} is called and the request is a page request`, async () => {
       const req = mockRequest({
         url: '/protected',
         headers: new Headers({ [constants.Headers.SecFetchDest]: 'document' }),
         appendDevBrowserCookie: true,
       });
 
       const resp = await clerkMiddleware(async auth => {
-        const { redirectToSignIn } = await auth();
-        redirectToSignIn();
+        (await auth())[util]();
       })(req, {} as NextFetchEvent);
 
       expect(resp?.status).toEqual(307);
-      expect(resp?.headers.get('location')).toContain('sign-in');
+      expect(resp?.headers.get('location')).toContain(locationHeader);
       expect((await clerkClient()).authenticateRequest).toBeCalled();
     });
 
-    it('redirects to sign-in url when redirectToSignIn is called with the correct returnBackUrl', async () => {
+    it(`redirects to ${locationHeader} url when redirectToSignIn is called with the correct returnBackUrl`, async () => {
       const req = mockRequest({
         url: '/protected',
         headers: new Headers({ [constants.Headers.SecFetchDest]: 'document' }),
         appendDevBrowserCookie: true,
       });
 
       const resp = await clerkMiddleware(async auth => {
-        const { redirectToSignIn } = await auth();
-        redirectToSignIn();
+        (await auth())[util]();
       })(req, {} as NextFetchEvent);
 
-      expect(resp?.status).toEqual(307);
       expect(resp?.status).toEqual(307);
       // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
       expect(new URL(resp!.headers.get('location')!).searchParams.get('redirect_url')).toContain('/protected');
       expect((await clerkClient()).authenticateRequest).toBeCalled();
     });
 
-    it('redirects to sign-in url with redirect_url set to the  provided returnBackUrl param', async () => {
+    it(`redirects to ${locationHeader} url with redirect_url set to the provided returnBackUrl param`, async () => {
       const req = mockRequest({
         url: '/protected',
         headers: new Headers({ [constants.Headers.SecFetchDest]: 'document' }),
         appendDevBrowserCookie: true,
       });
 
       const resp = await clerkMiddleware(async auth => {
-        const { redirectToSignIn } = await auth();
-        redirectToSignIn({ returnBackUrl: 'https://www.clerk.com/hello' });
+        (await auth())[util]({ returnBackUrl: 'https://www.clerk.com/hello' });
       })(req, {} as NextFetchEvent);
 
       expect(resp?.status).toEqual(307);
-      expect(resp?.headers.get('location')).toContain('sign-in');
+      expect(resp?.headers.get('location')).toContain(locationHeader);
       // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
       expect(new URL(resp!.headers.get('location')!).searchParams.get('redirect_url')).toEqual(
         'https://www.clerk.com/hello',
       );
       expect((await clerkClient()).authenticateRequest).toBeCalled();
     });
 
-    it('redirects to sign-in url without a redirect_url when returnBackUrl is null', async () => {
+    it(`redirects to ${locationHeader} url without a redirect_url when returnBackUrl is null`, async () => {
       const req = mockRequest({
         url: '/protected',
         headers: new Headers({ [constants.Headers.SecFetchDest]: 'document' }),
         appendDevBrowserCookie: true,
       });
 
       const resp = await clerkMiddleware(async auth => {
-        const { redirectToSignIn } = await auth();
-        redirectToSignIn({ returnBackUrl: null });
+        (await auth())[util]({ returnBackUrl: null });
       })(req, {} as NextFetchEvent);
 
       expect(resp?.status).toEqual(307);
-      expect(resp?.headers.get('location')).toContain('sign-in');
+      expect(resp?.headers.get('location')).toContain(locationHeader);
       // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
       expect(new URL(resp!.headers.get('location')!).searchParams.get('redirect_url')).toBeNull();
       expect((await clerkClient()).authenticateRequest).toBeCalled();
     });
   });
 
+  describe('auth().redirectToSignUp()', () => {
+    it('to support signInOrUp', async () => {
+      vi.mocked(clerkClient).mockResolvedValue({
+        authenticateRequest: vi.fn().mockResolvedValue({
+          toAuth: () => ({
+            debug: (d: any) => d,
+          }),
+          headers: new Headers(),
+          publishableKey,
+          signInUrl: '/hello',
+        }),
+        // @ts-expect-error - mock
+        telemetry: { record: vi.fn() },
+      });
+
+      const req = mockRequest({
+        url: '/protected',
+        headers: new Headers({ [constants.Headers.SecFetchDest]: 'document' }),
+        appendDevBrowserCookie: true,
+      });
+
+      const resp = await clerkMiddleware(async auth => {
+        (await auth()).redirectToSignUp();
+      })(req, {} as NextFetchEvent);
+
+      expect(resp?.status).toEqual(307);
+      expect(resp?.headers.get('location')).toContain(`/hello/create`);
+      expect((await clerkClient()).authenticateRequest).toBeCalled();
+    });
+  });
+
   describe('auth.protect()', () => {
     it('redirects to sign-in url when protect is called, the user is signed out and the request is a page request', async () => {
       const req = mockRequest({
diff --git a/packages/nextjs/src/server/clerkMiddleware.ts b/packages/nextjs/src/server/clerkMiddleware.ts
@@ -19,8 +19,10 @@ import {
   isNextjsNotFoundError,
   isNextjsRedirectError,
   isRedirectToSignInError,
+  isRedirectToSignUpError,
   nextjsRedirectError,
   redirectToSignInError,
+  redirectToSignUpError,
 } from './nextErrors';
 import type { AuthProtect } from './protect';
 import { createProtect } from './protect';
@@ -35,6 +37,7 @@ import {
 
 export type ClerkMiddlewareAuthObject = AuthObject & {
   redirectToSignIn: RedirectFun<Response>;
+  redirectToSignUp: RedirectFun<Response>;
 };
 
 export interface ClerkMiddlewareAuth {
@@ -185,9 +188,13 @@ export const clerkMiddleware = ((...args: unknown[]): NextMiddleware | NextMiddl
       logger.debug('auth', () => ({ auth: authObject, debug: authObject.debug() }));
 
       const redirectToSignIn = createMiddlewareRedirectToSignIn(clerkRequest);
+      const redirectToSignUp = createMiddlewareRedirectToSignUp(clerkRequest);
       const protect = await createMiddlewareProtect(clerkRequest, authObject, redirectToSignIn);
 
-      const authObjWithMethods: ClerkMiddlewareAuthObject = Object.assign(authObject, { redirectToSignIn });
+      const authObjWithMethods: ClerkMiddlewareAuthObject = Object.assign(authObject, {
+        redirectToSignIn,
+        redirectToSignUp,
+      });
       const authHandler = () => Promise.resolve(authObjWithMethods);
       authHandler.protect = protect;
 
@@ -348,6 +355,15 @@ const createMiddlewareRedirectToSignIn = (
   };
 };
 
+const createMiddlewareRedirectToSignUp = (
+  clerkRequest: ClerkRequest,
+): ClerkMiddlewareAuthObject['redirectToSignUp'] => {
+  return (opts = {}) => {
+    const url = clerkRequest.clerkUrl.toString();
+    redirectToSignUpError(url, opts.returnBackUrl);
+  };
+};
+
 const createMiddlewareProtect = (
   clerkRequest: ClerkRequest,
   authObject: AuthObject,
@@ -390,15 +406,21 @@ const handleControlFlowErrors = (
     );
   }
 
-  if (isRedirectToSignInError(e)) {
-    return createRedirect({
+  const isRedirectToSignIn = isRedirectToSignInError(e);
+  const isRedirectToSignUp = isRedirectToSignUpError(e);
+
+  if (isRedirectToSignIn || isRedirectToSignUp) {
+    const redirect = createRedirect({
       redirectAdapter,
       baseUrl: clerkRequest.clerkUrl,
       signInUrl: requestState.signInUrl,
       signUpUrl: requestState.signUpUrl,
       publishableKey: requestState.publishableKey,
       sessionStatus: requestState.toAuth()?.sessionStatus,
-    }).redirectToSignIn({ returnBackUrl: e.returnBackUrl });
+    });
+
+    const { returnBackUrl } = e;
+    return redirect[isRedirectToSignIn ? 'redirectToSignIn' : 'redirectToSignUp']({ returnBackUrl });
   }
 
   if (isNextjsRedirectError(e)) {
diff --git a/packages/nextjs/src/server/nextErrors.ts b/packages/nextjs/src/server/nextErrors.ts
