feat: add redirectToSignUp() to ClerkMiddlewareAuthObject

.changeset/giant-items-glow.md

@@ -0,0 +1,18 @@
+---
+'@clerk/nextjs': patch
+---
+
+- Introduce `auth().redirectToSignUp()` that can be used in API routes and pages, eg
+```ts
+import { auth } from '@clerk/nextjs/server';
+
+export const Layout = ({ children }) => {
+ const { userId } = auth();
+
+ if (!userId) {
+ return auth().redirectToSignUp();
+ }
+
+ return <>{children}</>;
+};
+```

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 {
@@ -104,7 +114,28 @@ export const auth: AuthFn = async () => {
  });
  };
 
- return Object.assign(authObject, { redirectToSignIn });
+ const redirectToSignUp: RedirectFun<never> = (opts = {}) => {
+ 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,
+ }).redirectToSignUp({
+ returnBackUrl: opts.returnBackUrl === null ? '' : opts.returnBackUrl || clerkUrl?.toString(),
+ });
+ };
+
+ return Object.assign(authObject, { redirectToSignIn, redirectToSignUp });
 };
 
 auth.protect = async (...args: any[]) => {

packages/nextjs/src/server/__tests__/clerkMiddleware.test.ts

@@ -379,6 +379,81 @@ describe('clerkMiddleware(params)', () => {
  });
  });
 
+ describe('auth().redirectToSignUp()', () => {
+ it('redirects to sign-up url when redirectToSignUp 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 { redirectToSignUp } = await auth();
+ redirectToSignUp();
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ expect((await clerkClient()).authenticateRequest).toBeCalled();
+ });
+
+ it('redirects to sign-up url when redirectToSignUp 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 { redirectToSignUp } = await auth();
+ redirectToSignUp();
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ expect(new URL(resp!.headers.get('location')!).searchParams.get('redirect_url')).toContain('/protected');
+ expect((await clerkClient()).authenticateRequest).toBeCalled();
+ });
+
+ it('redirects to sign-up 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 { redirectToSignUp } = await auth();
+ redirectToSignUp({ returnBackUrl: 'https://www.clerk.com/hello' });
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ 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-up 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 { redirectToSignUp } = await auth();
+ redirectToSignUp({ returnBackUrl: null });
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ expect(new URL(resp!.headers.get('location')!).searchParams.get('redirect_url')).toBeNull();
+ 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({

packages/nextjs/src/server/clerkMiddleware.ts

@@ -18,8 +18,10 @@ import {
  isNextjsNotFoundError,
  isNextjsRedirectError,
  isRedirectToSignInError,
+ isRedirectToSignUpError,
  nextjsRedirectError,
  redirectToSignInError,
+ redirectToSignUpError,
 } from './nextErrors';
 import type { AuthProtect } from './protect';
 import { createProtect } from './protect';
@@ -34,6 +36,7 @@ import {
 
 export type ClerkMiddlewareAuthObject = AuthObject & {
  redirectToSignIn: RedirectFun<Response>;
+ redirectToSignUp: RedirectFun<Response>;
 };
 
 export interface ClerkMiddlewareAuth {
@@ -172,9 +175,13 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
  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;
 
@@ -311,6 +318,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,
@@ -363,6 +379,16 @@ const handleControlFlowErrors = (
  }).redirectToSignIn({ returnBackUrl: e.returnBackUrl });
  }
 
+ if (isRedirectToSignUpError(e)) {
+ return createRedirect({
+ redirectAdapter,
+ baseUrl: clerkRequest.clerkUrl,
+ signInUrl: requestState.signInUrl,
+ signUpUrl: requestState.signUpUrl,
+ publishableKey: requestState.publishableKey,
+ }).redirectToSignUp({ returnBackUrl: e.returnBackUrl });
+ }
+
  if (isNextjsRedirectError(e)) {
  return redirectAdapter(e.redirectUrl);
  }

packages/nextjs/src/server/nextErrors.ts

@@ -4,6 +4,7 @@
 const CONTROL_FLOW_ERROR = {
  REDIRECT_TO_URL: 'CLERK_PROTECT_REDIRECT_TO_URL',
  REDIRECT_TO_SIGN_IN: 'CLERK_PROTECT_REDIRECT_TO_SIGN_IN',
+ REDIRECT_TO_SIGN_UP: 'CLERK_PROTECT_REDIRECT_TO_SIGN_UP',
 };
 
 /**
@@ -99,6 +100,13 @@ function redirectToSignInError(url: string, returnBackUrl?: string | URL | null)
  });
 }
 
+function redirectToSignUpError(url: string, returnBackUrl?: string | URL | null): never {
+ nextjsRedirectError(url, {
+ clerk_digest: CONTROL_FLOW_ERROR.REDIRECT_TO_SIGN_UP,
+ returnBackUrl: returnBackUrl === null ? '' : returnBackUrl || url,
+ });
+}
+
 /**
  * Checks an error to determine if it's an error generated by the
  * `redirect(url)` helper.
@@ -135,11 +143,21 @@ function isRedirectToSignInError(error: unknown): error is RedirectError<{ retur
  return false;
 }
 
+function isRedirectToSignUpError(error: unknown): error is RedirectError<{ returnBackUrl: string | URL }> {
+ if (isNextjsRedirectError(error) && 'clerk_digest' in error) {
+ return error.clerk_digest === CONTROL_FLOW_ERROR.REDIRECT_TO_SIGN_UP;
+ }
+
+ return false;
+}
+
 export {
  isNextjsNotFoundError,
  isLegacyNextjsNotFoundError,
  redirectToSignInError,
+ redirectToSignUpError,
  nextjsRedirectError,
  isNextjsRedirectError,
  isRedirectToSignInError,
+ isRedirectToSignUpError,
 };

.changeset/giant-items-glow.md

@@ -0,0 +1,18 @@
+---
+'@clerk/nextjs': patch
+---
+
+- Introduce `auth().redirectToSignUp()` that can be used in API routes and pages, eg
+```ts
+import { auth } from '@clerk/nextjs/server';
+
+export const Layout = ({ children }) => {
+ const { userId } = auth();
+
+ if (!userId) {
+ return auth().redirectToSignUp();
+ }
+
+ return <>{children}</>;
+};
+```

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 {
@@ -104,7 +114,28 @@ export const auth: AuthFn = async () => {
  });
  };
 
- return Object.assign(authObject, { redirectToSignIn });
+ const redirectToSignUp: RedirectFun<never> = (opts = {}) => {
+ 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,
+ }).redirectToSignUp({
+ returnBackUrl: opts.returnBackUrl === null ? '' : opts.returnBackUrl || clerkUrl?.toString(),
+ });
+ };
+
+ return Object.assign(authObject, { redirectToSignIn, redirectToSignUp });
 };
 
 auth.protect = async (...args: any[]) => {

packages/nextjs/src/server/__tests__/clerkMiddleware.test.ts

@@ -379,6 +379,81 @@ describe('clerkMiddleware(params)', () => {
  });
  });
 
+ describe('auth().redirectToSignUp()', () => {
+ it('redirects to sign-up url when redirectToSignUp 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 { redirectToSignUp } = await auth();
+ redirectToSignUp();
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ expect((await clerkClient()).authenticateRequest).toBeCalled();
+ });
+
+ it('redirects to sign-up url when redirectToSignUp 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 { redirectToSignUp } = await auth();
+ redirectToSignUp();
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ expect(new URL(resp!.headers.get('location')!).searchParams.get('redirect_url')).toContain('/protected');
+ expect((await clerkClient()).authenticateRequest).toBeCalled();
+ });
+
+ it('redirects to sign-up 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 { redirectToSignUp } = await auth();
+ redirectToSignUp({ returnBackUrl: 'https://www.clerk.com/hello' });
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ 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-up 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 { redirectToSignUp } = await auth();
+ redirectToSignUp({ returnBackUrl: null });
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ expect(new URL(resp!.headers.get('location')!).searchParams.get('redirect_url')).toBeNull();
+ 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({

packages/nextjs/src/server/clerkMiddleware.ts

@@ -18,8 +18,10 @@ import {
  isNextjsNotFoundError,
  isNextjsRedirectError,
  isRedirectToSignInError,
+ isRedirectToSignUpError,
  nextjsRedirectError,
  redirectToSignInError,
+ redirectToSignUpError,
 } from './nextErrors';
 import type { AuthProtect } from './protect';
 import { createProtect } from './protect';
@@ -34,6 +36,7 @@ import {
 
 export type ClerkMiddlewareAuthObject = AuthObject & {
  redirectToSignIn: RedirectFun<Response>;
+ redirectToSignUp: RedirectFun<Response>;
 };
 
 export interface ClerkMiddlewareAuth {
@@ -172,9 +175,13 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
  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;
 
@@ -311,6 +318,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,
@@ -363,6 +379,16 @@ const handleControlFlowErrors = (
  }).redirectToSignIn({ returnBackUrl: e.returnBackUrl });
  }
 
+ if (isRedirectToSignUpError(e)) {
+ return createRedirect({
+ redirectAdapter,
+ baseUrl: clerkRequest.clerkUrl,
+ signInUrl: requestState.signInUrl,
+ signUpUrl: requestState.signUpUrl,
+ publishableKey: requestState.publishableKey,
+ }).redirectToSignUp({ returnBackUrl: e.returnBackUrl });
+ }
+
  if (isNextjsRedirectError(e)) {
  return redirectAdapter(e.redirectUrl);
  }

packages/nextjs/src/server/nextErrors.ts

@@ -4,6 +4,7 @@
 const CONTROL_FLOW_ERROR = {
  REDIRECT_TO_URL: 'CLERK_PROTECT_REDIRECT_TO_URL',
  REDIRECT_TO_SIGN_IN: 'CLERK_PROTECT_REDIRECT_TO_SIGN_IN',
+ REDIRECT_TO_SIGN_UP: 'CLERK_PROTECT_REDIRECT_TO_SIGN_UP',
 };
 
 /**
@@ -99,6 +100,13 @@ function redirectToSignInError(url: string, returnBackUrl?: string | URL | null)
  });
 }
 
+function redirectToSignUpError(url: string, returnBackUrl?: string | URL | null): never {
+ nextjsRedirectError(url, {
+ clerk_digest: CONTROL_FLOW_ERROR.REDIRECT_TO_SIGN_UP,
+ returnBackUrl: returnBackUrl === null ? '' : returnBackUrl || url,
+ });
+}
+
 /**
  * Checks an error to determine if it's an error generated by the
  * `redirect(url)` helper.
@@ -135,11 +143,21 @@ function isRedirectToSignInError(error: unknown): error is RedirectError<{ retur
  return false;
 }
 
+function isRedirectToSignUpError(error: unknown): error is RedirectError<{ returnBackUrl: string | URL }> {
+ if (isNextjsRedirectError(error) && 'clerk_digest' in error) {
+ return error.clerk_digest === CONTROL_FLOW_ERROR.REDIRECT_TO_SIGN_UP;
+ }
+
+ return false;
+}
+
 export {
  isNextjsNotFoundError,
  isLegacyNextjsNotFoundError,
  redirectToSignInError,
+ redirectToSignUpError,
  nextjsRedirectError,
  isNextjsRedirectError,
  isRedirectToSignInError,
+ isRedirectToSignUpError,
 };

.changeset/giant-items-glow.md

@@ -0,0 +1,18 @@
+---
+'@clerk/nextjs': patch
+---
+
+- Introduce `auth().redirectToSignUp()` that can be used in API routes and pages, eg
+```ts
+import { auth } from '@clerk/nextjs/server';
+
+export const Layout = ({ children }) => {
+ const { userId } = auth();
+
+ if (!userId) {
+ return auth().redirectToSignUp();
+ }
+
+ return <>{children}</>;
+};
+```

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 {
@@ -104,7 +114,28 @@ export const auth: AuthFn = async () => {
  });
  };
 
- return Object.assign(authObject, { redirectToSignIn });
+ const redirectToSignUp: RedirectFun<never> = (opts = {}) => {
+ 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,
+ }).redirectToSignUp({
+ returnBackUrl: opts.returnBackUrl === null ? '' : opts.returnBackUrl || clerkUrl?.toString(),
+ });
+ };
+
+ return Object.assign(authObject, { redirectToSignIn, redirectToSignUp });
 };
 
 auth.protect = async (...args: any[]) => {

packages/nextjs/src/server/__tests__/clerkMiddleware.test.ts

@@ -379,6 +379,81 @@ describe('clerkMiddleware(params)', () => {
  });
  });
 
+ describe('auth().redirectToSignUp()', () => {
+ it('redirects to sign-up url when redirectToSignUp 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 { redirectToSignUp } = await auth();
+ redirectToSignUp();
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ expect((await clerkClient()).authenticateRequest).toBeCalled();
+ });
+
+ it('redirects to sign-up url when redirectToSignUp 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 { redirectToSignUp } = await auth();
+ redirectToSignUp();
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ expect(new URL(resp!.headers.get('location')!).searchParams.get('redirect_url')).toContain('/protected');
+ expect((await clerkClient()).authenticateRequest).toBeCalled();
+ });
+
+ it('redirects to sign-up 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 { redirectToSignUp } = await auth();
+ redirectToSignUp({ returnBackUrl: 'https://www.clerk.com/hello' });
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ 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-up 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 { redirectToSignUp } = await auth();
+ redirectToSignUp({ returnBackUrl: null });
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ expect(new URL(resp!.headers.get('location')!).searchParams.get('redirect_url')).toBeNull();
+ 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({

packages/nextjs/src/server/clerkMiddleware.ts

@@ -18,8 +18,10 @@ import {
  isNextjsNotFoundError,
  isNextjsRedirectError,
  isRedirectToSignInError,
+ isRedirectToSignUpError,
  nextjsRedirectError,
  redirectToSignInError,
+ redirectToSignUpError,
 } from './nextErrors';
 import type { AuthProtect } from './protect';
 import { createProtect } from './protect';
@@ -34,6 +36,7 @@ import {
 
 export type ClerkMiddlewareAuthObject = AuthObject & {
  redirectToSignIn: RedirectFun<Response>;
+ redirectToSignUp: RedirectFun<Response>;
 };
 
 export interface ClerkMiddlewareAuth {
@@ -172,9 +175,13 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
  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;
 
@@ -311,6 +318,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,
@@ -363,6 +379,16 @@ const handleControlFlowErrors = (
  }).redirectToSignIn({ returnBackUrl: e.returnBackUrl });
  }
 
+ if (isRedirectToSignUpError(e)) {
+ return createRedirect({
+ redirectAdapter,
+ baseUrl: clerkRequest.clerkUrl,
+ signInUrl: requestState.signInUrl,
+ signUpUrl: requestState.signUpUrl,
+ publishableKey: requestState.publishableKey,
+ }).redirectToSignUp({ returnBackUrl: e.returnBackUrl });
+ }
+
  if (isNextjsRedirectError(e)) {
  return redirectAdapter(e.redirectUrl);
  }

packages/nextjs/src/server/nextErrors.ts

@@ -4,6 +4,7 @@
 const CONTROL_FLOW_ERROR = {
  REDIRECT_TO_URL: 'CLERK_PROTECT_REDIRECT_TO_URL',
  REDIRECT_TO_SIGN_IN: 'CLERK_PROTECT_REDIRECT_TO_SIGN_IN',
+ REDIRECT_TO_SIGN_UP: 'CLERK_PROTECT_REDIRECT_TO_SIGN_UP',
 };
 
 /**
@@ -99,6 +100,13 @@ function redirectToSignInError(url: string, returnBackUrl?: string | URL | null)
  });
 }
 
+function redirectToSignUpError(url: string, returnBackUrl?: string | URL | null): never {
+ nextjsRedirectError(url, {
+ clerk_digest: CONTROL_FLOW_ERROR.REDIRECT_TO_SIGN_UP,
+ returnBackUrl: returnBackUrl === null ? '' : returnBackUrl || url,
+ });
+}
+
 /**
  * Checks an error to determine if it's an error generated by the
  * `redirect(url)` helper.
@@ -135,11 +143,21 @@ function isRedirectToSignInError(error: unknown): error is RedirectError<{ retur
  return false;
 }
 
+function isRedirectToSignUpError(error: unknown): error is RedirectError<{ returnBackUrl: string | URL }> {
+ if (isNextjsRedirectError(error) && 'clerk_digest' in error) {
+ return error.clerk_digest === CONTROL_FLOW_ERROR.REDIRECT_TO_SIGN_UP;
+ }
+
+ return false;
+}
+
 export {
  isNextjsNotFoundError,
  isLegacyNextjsNotFoundError,
  redirectToSignInError,
+ redirectToSignUpError,
  nextjsRedirectError,
  isNextjsRedirectError,
  isRedirectToSignInError,
+ isRedirectToSignUpError,
 };

.changeset/giant-items-glow.md

@@ -0,0 +1,18 @@
+---
+'@clerk/nextjs': patch
+---
+
+- Introduce `auth().redirectToSignUp()` that can be used in API routes and pages, eg
+```ts
+import { auth } from '@clerk/nextjs/server';
+
+export const Layout = ({ children }) => {
+ const { userId } = auth();
+
+ if (!userId) {
+ return auth().redirectToSignUp();
+ }
+
+ return <>{children}</>;
+};
+```

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 {
@@ -104,7 +114,28 @@ export const auth: AuthFn = async () => {
  });
  };
 
- return Object.assign(authObject, { redirectToSignIn });
+ const redirectToSignUp: RedirectFun<never> = (opts = {}) => {
+ 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,
+ }).redirectToSignUp({
+ returnBackUrl: opts.returnBackUrl === null ? '' : opts.returnBackUrl || clerkUrl?.toString(),
+ });
+ };
+
+ return Object.assign(authObject, { redirectToSignIn, redirectToSignUp });
 };
 
 auth.protect = async (...args: any[]) => {

packages/nextjs/src/server/__tests__/clerkMiddleware.test.ts

@@ -379,6 +379,81 @@ describe('clerkMiddleware(params)', () => {
  });
  });
 
+ describe('auth().redirectToSignUp()', () => {
+ it('redirects to sign-up url when redirectToSignUp 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 { redirectToSignUp } = await auth();
+ redirectToSignUp();
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ expect((await clerkClient()).authenticateRequest).toBeCalled();
+ });
+
+ it('redirects to sign-up url when redirectToSignUp 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 { redirectToSignUp } = await auth();
+ redirectToSignUp();
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ expect(new URL(resp!.headers.get('location')!).searchParams.get('redirect_url')).toContain('/protected');
+ expect((await clerkClient()).authenticateRequest).toBeCalled();
+ });
+
+ it('redirects to sign-up 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 { redirectToSignUp } = await auth();
+ redirectToSignUp({ returnBackUrl: 'https://www.clerk.com/hello' });
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ 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-up 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 { redirectToSignUp } = await auth();
+ redirectToSignUp({ returnBackUrl: null });
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ expect(new URL(resp!.headers.get('location')!).searchParams.get('redirect_url')).toBeNull();
+ 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({

packages/nextjs/src/server/clerkMiddleware.ts

@@ -18,8 +18,10 @@ import {
  isNextjsNotFoundError,
  isNextjsRedirectError,
  isRedirectToSignInError,
+ isRedirectToSignUpError,
  nextjsRedirectError,
  redirectToSignInError,
+ redirectToSignUpError,
 } from './nextErrors';
 import type { AuthProtect } from './protect';
 import { createProtect } from './protect';
@@ -34,6 +36,7 @@ import {
 
 export type ClerkMiddlewareAuthObject = AuthObject & {
  redirectToSignIn: RedirectFun<Response>;
+ redirectToSignUp: RedirectFun<Response>;
 };
 
 export interface ClerkMiddlewareAuth {
@@ -172,9 +175,13 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
  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;
 
@@ -311,6 +318,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,
@@ -363,6 +379,16 @@ const handleControlFlowErrors = (
  }).redirectToSignIn({ returnBackUrl: e.returnBackUrl });
  }
 
+ if (isRedirectToSignUpError(e)) {
+ return createRedirect({
+ redirectAdapter,
+ baseUrl: clerkRequest.clerkUrl,
+ signInUrl: requestState.signInUrl,
+ signUpUrl: requestState.signUpUrl,
+ publishableKey: requestState.publishableKey,
+ }).redirectToSignUp({ returnBackUrl: e.returnBackUrl });
+ }
+
  if (isNextjsRedirectError(e)) {
  return redirectAdapter(e.redirectUrl);
  }

packages/nextjs/src/server/nextErrors.ts

@@ -4,6 +4,7 @@
 const CONTROL_FLOW_ERROR = {
  REDIRECT_TO_URL: 'CLERK_PROTECT_REDIRECT_TO_URL',
  REDIRECT_TO_SIGN_IN: 'CLERK_PROTECT_REDIRECT_TO_SIGN_IN',
+ REDIRECT_TO_SIGN_UP: 'CLERK_PROTECT_REDIRECT_TO_SIGN_UP',
 };
 
 /**
@@ -99,6 +100,13 @@ function redirectToSignInError(url: string, returnBackUrl?: string | URL | null)
  });
 }
 
+function redirectToSignUpError(url: string, returnBackUrl?: string | URL | null): never {
+ nextjsRedirectError(url, {
+ clerk_digest: CONTROL_FLOW_ERROR.REDIRECT_TO_SIGN_UP,
+ returnBackUrl: returnBackUrl === null ? '' : returnBackUrl || url,
+ });
+}
+
 /**
  * Checks an error to determine if it's an error generated by the
  * `redirect(url)` helper.
@@ -135,11 +143,21 @@ function isRedirectToSignInError(error: unknown): error is RedirectError<{ retur
  return false;
 }
 
+function isRedirectToSignUpError(error: unknown): error is RedirectError<{ returnBackUrl: string | URL }> {
+ if (isNextjsRedirectError(error) && 'clerk_digest' in error) {
+ return error.clerk_digest === CONTROL_FLOW_ERROR.REDIRECT_TO_SIGN_UP;
+ }
+
+ return false;
+}
+
 export {
  isNextjsNotFoundError,
  isLegacyNextjsNotFoundError,
  redirectToSignInError,
+ redirectToSignUpError,
  nextjsRedirectError,
  isNextjsRedirectError,
  isRedirectToSignInError,
+ isRedirectToSignUpError,
 };

.changeset/giant-items-glow.md

@@ -0,0 +1,18 @@
+---
+'@clerk/nextjs': patch
+---
+
+- Introduce `auth().redirectToSignUp()` that can be used in API routes and pages, eg
+```ts
+import { auth } from '@clerk/nextjs/server';
+
+export const Layout = ({ children }) => {
+ const { userId } = auth();
+
+ if (!userId) {
+ return auth().redirectToSignUp();
+ }
+
+ return <>{children}</>;
+};
+```

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 {
@@ -104,7 +114,28 @@ export const auth: AuthFn = async () => {
  });
  };
 
- return Object.assign(authObject, { redirectToSignIn });
+ const redirectToSignUp: RedirectFun<never> = (opts = {}) => {
+ 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,
+ }).redirectToSignUp({
+ returnBackUrl: opts.returnBackUrl === null ? '' : opts.returnBackUrl || clerkUrl?.toString(),
+ });
+ };
+
+ return Object.assign(authObject, { redirectToSignIn, redirectToSignUp });
 };
 
 auth.protect = async (...args: any[]) => {

packages/nextjs/src/server/__tests__/clerkMiddleware.test.ts

@@ -379,6 +379,81 @@ describe('clerkMiddleware(params)', () => {
  });
  });
 
+ describe('auth().redirectToSignUp()', () => {
+ it('redirects to sign-up url when redirectToSignUp 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 { redirectToSignUp } = await auth();
+ redirectToSignUp();
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ expect((await clerkClient()).authenticateRequest).toBeCalled();
+ });
+
+ it('redirects to sign-up url when redirectToSignUp 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 { redirectToSignUp } = await auth();
+ redirectToSignUp();
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ expect(new URL(resp!.headers.get('location')!).searchParams.get('redirect_url')).toContain('/protected');
+ expect((await clerkClient()).authenticateRequest).toBeCalled();
+ });
+
+ it('redirects to sign-up 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 { redirectToSignUp } = await auth();
+ redirectToSignUp({ returnBackUrl: 'https://www.clerk.com/hello' });
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ 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-up 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 { redirectToSignUp } = await auth();
+ redirectToSignUp({ returnBackUrl: null });
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ expect(new URL(resp!.headers.get('location')!).searchParams.get('redirect_url')).toBeNull();
+ 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({

packages/nextjs/src/server/clerkMiddleware.ts

@@ -18,8 +18,10 @@ import {
  isNextjsNotFoundError,
  isNextjsRedirectError,
  isRedirectToSignInError,
+ isRedirectToSignUpError,
  nextjsRedirectError,
  redirectToSignInError,
+ redirectToSignUpError,
 } from './nextErrors';
 import type { AuthProtect } from './protect';
 import { createProtect } from './protect';
@@ -34,6 +36,7 @@ import {
 
 export type ClerkMiddlewareAuthObject = AuthObject & {
  redirectToSignIn: RedirectFun<Response>;
+ redirectToSignUp: RedirectFun<Response>;
 };
 
 export interface ClerkMiddlewareAuth {
@@ -172,9 +175,13 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
  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;
 
@@ -311,6 +318,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,
@@ -363,6 +379,16 @@ const handleControlFlowErrors = (
  }).redirectToSignIn({ returnBackUrl: e.returnBackUrl });
  }
 
+ if (isRedirectToSignUpError(e)) {
+ return createRedirect({
+ redirectAdapter,
+ baseUrl: clerkRequest.clerkUrl,
+ signInUrl: requestState.signInUrl,
+ signUpUrl: requestState.signUpUrl,
+ publishableKey: requestState.publishableKey,
+ }).redirectToSignUp({ returnBackUrl: e.returnBackUrl });
+ }
+
  if (isNextjsRedirectError(e)) {
  return redirectAdapter(e.redirectUrl);
  }

packages/nextjs/src/server/nextErrors.ts

@@ -4,6 +4,7 @@
 const CONTROL_FLOW_ERROR = {
  REDIRECT_TO_URL: 'CLERK_PROTECT_REDIRECT_TO_URL',
  REDIRECT_TO_SIGN_IN: 'CLERK_PROTECT_REDIRECT_TO_SIGN_IN',
+ REDIRECT_TO_SIGN_UP: 'CLERK_PROTECT_REDIRECT_TO_SIGN_UP',
 };
 
 /**
@@ -99,6 +100,13 @@ function redirectToSignInError(url: string, returnBackUrl?: string | URL | null)
  });
 }
 
+function redirectToSignUpError(url: string, returnBackUrl?: string | URL | null): never {
+ nextjsRedirectError(url, {
+ clerk_digest: CONTROL_FLOW_ERROR.REDIRECT_TO_SIGN_UP,
+ returnBackUrl: returnBackUrl === null ? '' : returnBackUrl || url,
+ });
+}
+
 /**
  * Checks an error to determine if it's an error generated by the
  * `redirect(url)` helper.
@@ -135,11 +143,21 @@ function isRedirectToSignInError(error: unknown): error is RedirectError<{ retur
  return false;
 }
 
+function isRedirectToSignUpError(error: unknown): error is RedirectError<{ returnBackUrl: string | URL }> {
+ if (isNextjsRedirectError(error) && 'clerk_digest' in error) {
+ return error.clerk_digest === CONTROL_FLOW_ERROR.REDIRECT_TO_SIGN_UP;
+ }
+
+ return false;
+}
+
 export {
  isNextjsNotFoundError,
  isLegacyNextjsNotFoundError,
  redirectToSignInError,
+ redirectToSignUpError,
  nextjsRedirectError,
  isNextjsRedirectError,
  isRedirectToSignInError,
+ isRedirectToSignUpError,
 };

.changeset/giant-items-glow.md

@@ -0,0 +1,18 @@
+---
+'@clerk/nextjs': patch
+---
+
+- Introduce `auth().redirectToSignUp()` that can be used in API routes and pages, eg
+```ts
+import { auth } from '@clerk/nextjs/server';
+
+export const Layout = ({ children }) => {
+ const { userId } = auth();
+
+ if (!userId) {
+ return auth().redirectToSignUp();
+ }
+
+ return <>{children}</>;
+};
+```

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 {
@@ -104,7 +114,28 @@ export const auth: AuthFn = async () => {
  });
  };
 
- return Object.assign(authObject, { redirectToSignIn });
+ const redirectToSignUp: RedirectFun<never> = (opts = {}) => {
+ 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,
+ }).redirectToSignUp({
+ returnBackUrl: opts.returnBackUrl === null ? '' : opts.returnBackUrl || clerkUrl?.toString(),
+ });
+ };
+
+ return Object.assign(authObject, { redirectToSignIn, redirectToSignUp });
 };
 
 auth.protect = async (...args: any[]) => {

packages/nextjs/src/server/__tests__/clerkMiddleware.test.ts

@@ -379,6 +379,81 @@ describe('clerkMiddleware(params)', () => {
  });
  });
 
+ describe('auth().redirectToSignUp()', () => {
+ it('redirects to sign-up url when redirectToSignUp 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 { redirectToSignUp } = await auth();
+ redirectToSignUp();
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ expect((await clerkClient()).authenticateRequest).toBeCalled();
+ });
+
+ it('redirects to sign-up url when redirectToSignUp 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 { redirectToSignUp } = await auth();
+ redirectToSignUp();
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ expect(new URL(resp!.headers.get('location')!).searchParams.get('redirect_url')).toContain('/protected');
+ expect((await clerkClient()).authenticateRequest).toBeCalled();
+ });
+
+ it('redirects to sign-up 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 { redirectToSignUp } = await auth();
+ redirectToSignUp({ returnBackUrl: 'https://www.clerk.com/hello' });
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ 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-up 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 { redirectToSignUp } = await auth();
+ redirectToSignUp({ returnBackUrl: null });
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ expect(new URL(resp!.headers.get('location')!).searchParams.get('redirect_url')).toBeNull();
+ 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({

packages/nextjs/src/server/clerkMiddleware.ts

@@ -18,8 +18,10 @@ import {
  isNextjsNotFoundError,
  isNextjsRedirectError,
  isRedirectToSignInError,
+ isRedirectToSignUpError,
  nextjsRedirectError,
  redirectToSignInError,
+ redirectToSignUpError,
 } from './nextErrors';
 import type { AuthProtect } from './protect';
 import { createProtect } from './protect';
@@ -34,6 +36,7 @@ import {
 
 export type ClerkMiddlewareAuthObject = AuthObject & {
  redirectToSignIn: RedirectFun<Response>;
+ redirectToSignUp: RedirectFun<Response>;
 };
 
 export interface ClerkMiddlewareAuth {
@@ -172,9 +175,13 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
  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;
 
@@ -311,6 +318,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,
@@ -363,6 +379,16 @@ const handleControlFlowErrors = (
  }).redirectToSignIn({ returnBackUrl: e.returnBackUrl });
  }
 
+ if (isRedirectToSignUpError(e)) {
+ return createRedirect({
+ redirectAdapter,
+ baseUrl: clerkRequest.clerkUrl,
+ signInUrl: requestState.signInUrl,
+ signUpUrl: requestState.signUpUrl,
+ publishableKey: requestState.publishableKey,
+ }).redirectToSignUp({ returnBackUrl: e.returnBackUrl });
+ }
+
  if (isNextjsRedirectError(e)) {
  return redirectAdapter(e.redirectUrl);
  }

packages/nextjs/src/server/nextErrors.ts

@@ -4,6 +4,7 @@
 const CONTROL_FLOW_ERROR = {
  REDIRECT_TO_URL: 'CLERK_PROTECT_REDIRECT_TO_URL',
  REDIRECT_TO_SIGN_IN: 'CLERK_PROTECT_REDIRECT_TO_SIGN_IN',
+ REDIRECT_TO_SIGN_UP: 'CLERK_PROTECT_REDIRECT_TO_SIGN_UP',
 };
 
 /**
@@ -99,6 +100,13 @@ function redirectToSignInError(url: string, returnBackUrl?: string | URL | null)
  });
 }
 
+function redirectToSignUpError(url: string, returnBackUrl?: string | URL | null): never {
+ nextjsRedirectError(url, {
+ clerk_digest: CONTROL_FLOW_ERROR.REDIRECT_TO_SIGN_UP,
+ returnBackUrl: returnBackUrl === null ? '' : returnBackUrl || url,
+ });
+}
+
 /**
  * Checks an error to determine if it's an error generated by the
  * `redirect(url)` helper.
@@ -135,11 +143,21 @@ function isRedirectToSignInError(error: unknown): error is RedirectError<{ retur
  return false;
 }
 
+function isRedirectToSignUpError(error: unknown): error is RedirectError<{ returnBackUrl: string | URL }> {
+ if (isNextjsRedirectError(error) && 'clerk_digest' in error) {
+ return error.clerk_digest === CONTROL_FLOW_ERROR.REDIRECT_TO_SIGN_UP;
+ }
+
+ return false;
+}
+
 export {
  isNextjsNotFoundError,
  isLegacyNextjsNotFoundError,
  redirectToSignInError,
+ redirectToSignUpError,
  nextjsRedirectError,
  isNextjsRedirectError,
  isRedirectToSignInError,
+ isRedirectToSignUpError,
 };

.changeset/giant-items-glow.md

@@ -0,0 +1,18 @@
+---
+'@clerk/nextjs': patch
+---
+
+- Introduce `auth().redirectToSignUp()` that can be used in API routes and pages, eg
+```ts
+import { auth } from '@clerk/nextjs/server';
+
+export const Layout = ({ children }) => {
+ const { userId } = auth();
+
+ if (!userId) {
+ return auth().redirectToSignUp();
+ }
+
+ return <>{children}</>;
+};
+```

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 {
@@ -104,7 +114,28 @@ export const auth: AuthFn = async () => {
  });
  };
 
- return Object.assign(authObject, { redirectToSignIn });
+ const redirectToSignUp: RedirectFun<never> = (opts = {}) => {
+ 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,
+ }).redirectToSignUp({
+ returnBackUrl: opts.returnBackUrl === null ? '' : opts.returnBackUrl || clerkUrl?.toString(),
+ });
+ };
+
+ return Object.assign(authObject, { redirectToSignIn, redirectToSignUp });
 };
 
 auth.protect = async (...args: any[]) => {

packages/nextjs/src/server/__tests__/clerkMiddleware.test.ts

@@ -379,6 +379,81 @@ describe('clerkMiddleware(params)', () => {
  });
  });
 
+ describe('auth().redirectToSignUp()', () => {
+ it('redirects to sign-up url when redirectToSignUp 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 { redirectToSignUp } = await auth();
+ redirectToSignUp();
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ expect((await clerkClient()).authenticateRequest).toBeCalled();
+ });
+
+ it('redirects to sign-up url when redirectToSignUp 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 { redirectToSignUp } = await auth();
+ redirectToSignUp();
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ expect(new URL(resp!.headers.get('location')!).searchParams.get('redirect_url')).toContain('/protected');
+ expect((await clerkClient()).authenticateRequest).toBeCalled();
+ });
+
+ it('redirects to sign-up 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 { redirectToSignUp } = await auth();
+ redirectToSignUp({ returnBackUrl: 'https://www.clerk.com/hello' });
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ 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-up 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 { redirectToSignUp } = await auth();
+ redirectToSignUp({ returnBackUrl: null });
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ expect(new URL(resp!.headers.get('location')!).searchParams.get('redirect_url')).toBeNull();
+ 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({

packages/nextjs/src/server/clerkMiddleware.ts

@@ -18,8 +18,10 @@ import {
  isNextjsNotFoundError,
  isNextjsRedirectError,
  isRedirectToSignInError,
+ isRedirectToSignUpError,
  nextjsRedirectError,
  redirectToSignInError,
+ redirectToSignUpError,
 } from './nextErrors';
 import type { AuthProtect } from './protect';
 import { createProtect } from './protect';
@@ -34,6 +36,7 @@ import {
 
 export type ClerkMiddlewareAuthObject = AuthObject & {
  redirectToSignIn: RedirectFun<Response>;
+ redirectToSignUp: RedirectFun<Response>;
 };
 
 export interface ClerkMiddlewareAuth {
@@ -172,9 +175,13 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
  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;
 
@@ -311,6 +318,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,
@@ -363,6 +379,16 @@ const handleControlFlowErrors = (
  }).redirectToSignIn({ returnBackUrl: e.returnBackUrl });
  }
 
+ if (isRedirectToSignUpError(e)) {
+ return createRedirect({
+ redirectAdapter,
+ baseUrl: clerkRequest.clerkUrl,
+ signInUrl: requestState.signInUrl,
+ signUpUrl: requestState.signUpUrl,
+ publishableKey: requestState.publishableKey,
+ }).redirectToSignUp({ returnBackUrl: e.returnBackUrl });
+ }
+
  if (isNextjsRedirectError(e)) {
  return redirectAdapter(e.redirectUrl);
  }

packages/nextjs/src/server/nextErrors.ts

@@ -4,6 +4,7 @@
 const CONTROL_FLOW_ERROR = {
  REDIRECT_TO_URL: 'CLERK_PROTECT_REDIRECT_TO_URL',
  REDIRECT_TO_SIGN_IN: 'CLERK_PROTECT_REDIRECT_TO_SIGN_IN',
+ REDIRECT_TO_SIGN_UP: 'CLERK_PROTECT_REDIRECT_TO_SIGN_UP',
 };
 
 /**
@@ -99,6 +100,13 @@ function redirectToSignInError(url: string, returnBackUrl?: string | URL | null)
  });
 }
 
+function redirectToSignUpError(url: string, returnBackUrl?: string | URL | null): never {
+ nextjsRedirectError(url, {
+ clerk_digest: CONTROL_FLOW_ERROR.REDIRECT_TO_SIGN_UP,
+ returnBackUrl: returnBackUrl === null ? '' : returnBackUrl || url,
+ });
+}
+
 /**
  * Checks an error to determine if it's an error generated by the
  * `redirect(url)` helper.
@@ -135,11 +143,21 @@ function isRedirectToSignInError(error: unknown): error is RedirectError<{ retur
  return false;
 }
 
+function isRedirectToSignUpError(error: unknown): error is RedirectError<{ returnBackUrl: string | URL }> {
+ if (isNextjsRedirectError(error) && 'clerk_digest' in error) {
+ return error.clerk_digest === CONTROL_FLOW_ERROR.REDIRECT_TO_SIGN_UP;
+ }
+
+ return false;
+}
+
 export {
  isNextjsNotFoundError,
  isLegacyNextjsNotFoundError,
  redirectToSignInError,
+ redirectToSignUpError,
  nextjsRedirectError,
  isNextjsRedirectError,
  isRedirectToSignInError,
+ isRedirectToSignUpError,
 };

.changeset/giant-items-glow.md

@@ -0,0 +1,18 @@
+---
+'@clerk/nextjs': patch
+---
+
+- Introduce `auth().redirectToSignUp()` that can be used in API routes and pages, eg
+```ts
+import { auth } from '@clerk/nextjs/server';
+
+export const Layout = ({ children }) => {
+ const { userId } = auth();
+
+ if (!userId) {
+ return auth().redirectToSignUp();
+ }
+
+ return <>{children}</>;
+};
+```

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 {
@@ -104,7 +114,28 @@ export const auth: AuthFn = async () => {
  });
  };
 
- return Object.assign(authObject, { redirectToSignIn });
+ const redirectToSignUp: RedirectFun<never> = (opts = {}) => {
+ 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,
+ }).redirectToSignUp({
+ returnBackUrl: opts.returnBackUrl === null ? '' : opts.returnBackUrl || clerkUrl?.toString(),
+ });
+ };
+
+ return Object.assign(authObject, { redirectToSignIn, redirectToSignUp });
 };
 
 auth.protect = async (...args: any[]) => {

packages/nextjs/src/server/__tests__/clerkMiddleware.test.ts

@@ -379,6 +379,81 @@ describe('clerkMiddleware(params)', () => {
  });
  });
 
+ describe('auth().redirectToSignUp()', () => {
+ it('redirects to sign-up url when redirectToSignUp 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 { redirectToSignUp } = await auth();
+ redirectToSignUp();
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ expect((await clerkClient()).authenticateRequest).toBeCalled();
+ });
+
+ it('redirects to sign-up url when redirectToSignUp 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 { redirectToSignUp } = await auth();
+ redirectToSignUp();
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ expect(new URL(resp!.headers.get('location')!).searchParams.get('redirect_url')).toContain('/protected');
+ expect((await clerkClient()).authenticateRequest).toBeCalled();
+ });
+
+ it('redirects to sign-up 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 { redirectToSignUp } = await auth();
+ redirectToSignUp({ returnBackUrl: 'https://www.clerk.com/hello' });
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ 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-up 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 { redirectToSignUp } = await auth();
+ redirectToSignUp({ returnBackUrl: null });
+ })(req, {} as NextFetchEvent);
+
+ expect(resp?.status).toEqual(307);
+ expect(resp?.headers.get('location')).toContain('sign-up');
+ expect(new URL(resp!.headers.get('location')!).searchParams.get('redirect_url')).toBeNull();
+ 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({

packages/nextjs/src/server/clerkMiddleware.ts

@@ -18,8 +18,10 @@ import {
  isNextjsNotFoundError,
  isNextjsRedirectError,
  isRedirectToSignInError,
+ isRedirectToSignUpError,
  nextjsRedirectError,
  redirectToSignInError,
+ redirectToSignUpError,
 } from './nextErrors';
 import type { AuthProtect } from './protect';
 import { createProtect } from './protect';
@@ -34,6 +36,7 @@ import {
 
 export type ClerkMiddlewareAuthObject = AuthObject & {
  redirectToSignIn: RedirectFun<Response>;
+ redirectToSignUp: RedirectFun<Response>;
 };
 
 export interface ClerkMiddlewareAuth {
@@ -172,9 +175,13 @@ export const clerkMiddleware: ClerkMiddleware = (...args: unknown[]) => {
  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;
 
@@ -311,6 +318,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,
@@ -363,6 +379,16 @@ const handleControlFlowErrors = (
  }).redirectToSignIn({ returnBackUrl: e.returnBackUrl });
  }
 
+ if (isRedirectToSignUpError(e)) {
+ return createRedirect({
+ redirectAdapter,
+ baseUrl: clerkRequest.clerkUrl,
+ signInUrl: requestState.signInUrl,
+ signUpUrl: requestState.signUpUrl,
+ publishableKey: requestState.publishableKey,
+ }).redirectToSignUp({ returnBackUrl: e.returnBackUrl });
+ }
+
  if (isNextjsRedirectError(e)) {
  return redirectAdapter(e.redirectUrl);
  }

packages/nextjs/src/server/nextErrors.ts

@@ -4,6 +4,7 @@
 const CONTROL_FLOW_ERROR = {
  REDIRECT_TO_URL: 'CLERK_PROTECT_REDIRECT_TO_URL',
  REDIRECT_TO_SIGN_IN: 'CLERK_PROTECT_REDIRECT_TO_SIGN_IN',
+ REDIRECT_TO_SIGN_UP: 'CLERK_PROTECT_REDIRECT_TO_SIGN_UP',
 };
 
 /**
@@ -99,6 +100,13 @@ function redirectToSignInError(url: string, returnBackUrl?: string | URL | null)
  });
 }
 
+function redirectToSignUpError(url: string, returnBackUrl?: string | URL | null): never {
+ nextjsRedirectError(url, {
+ clerk_digest: CONTROL_FLOW_ERROR.REDIRECT_TO_SIGN_UP,
+ returnBackUrl: returnBackUrl === null ? '' : returnBackUrl || url,
+ });
+}
+
 /**
  * Checks an error to determine if it's an error generated by the
  * `redirect(url)` helper.
@@ -135,11 +143,21 @@ function isRedirectToSignInError(error: unknown): error is RedirectError<{ retur
  return false;
 }
 
+function isRedirectToSignUpError(error: unknown): error is RedirectError<{ returnBackUrl: string | URL }> {
+ if (isNextjsRedirectError(error) && 'clerk_digest' in error) {
+ return error.clerk_digest === CONTROL_FLOW_ERROR.REDIRECT_TO_SIGN_UP;
+ }
+
+ return false;
+}
+
 export {
  isNextjsNotFoundError,
  isLegacyNextjsNotFoundError,
  redirectToSignInError,
+ redirectToSignUpError,
  nextjsRedirectError,
  isNextjsRedirectError,
  isRedirectToSignInError,
+ isRedirectToSignUpError,
 };