feat(nextjs): Introduce clerkMiddleware

.changeset/funny-avocados-shout.md

@@ -0,0 +1,64 @@
+---
+'@clerk/nextjs': patch
+---
+
+Introduce the new `clerkMiddleware` helper to allow for more flexibility in how Clerk is integrated into your Next.js middleware. Example usage can be found below, for more details, For more details, please see the [clerkMiddleware](https://clerk.com/docs/references/nextjs/clerkMiddleware) documentation.
+The `clerkMiddleware` helper effectively replaces the older `authMiddleware` helper, which is now considered deprecated and will be removed in the next major release.
+
+### 1. Protect a route that requires authentication
+
+```js
+import { clerkMiddleware } from '@clerk/nextjs/server';
+
+export default clerkMiddleware(auth => {
+ const { userId } = auth().protect();
+ // userId is now available for use in your route handler
+ // for page requests, calling protect will automatically redirect the user to the sign-in URL if they are not authenticated
+ return NextResponse.next();
+});
+```
+
+
+### 2. Protect a route that requires specific permissions
+
+```js
+import { clerkMiddleware } from '@clerk/nextjs/server';
+
+export default clerkMiddleware(auth => {
+ const { userId } = auth().protect({ permission: 'org:domains:delete'});
+ // userId is now available for use in your route handler
+ // for page requests, calling protect will automatically throw a notFound error if the user does not have the required permissions
+ return NextResponse.next();
+});
+```
+
+### 2. Manually redirect to sign-in URL using the redirectToSignIn helper
+
+```js
+import { clerkMiddleware } from '@clerk/nextjs/server';
+
+export default clerkMiddleware(auth => {
+ // If you want more fine-grained control, you can always use the low-level redirectToSignIn helper
+ if(!auth().userId) {
+ return auth().redirectToSignIn();
+ }
+
+ return NextResponse.next();
+});
+```
+
+This commit also introduces the experimental `createRouteMatcher` helper, which can be used to create a route matcher that matches a route against the current request. This is useful for creating custom logic based on which routes you want to handle as protected or public.
+
+```js
+import { clerkMiddleware, experimental_createRouteMatcher } from '@clerk/nextjs/server';
+
+const isProtectedRoute = experimental_createRouteMatcher([/protected.*/]);
+
+export default clerkMiddleware((auth, request) => {
+ if(isProtectedRoute(request)) {
+ auth().protect();
+ }
+
+ return NextResponse.next();
+});
+```

integration/constants.ts

@@ -38,6 +38,7 @@ export const constants = {
  */
  E2E_APP_SK: process.env.E2E_APP_SK,
  E2E_APP_PK: process.env.E2E_APP_PK,
+ E2E_CLERK_API_URL: process.env.E2E_CLERK_API_URL,
  /**
  * The version of the dependency to use, controlled programmatically.
  */

integration/models/longRunningApplication.ts

@@ -43,7 +43,7 @@ export const longRunningApplication = (params: LongRunningApplicationParams) =>
  if (!stateFile.getLongRunningApps() || [port, serverUrl, pid, appDir, env].filter(Boolean).length === 0) {
  return;
  }
- const data = stateFile.getLongRunningApps()[id];
+ const data = stateFile.getLongRunningApps()[id] || {};
  port ||= data.port;
  serverUrl ||= data.serverUrl;
  pid ||= data.pid;

integration/scripts/setup.ts

@@ -1,15 +1,15 @@
-/* eslint-disable turbo/no-undeclared-env-vars */
 import { constants } from '../constants';
 
 export const parseEnvOptions = () => {
  const appIds = constants.E2E_APP_ID ? constants.E2E_APP_ID.split(',') : [];
  const appUrl = constants.E2E_APP_URL;
  const appPk = constants.E2E_APP_PK;
  const appSk = constants.E2E_APP_SK;
+ const clerkApiUrl = constants.E2E_CLERK_API_URL;
 
  if (appIds.length && appUrl) {
  throw new Error('E2E_APP_ID cannot be used with E2E_APP_URL');
  }
 
- return { appIds, appUrl, appPk, appSk };
+ return { appIds, appUrl, appPk, appSk, clerkApiUrl };
 };

integration/testUtils/testAgainstRunningApps.ts

@@ -20,7 +20,7 @@ type RunningAppsParams = {
  */
 const runningApps = (params: RunningAppsParams = {}) => {
  const withEnv = [params.withEnv].flat().filter(Boolean);
- const { appIds, appUrl, appPk, appSk } = parseEnvOptions();
+ const { appIds, appUrl, appPk, appSk, clerkApiUrl } = parseEnvOptions();
  if (appIds.length) {
  // if appIds are provided, we only return the apps with the given ids
  const filter = app => (withEnv.length ? withEnv.includes(app.env) : true);
@@ -31,6 +31,7 @@ const runningApps = (params: RunningAppsParams = {}) => {
  const env = environmentConfig()
  .setId('tempEnv')
  .setEnvVariable('private', 'CLERK_SECRET_KEY', appSk)
+ .setEnvVariable('private', 'CLERK_API_URL', clerkApiUrl)
  .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', appPk);
  return [longRunningApplication({ id: 'standalone', env, serverUrl: appUrl, config: applicationConfig() })];
 };

integration/tests/protect.test.ts

@@ -77,7 +77,7 @@ testAgainstRunningApps({ withEnv: [appConfigs.envs.withCustomRoles] })('authoriz
  await u.page.goToRelative('/settings/auth-has');
  await expect(u.page.getByText(/User is missing permissions/i)).toBeVisible();
  await u.page.goToRelative('/settings/auth-protect');
- await expect(u.page.getByText(/this page could not be found/i)).toBeVisible();
+ await u.po.signIn.waitForMounted();
  });
 
  test('Protect in RSCs and RCCs as `viewer`', async ({ page, context }) => {

packages/backend/src/constants.ts

@@ -42,6 +42,7 @@ const Headers = {
  Host: 'host',
  ContentType: 'content-type',
  SecFetchDest: 'sec-fetch-dest',
+ Location: 'location',
 } as const;
 
 const ContentTypes = {
@@ -58,3 +59,5 @@ export const constants = {
  ContentTypes,
  QueryParameters,
 } as const;
+
+export type Constants = typeof constants;

packages/backend/src/tokens/clerkRequest.ts

@@ -1,25 +1,14 @@
 import { parse as parseCookies } from 'cookie';
 
 import { constants } from '../constants';
-
-export type WithClerkUrl<T> = T & {
- /**
- * When a NextJs app is hosted on a platform different from Vercel
- * or inside a container (Netlify, Fly.io, AWS Amplify, docker etc),
- * req.url is always set to `localhost:3000` instead of the actual host of the app.
- *
- * The `authMiddleware` uses the value of the available req.headers in order to construct
- * and use the correct url internally. This url is then exposed as `experimental_clerkUrl`,
- * intended to be used within `beforeAuth` and `afterAuth` if needed.
- */
- clerkUrl: URL;
-};
+import type { ClerkUrl, WithClerkUrl } from './clerkUrl';
+import { createClerkUrl } from './clerkUrl';
 
 class ClerkRequest extends Request {
- readonly clerkUrl: URL;
+ readonly clerkUrl: ClerkUrl;
  readonly cookies: Map<string, string>;
 
- public constructor(req: Request) {
+ public constructor(req: ClerkRequest | Request) {
  super(req, req);
  this.clerkUrl = this.deriveUrlFromHeaders(req);
  this.cookies = this.parseCookies(req);
@@ -44,7 +33,7 @@ class ClerkRequest extends Request {
  const resolvedProtocol = this.getFirstValueFromHeader(forwardedProto) ?? protocol?.replace(/[:/]/, '');
  const origin = resolvedHost && resolvedProtocol ? `${resolvedProtocol}://${resolvedHost}` : initialUrl.origin;
 
- return new URL(initialUrl.pathname + initialUrl.search, origin);
+ return createClerkUrl(initialUrl.pathname + initialUrl.search, origin);
  }
 
  private getFirstValueFromHeader(value?: string | null) {
@@ -62,7 +51,7 @@ class ClerkRequest extends Request {
 }
 
 export const createClerkRequest = (...args: ConstructorParameters<typeof ClerkRequest>): ClerkRequest => {
- return new ClerkRequest(...args);
+ return args[0] instanceof ClerkRequest ? args[0] : new ClerkRequest(...args);
 };
 
 export type { ClerkRequest };

packages/backend/src/tokens/clerkUrl.ts

@@ -0,0 +1,24 @@
+class ClerkUrl extends URL {
+ public isCrossOrigin(other: URL | string) {
+ return this.origin !== new URL(other.toString()).origin;
+ }
+}
+
+export type WithClerkUrl<T> = T & {
+ /**
+ * When a NextJs app is hosted on a platform different from Vercel
+ * or inside a container (Netlify, Fly.io, AWS Amplify, docker etc),
+ * req.url is always set to `localhost:3000` instead of the actual host of the app.
+ *
+ * The `authMiddleware` uses the value of the available req.headers in order to construct
+ * and use the correct url internally. This url is then exposed as `experimental_clerkUrl`,
+ * intended to be used within `beforeAuth` and `afterAuth` if needed.
+ */
+ clerkUrl: ClerkUrl;
+};
+
+export const createClerkUrl = (...args: ConstructorParameters<typeof ClerkUrl>): ClerkUrl => {
+ return new ClerkUrl(...args);
+};
+
+export type { ClerkUrl };

packages/fastify/src/__snapshots__/constants.test.ts.snap

@@ -24,6 +24,7 @@ exports[`constants from environment variables 1`] = `
  "ForwardedPort": "x-forwarded-port",
  "ForwardedProto": "x-forwarded-proto",
  "Host": "host",
+ "Location": "location",
  "Origin": "origin",
  "Referrer": "referer",
  "SecFetchDest": "sec-fetch-dest",

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

@@ -1,14 +1,12 @@
-import type { ClerkProviderOptionsWrapper } from '@clerk/clerk-react';
-import type { InitialState } from '@clerk/types';
+import type { InitialState, Without } from '@clerk/types';
 import React from 'react';
 
+import type { NextClerkProviderProps } from '../../types';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
 import { ClientClerkProvider } from '../client/ClerkProvider';
 import { initialState } from './auth';
 
-type NextAppClerkProviderProps = ClerkProviderOptionsWrapper;
-
-export function ClerkProvider(props: NextAppClerkProviderProps) {
+export function ClerkProvider(props: Without<NextClerkProviderProps, '__unstable_invokeMiddlewareOnAuthStateChange'>) {
  const { children, ...rest } = props;
  const state = initialState()?.__clerk_ssr_state as InitialState;
 

packages/nextjs/src/app-router/server/auth.ts

@@ -1,18 +1,20 @@
 import type { AuthObject } from '@clerk/backend/internal';
+import { notFound, redirect } from 'next/navigation';
 
 import { authAuthHeaderMissing } from '../../server/errors';
 import { buildClerkProps, createGetAuth } from '../../server/getAuth';
-import type { AuthProtect } from './protect';
-import { createProtect } from './protect';
+import type { AuthProtect } from '../../server/protect';
+import { createProtect } from '../../server/protect';
 import { buildRequestLike } from './utils';
 
 export const auth = (): AuthObject & { protect: AuthProtect } => {
+ const request = buildRequestLike();
  const authObject = createGetAuth({
  debugLoggerName: 'auth()',
  noAuthStatusMessage: authAuthHeaderMissing(),
- })(buildRequestLike());
+ })(request);
 
- return Object.assign(authObject, { protect: createProtect(authObject) });
+ return Object.assign(authObject, { protect: createProtect({ request, authObject, notFound, redirect }) });
 };
 
 export const initialState = () => {

packages/nextjs/src/constants.ts

@@ -2,6 +2,8 @@ const Headers = {
  NextRewrite: 'x-middleware-rewrite',
  NextResume: 'x-middleware-next',
  NextRedirect: 'Location',
+ NextUrl: 'next-url',
+ NextAction: 'next-action',
 } as const;
 
 export const constants = {

packages/nextjs/src/pages/__tests__/index.test.tsx

@@ -31,27 +31,6 @@ describe('ClerkProvider', () => {
  it('domain + isSatellite (satellite app)', () => {
  expectTypeOf({ ...defaultProps, domain: 'test', isSatellite: true }).toMatchTypeOf<ClerkProviderProps>();
  });
-
- it('only domain is not allowed', () => {
- expectTypeOf({ ...defaultProps, domain: 'test' }).not.toMatchTypeOf<ClerkProviderProps>();
- });
-
- it('only isSatellite is not allowed', () => {
- expectTypeOf({ ...defaultProps, isSatellite: true }).not.toMatchTypeOf<ClerkProviderProps>();
- });
-
- it('proxyUrl + domain is not allowed', () => {
- expectTypeOf({ ...defaultProps, proxyUrl: 'test', domain: 'test' }).not.toMatchTypeOf<ClerkProviderProps>();
- });
-
- it('proxyUrl + domain + isSatellite is not allowed', () => {
- expectTypeOf({
- ...defaultProps,
- proxyUrl: 'test',
- domain: 'test',
- isSatellite: true,
- }).not.toMatchTypeOf<ClerkProviderProps>();
- });
  });
 
  describe('clerkJSVariant', () => {

packages/nextjs/src/server/__tests__/__snapshots__/exports.test.ts.snap

@@ -6,8 +6,10 @@ exports[`/server public exports should not include a breaking change 1`] = `
  "authMiddleware",
  "buildClerkProps",
  "clerkClient",
+ "clerkMiddleware",
  "createClerkClient",
  "currentUser",
+ "experimental_createRouteMatcher",
  "getAuth",
  "redirectToSignIn",
  "redirectToSignUp",

packages/nextjs/src/server/authMiddleware.test.ts

@@ -33,9 +33,10 @@ jest.mock('./redirect', () => {
 });
 
 import { paths, setHeader } from '../utils';
-import { authMiddleware, createRouteMatcher, DEFAULT_CONFIG_MATCHER, DEFAULT_IGNORED_ROUTES } from './authMiddleware';
+import { authMiddleware, DEFAULT_CONFIG_MATCHER, DEFAULT_IGNORED_ROUTES } from './authMiddleware';
 // used to assert the mock
 import { clerkClient } from './clerkClient';
+import { createRouteMatcher } from './routeMatcher';
 
 /**
  * Disable console warnings about config matchers

.changeset/funny-avocados-shout.md

@@ -0,0 +1,64 @@
+---
+'@clerk/nextjs': patch
+---
+
+Introduce the new `clerkMiddleware` helper to allow for more flexibility in how Clerk is integrated into your Next.js middleware. Example usage can be found below, for more details, For more details, please see the [clerkMiddleware](https://clerk.com/docs/references/nextjs/clerkMiddleware) documentation.
+The `clerkMiddleware` helper effectively replaces the older `authMiddleware` helper, which is now considered deprecated and will be removed in the next major release.
+
+### 1. Protect a route that requires authentication
+
+```js
+import { clerkMiddleware } from '@clerk/nextjs/server';
+
+export default clerkMiddleware(auth => {
+ const { userId } = auth().protect();
+ // userId is now available for use in your route handler
+ // for page requests, calling protect will automatically redirect the user to the sign-in URL if they are not authenticated
+ return NextResponse.next();
+});
+```
+
+
+### 2. Protect a route that requires specific permissions
+
+```js
+import { clerkMiddleware } from '@clerk/nextjs/server';
+
+export default clerkMiddleware(auth => {
+ const { userId } = auth().protect({ permission: 'org:domains:delete'});
+ // userId is now available for use in your route handler
+ // for page requests, calling protect will automatically throw a notFound error if the user does not have the required permissions
+ return NextResponse.next();
+});
+```
+
+### 2. Manually redirect to sign-in URL using the redirectToSignIn helper
+
+```js
+import { clerkMiddleware } from '@clerk/nextjs/server';
+
+export default clerkMiddleware(auth => {
+ // If you want more fine-grained control, you can always use the low-level redirectToSignIn helper
+ if(!auth().userId) {
+ return auth().redirectToSignIn();
+ }
+
+ return NextResponse.next();
+});
+```
+
+This commit also introduces the experimental `createRouteMatcher` helper, which can be used to create a route matcher that matches a route against the current request. This is useful for creating custom logic based on which routes you want to handle as protected or public.
+
+```js
+import { clerkMiddleware, experimental_createRouteMatcher } from '@clerk/nextjs/server';
+
+const isProtectedRoute = experimental_createRouteMatcher([/protected.*/]);
+
+export default clerkMiddleware((auth, request) => {
+ if(isProtectedRoute(request)) {
+ auth().protect();
+ }
+
+ return NextResponse.next();
+});
+```

integration/constants.ts

@@ -38,6 +38,7 @@ export const constants = {
  */
  E2E_APP_SK: process.env.E2E_APP_SK,
  E2E_APP_PK: process.env.E2E_APP_PK,
+ E2E_CLERK_API_URL: process.env.E2E_CLERK_API_URL,
  /**
  * The version of the dependency to use, controlled programmatically.
  */

integration/models/longRunningApplication.ts

@@ -43,7 +43,7 @@ export const longRunningApplication = (params: LongRunningApplicationParams) =>
  if (!stateFile.getLongRunningApps() || [port, serverUrl, pid, appDir, env].filter(Boolean).length === 0) {
  return;
  }
- const data = stateFile.getLongRunningApps()[id];
+ const data = stateFile.getLongRunningApps()[id] || {};
  port ||= data.port;
  serverUrl ||= data.serverUrl;
  pid ||= data.pid;

integration/scripts/setup.ts

@@ -1,15 +1,15 @@
-/* eslint-disable turbo/no-undeclared-env-vars */
 import { constants } from '../constants';
 
 export const parseEnvOptions = () => {
  const appIds = constants.E2E_APP_ID ? constants.E2E_APP_ID.split(',') : [];
  const appUrl = constants.E2E_APP_URL;
  const appPk = constants.E2E_APP_PK;
  const appSk = constants.E2E_APP_SK;
+ const clerkApiUrl = constants.E2E_CLERK_API_URL;
 
  if (appIds.length && appUrl) {
  throw new Error('E2E_APP_ID cannot be used with E2E_APP_URL');
  }
 
- return { appIds, appUrl, appPk, appSk };
+ return { appIds, appUrl, appPk, appSk, clerkApiUrl };
 };

integration/testUtils/testAgainstRunningApps.ts

@@ -20,7 +20,7 @@ type RunningAppsParams = {
  */
 const runningApps = (params: RunningAppsParams = {}) => {
  const withEnv = [params.withEnv].flat().filter(Boolean);
- const { appIds, appUrl, appPk, appSk } = parseEnvOptions();
+ const { appIds, appUrl, appPk, appSk, clerkApiUrl } = parseEnvOptions();
  if (appIds.length) {
  // if appIds are provided, we only return the apps with the given ids
  const filter = app => (withEnv.length ? withEnv.includes(app.env) : true);
@@ -31,6 +31,7 @@ const runningApps = (params: RunningAppsParams = {}) => {
  const env = environmentConfig()
  .setId('tempEnv')
  .setEnvVariable('private', 'CLERK_SECRET_KEY', appSk)
+ .setEnvVariable('private', 'CLERK_API_URL', clerkApiUrl)
  .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', appPk);
  return [longRunningApplication({ id: 'standalone', env, serverUrl: appUrl, config: applicationConfig() })];
 };

integration/tests/protect.test.ts

@@ -77,7 +77,7 @@ testAgainstRunningApps({ withEnv: [appConfigs.envs.withCustomRoles] })('authoriz
  await u.page.goToRelative('/settings/auth-has');
  await expect(u.page.getByText(/User is missing permissions/i)).toBeVisible();
  await u.page.goToRelative('/settings/auth-protect');
- await expect(u.page.getByText(/this page could not be found/i)).toBeVisible();
+ await u.po.signIn.waitForMounted();
  });
 
  test('Protect in RSCs and RCCs as `viewer`', async ({ page, context }) => {

packages/backend/src/constants.ts

@@ -42,6 +42,7 @@ const Headers = {
  Host: 'host',
  ContentType: 'content-type',
  SecFetchDest: 'sec-fetch-dest',
+ Location: 'location',
 } as const;
 
 const ContentTypes = {
@@ -58,3 +59,5 @@ export const constants = {
  ContentTypes,
  QueryParameters,
 } as const;
+
+export type Constants = typeof constants;

packages/backend/src/tokens/clerkRequest.ts

@@ -1,25 +1,14 @@
 import { parse as parseCookies } from 'cookie';
 
 import { constants } from '../constants';
-
-export type WithClerkUrl<T> = T & {
- /**
- * When a NextJs app is hosted on a platform different from Vercel
- * or inside a container (Netlify, Fly.io, AWS Amplify, docker etc),
- * req.url is always set to `localhost:3000` instead of the actual host of the app.
- *
- * The `authMiddleware` uses the value of the available req.headers in order to construct
- * and use the correct url internally. This url is then exposed as `experimental_clerkUrl`,
- * intended to be used within `beforeAuth` and `afterAuth` if needed.
- */
- clerkUrl: URL;
-};
+import type { ClerkUrl, WithClerkUrl } from './clerkUrl';
+import { createClerkUrl } from './clerkUrl';
 
 class ClerkRequest extends Request {
- readonly clerkUrl: URL;
+ readonly clerkUrl: ClerkUrl;
  readonly cookies: Map<string, string>;
 
- public constructor(req: Request) {
+ public constructor(req: ClerkRequest | Request) {
  super(req, req);
  this.clerkUrl = this.deriveUrlFromHeaders(req);
  this.cookies = this.parseCookies(req);
@@ -44,7 +33,7 @@ class ClerkRequest extends Request {
  const resolvedProtocol = this.getFirstValueFromHeader(forwardedProto) ?? protocol?.replace(/[:/]/, '');
  const origin = resolvedHost && resolvedProtocol ? `${resolvedProtocol}://${resolvedHost}` : initialUrl.origin;
 
- return new URL(initialUrl.pathname + initialUrl.search, origin);
+ return createClerkUrl(initialUrl.pathname + initialUrl.search, origin);
  }
 
  private getFirstValueFromHeader(value?: string | null) {
@@ -62,7 +51,7 @@ class ClerkRequest extends Request {
 }
 
 export const createClerkRequest = (...args: ConstructorParameters<typeof ClerkRequest>): ClerkRequest => {
- return new ClerkRequest(...args);
+ return args[0] instanceof ClerkRequest ? args[0] : new ClerkRequest(...args);
 };
 
 export type { ClerkRequest };

packages/backend/src/tokens/clerkUrl.ts

@@ -0,0 +1,24 @@
+class ClerkUrl extends URL {
+ public isCrossOrigin(other: URL | string) {
+ return this.origin !== new URL(other.toString()).origin;
+ }
+}
+
+export type WithClerkUrl<T> = T & {
+ /**
+ * When a NextJs app is hosted on a platform different from Vercel
+ * or inside a container (Netlify, Fly.io, AWS Amplify, docker etc),
+ * req.url is always set to `localhost:3000` instead of the actual host of the app.
+ *
+ * The `authMiddleware` uses the value of the available req.headers in order to construct
+ * and use the correct url internally. This url is then exposed as `experimental_clerkUrl`,
+ * intended to be used within `beforeAuth` and `afterAuth` if needed.
+ */
+ clerkUrl: ClerkUrl;
+};
+
+export const createClerkUrl = (...args: ConstructorParameters<typeof ClerkUrl>): ClerkUrl => {
+ return new ClerkUrl(...args);
+};
+
+export type { ClerkUrl };

packages/fastify/src/__snapshots__/constants.test.ts.snap

@@ -24,6 +24,7 @@ exports[`constants from environment variables 1`] = `
  "ForwardedPort": "x-forwarded-port",
  "ForwardedProto": "x-forwarded-proto",
  "Host": "host",
+ "Location": "location",
  "Origin": "origin",
  "Referrer": "referer",
  "SecFetchDest": "sec-fetch-dest",

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

@@ -1,14 +1,12 @@
-import type { ClerkProviderOptionsWrapper } from '@clerk/clerk-react';
-import type { InitialState } from '@clerk/types';
+import type { InitialState, Without } from '@clerk/types';
 import React from 'react';
 
+import type { NextClerkProviderProps } from '../../types';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
 import { ClientClerkProvider } from '../client/ClerkProvider';
 import { initialState } from './auth';
 
-type NextAppClerkProviderProps = ClerkProviderOptionsWrapper;
-
-export function ClerkProvider(props: NextAppClerkProviderProps) {
+export function ClerkProvider(props: Without<NextClerkProviderProps, '__unstable_invokeMiddlewareOnAuthStateChange'>) {
  const { children, ...rest } = props;
  const state = initialState()?.__clerk_ssr_state as InitialState;
 

packages/nextjs/src/app-router/server/auth.ts

@@ -1,18 +1,20 @@
 import type { AuthObject } from '@clerk/backend/internal';
+import { notFound, redirect } from 'next/navigation';
 
 import { authAuthHeaderMissing } from '../../server/errors';
 import { buildClerkProps, createGetAuth } from '../../server/getAuth';
-import type { AuthProtect } from './protect';
-import { createProtect } from './protect';
+import type { AuthProtect } from '../../server/protect';
+import { createProtect } from '../../server/protect';
 import { buildRequestLike } from './utils';
 
 export const auth = (): AuthObject & { protect: AuthProtect } => {
+ const request = buildRequestLike();
  const authObject = createGetAuth({
  debugLoggerName: 'auth()',
  noAuthStatusMessage: authAuthHeaderMissing(),
- })(buildRequestLike());
+ })(request);
 
- return Object.assign(authObject, { protect: createProtect(authObject) });
+ return Object.assign(authObject, { protect: createProtect({ request, authObject, notFound, redirect }) });
 };
 
 export const initialState = () => {

packages/nextjs/src/constants.ts

@@ -2,6 +2,8 @@ const Headers = {
  NextRewrite: 'x-middleware-rewrite',
  NextResume: 'x-middleware-next',
  NextRedirect: 'Location',
+ NextUrl: 'next-url',
+ NextAction: 'next-action',
 } as const;
 
 export const constants = {

packages/nextjs/src/pages/__tests__/index.test.tsx

@@ -31,27 +31,6 @@ describe('ClerkProvider', () => {
  it('domain + isSatellite (satellite app)', () => {
  expectTypeOf({ ...defaultProps, domain: 'test', isSatellite: true }).toMatchTypeOf<ClerkProviderProps>();
  });
-
- it('only domain is not allowed', () => {
- expectTypeOf({ ...defaultProps, domain: 'test' }).not.toMatchTypeOf<ClerkProviderProps>();
- });
-
- it('only isSatellite is not allowed', () => {
- expectTypeOf({ ...defaultProps, isSatellite: true }).not.toMatchTypeOf<ClerkProviderProps>();
- });
-
- it('proxyUrl + domain is not allowed', () => {
- expectTypeOf({ ...defaultProps, proxyUrl: 'test', domain: 'test' }).not.toMatchTypeOf<ClerkProviderProps>();
- });
-
- it('proxyUrl + domain + isSatellite is not allowed', () => {
- expectTypeOf({
- ...defaultProps,
- proxyUrl: 'test',
- domain: 'test',
- isSatellite: true,
- }).not.toMatchTypeOf<ClerkProviderProps>();
- });
  });
 
  describe('clerkJSVariant', () => {

packages/nextjs/src/server/__tests__/__snapshots__/exports.test.ts.snap

@@ -6,8 +6,10 @@ exports[`/server public exports should not include a breaking change 1`] = `
  "authMiddleware",
  "buildClerkProps",
  "clerkClient",
+ "clerkMiddleware",
  "createClerkClient",
  "currentUser",
+ "experimental_createRouteMatcher",
  "getAuth",
  "redirectToSignIn",
  "redirectToSignUp",

packages/nextjs/src/server/authMiddleware.test.ts

@@ -33,9 +33,10 @@ jest.mock('./redirect', () => {
 });
 
 import { paths, setHeader } from '../utils';
-import { authMiddleware, createRouteMatcher, DEFAULT_CONFIG_MATCHER, DEFAULT_IGNORED_ROUTES } from './authMiddleware';
+import { authMiddleware, DEFAULT_CONFIG_MATCHER, DEFAULT_IGNORED_ROUTES } from './authMiddleware';
 // used to assert the mock
 import { clerkClient } from './clerkClient';
+import { createRouteMatcher } from './routeMatcher';
 
 /**
  * Disable console warnings about config matchers

.changeset/funny-avocados-shout.md

@@ -0,0 +1,64 @@
+---
+'@clerk/nextjs': patch
+---
+
+Introduce the new `clerkMiddleware` helper to allow for more flexibility in how Clerk is integrated into your Next.js middleware. Example usage can be found below, for more details, For more details, please see the [clerkMiddleware](https://clerk.com/docs/references/nextjs/clerkMiddleware) documentation.
+The `clerkMiddleware` helper effectively replaces the older `authMiddleware` helper, which is now considered deprecated and will be removed in the next major release.
+
+### 1. Protect a route that requires authentication
+
+```js
+import { clerkMiddleware } from '@clerk/nextjs/server';
+
+export default clerkMiddleware(auth => {
+ const { userId } = auth().protect();
+ // userId is now available for use in your route handler
+ // for page requests, calling protect will automatically redirect the user to the sign-in URL if they are not authenticated
+ return NextResponse.next();
+});
+```
+
+
+### 2. Protect a route that requires specific permissions
+
+```js
+import { clerkMiddleware } from '@clerk/nextjs/server';
+
+export default clerkMiddleware(auth => {
+ const { userId } = auth().protect({ permission: 'org:domains:delete'});
+ // userId is now available for use in your route handler
+ // for page requests, calling protect will automatically throw a notFound error if the user does not have the required permissions
+ return NextResponse.next();
+});
+```
+
+### 2. Manually redirect to sign-in URL using the redirectToSignIn helper
+
+```js
+import { clerkMiddleware } from '@clerk/nextjs/server';
+
+export default clerkMiddleware(auth => {
+ // If you want more fine-grained control, you can always use the low-level redirectToSignIn helper
+ if(!auth().userId) {
+ return auth().redirectToSignIn();
+ }
+
+ return NextResponse.next();
+});
+```
+
+This commit also introduces the experimental `createRouteMatcher` helper, which can be used to create a route matcher that matches a route against the current request. This is useful for creating custom logic based on which routes you want to handle as protected or public.
+
+```js
+import { clerkMiddleware, experimental_createRouteMatcher } from '@clerk/nextjs/server';
+
+const isProtectedRoute = experimental_createRouteMatcher([/protected.*/]);
+
+export default clerkMiddleware((auth, request) => {
+ if(isProtectedRoute(request)) {
+ auth().protect();
+ }
+
+ return NextResponse.next();
+});
+```

integration/constants.ts

@@ -38,6 +38,7 @@ export const constants = {
  */
  E2E_APP_SK: process.env.E2E_APP_SK,
  E2E_APP_PK: process.env.E2E_APP_PK,
+ E2E_CLERK_API_URL: process.env.E2E_CLERK_API_URL,
  /**
  * The version of the dependency to use, controlled programmatically.
  */

integration/models/longRunningApplication.ts

@@ -43,7 +43,7 @@ export const longRunningApplication = (params: LongRunningApplicationParams) =>
  if (!stateFile.getLongRunningApps() || [port, serverUrl, pid, appDir, env].filter(Boolean).length === 0) {
  return;
  }
- const data = stateFile.getLongRunningApps()[id];
+ const data = stateFile.getLongRunningApps()[id] || {};
  port ||= data.port;
  serverUrl ||= data.serverUrl;
  pid ||= data.pid;

integration/scripts/setup.ts

@@ -1,15 +1,15 @@
-/* eslint-disable turbo/no-undeclared-env-vars */
 import { constants } from '../constants';
 
 export const parseEnvOptions = () => {
  const appIds = constants.E2E_APP_ID ? constants.E2E_APP_ID.split(',') : [];
  const appUrl = constants.E2E_APP_URL;
  const appPk = constants.E2E_APP_PK;
  const appSk = constants.E2E_APP_SK;
+ const clerkApiUrl = constants.E2E_CLERK_API_URL;
 
  if (appIds.length && appUrl) {
  throw new Error('E2E_APP_ID cannot be used with E2E_APP_URL');
  }
 
- return { appIds, appUrl, appPk, appSk };
+ return { appIds, appUrl, appPk, appSk, clerkApiUrl };
 };

integration/testUtils/testAgainstRunningApps.ts

@@ -20,7 +20,7 @@ type RunningAppsParams = {
  */
 const runningApps = (params: RunningAppsParams = {}) => {
  const withEnv = [params.withEnv].flat().filter(Boolean);
- const { appIds, appUrl, appPk, appSk } = parseEnvOptions();
+ const { appIds, appUrl, appPk, appSk, clerkApiUrl } = parseEnvOptions();
  if (appIds.length) {
  // if appIds are provided, we only return the apps with the given ids
  const filter = app => (withEnv.length ? withEnv.includes(app.env) : true);
@@ -31,6 +31,7 @@ const runningApps = (params: RunningAppsParams = {}) => {
  const env = environmentConfig()
  .setId('tempEnv')
  .setEnvVariable('private', 'CLERK_SECRET_KEY', appSk)
+ .setEnvVariable('private', 'CLERK_API_URL', clerkApiUrl)
  .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', appPk);
  return [longRunningApplication({ id: 'standalone', env, serverUrl: appUrl, config: applicationConfig() })];
 };

integration/tests/protect.test.ts

@@ -77,7 +77,7 @@ testAgainstRunningApps({ withEnv: [appConfigs.envs.withCustomRoles] })('authoriz
  await u.page.goToRelative('/settings/auth-has');
  await expect(u.page.getByText(/User is missing permissions/i)).toBeVisible();
  await u.page.goToRelative('/settings/auth-protect');
- await expect(u.page.getByText(/this page could not be found/i)).toBeVisible();
+ await u.po.signIn.waitForMounted();
  });
 
  test('Protect in RSCs and RCCs as `viewer`', async ({ page, context }) => {

packages/backend/src/constants.ts

@@ -42,6 +42,7 @@ const Headers = {
  Host: 'host',
  ContentType: 'content-type',
  SecFetchDest: 'sec-fetch-dest',
+ Location: 'location',
 } as const;
 
 const ContentTypes = {
@@ -58,3 +59,5 @@ export const constants = {
  ContentTypes,
  QueryParameters,
 } as const;
+
+export type Constants = typeof constants;

packages/backend/src/tokens/clerkRequest.ts

@@ -1,25 +1,14 @@
 import { parse as parseCookies } from 'cookie';
 
 import { constants } from '../constants';
-
-export type WithClerkUrl<T> = T & {
- /**
- * When a NextJs app is hosted on a platform different from Vercel
- * or inside a container (Netlify, Fly.io, AWS Amplify, docker etc),
- * req.url is always set to `localhost:3000` instead of the actual host of the app.
- *
- * The `authMiddleware` uses the value of the available req.headers in order to construct
- * and use the correct url internally. This url is then exposed as `experimental_clerkUrl`,
- * intended to be used within `beforeAuth` and `afterAuth` if needed.
- */
- clerkUrl: URL;
-};
+import type { ClerkUrl, WithClerkUrl } from './clerkUrl';
+import { createClerkUrl } from './clerkUrl';
 
 class ClerkRequest extends Request {
- readonly clerkUrl: URL;
+ readonly clerkUrl: ClerkUrl;
  readonly cookies: Map<string, string>;
 
- public constructor(req: Request) {
+ public constructor(req: ClerkRequest | Request) {
  super(req, req);
  this.clerkUrl = this.deriveUrlFromHeaders(req);
  this.cookies = this.parseCookies(req);
@@ -44,7 +33,7 @@ class ClerkRequest extends Request {
  const resolvedProtocol = this.getFirstValueFromHeader(forwardedProto) ?? protocol?.replace(/[:/]/, '');
  const origin = resolvedHost && resolvedProtocol ? `${resolvedProtocol}://${resolvedHost}` : initialUrl.origin;
 
- return new URL(initialUrl.pathname + initialUrl.search, origin);
+ return createClerkUrl(initialUrl.pathname + initialUrl.search, origin);
  }
 
  private getFirstValueFromHeader(value?: string | null) {
@@ -62,7 +51,7 @@ class ClerkRequest extends Request {
 }
 
 export const createClerkRequest = (...args: ConstructorParameters<typeof ClerkRequest>): ClerkRequest => {
- return new ClerkRequest(...args);
+ return args[0] instanceof ClerkRequest ? args[0] : new ClerkRequest(...args);
 };
 
 export type { ClerkRequest };

packages/backend/src/tokens/clerkUrl.ts

@@ -0,0 +1,24 @@
+class ClerkUrl extends URL {
+ public isCrossOrigin(other: URL | string) {
+ return this.origin !== new URL(other.toString()).origin;
+ }
+}
+
+export type WithClerkUrl<T> = T & {
+ /**
+ * When a NextJs app is hosted on a platform different from Vercel
+ * or inside a container (Netlify, Fly.io, AWS Amplify, docker etc),
+ * req.url is always set to `localhost:3000` instead of the actual host of the app.
+ *
+ * The `authMiddleware` uses the value of the available req.headers in order to construct
+ * and use the correct url internally. This url is then exposed as `experimental_clerkUrl`,
+ * intended to be used within `beforeAuth` and `afterAuth` if needed.
+ */
+ clerkUrl: ClerkUrl;
+};
+
+export const createClerkUrl = (...args: ConstructorParameters<typeof ClerkUrl>): ClerkUrl => {
+ return new ClerkUrl(...args);
+};
+
+export type { ClerkUrl };

packages/fastify/src/__snapshots__/constants.test.ts.snap

@@ -24,6 +24,7 @@ exports[`constants from environment variables 1`] = `
  "ForwardedPort": "x-forwarded-port",
  "ForwardedProto": "x-forwarded-proto",
  "Host": "host",
+ "Location": "location",
  "Origin": "origin",
  "Referrer": "referer",
  "SecFetchDest": "sec-fetch-dest",

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

@@ -1,14 +1,12 @@
-import type { ClerkProviderOptionsWrapper } from '@clerk/clerk-react';
-import type { InitialState } from '@clerk/types';
+import type { InitialState, Without } from '@clerk/types';
 import React from 'react';
 
+import type { NextClerkProviderProps } from '../../types';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
 import { ClientClerkProvider } from '../client/ClerkProvider';
 import { initialState } from './auth';
 
-type NextAppClerkProviderProps = ClerkProviderOptionsWrapper;
-
-export function ClerkProvider(props: NextAppClerkProviderProps) {
+export function ClerkProvider(props: Without<NextClerkProviderProps, '__unstable_invokeMiddlewareOnAuthStateChange'>) {
  const { children, ...rest } = props;
  const state = initialState()?.__clerk_ssr_state as InitialState;
 

packages/nextjs/src/app-router/server/auth.ts

@@ -1,18 +1,20 @@
 import type { AuthObject } from '@clerk/backend/internal';
+import { notFound, redirect } from 'next/navigation';
 
 import { authAuthHeaderMissing } from '../../server/errors';
 import { buildClerkProps, createGetAuth } from '../../server/getAuth';
-import type { AuthProtect } from './protect';
-import { createProtect } from './protect';
+import type { AuthProtect } from '../../server/protect';
+import { createProtect } from '../../server/protect';
 import { buildRequestLike } from './utils';
 
 export const auth = (): AuthObject & { protect: AuthProtect } => {
+ const request = buildRequestLike();
  const authObject = createGetAuth({
  debugLoggerName: 'auth()',
  noAuthStatusMessage: authAuthHeaderMissing(),
- })(buildRequestLike());
+ })(request);
 
- return Object.assign(authObject, { protect: createProtect(authObject) });
+ return Object.assign(authObject, { protect: createProtect({ request, authObject, notFound, redirect }) });
 };
 
 export const initialState = () => {

packages/nextjs/src/constants.ts

@@ -2,6 +2,8 @@ const Headers = {
  NextRewrite: 'x-middleware-rewrite',
  NextResume: 'x-middleware-next',
  NextRedirect: 'Location',
+ NextUrl: 'next-url',
+ NextAction: 'next-action',
 } as const;
 
 export const constants = {

packages/nextjs/src/pages/__tests__/index.test.tsx

@@ -31,27 +31,6 @@ describe('ClerkProvider', () => {
  it('domain + isSatellite (satellite app)', () => {
  expectTypeOf({ ...defaultProps, domain: 'test', isSatellite: true }).toMatchTypeOf<ClerkProviderProps>();
  });
-
- it('only domain is not allowed', () => {
- expectTypeOf({ ...defaultProps, domain: 'test' }).not.toMatchTypeOf<ClerkProviderProps>();
- });
-
- it('only isSatellite is not allowed', () => {
- expectTypeOf({ ...defaultProps, isSatellite: true }).not.toMatchTypeOf<ClerkProviderProps>();
- });
-
- it('proxyUrl + domain is not allowed', () => {
- expectTypeOf({ ...defaultProps, proxyUrl: 'test', domain: 'test' }).not.toMatchTypeOf<ClerkProviderProps>();
- });
-
- it('proxyUrl + domain + isSatellite is not allowed', () => {
- expectTypeOf({
- ...defaultProps,
- proxyUrl: 'test',
- domain: 'test',
- isSatellite: true,
- }).not.toMatchTypeOf<ClerkProviderProps>();
- });
  });
 
  describe('clerkJSVariant', () => {

packages/nextjs/src/server/__tests__/__snapshots__/exports.test.ts.snap

@@ -6,8 +6,10 @@ exports[`/server public exports should not include a breaking change 1`] = `
  "authMiddleware",
  "buildClerkProps",
  "clerkClient",
+ "clerkMiddleware",
  "createClerkClient",
  "currentUser",
+ "experimental_createRouteMatcher",
  "getAuth",
  "redirectToSignIn",
  "redirectToSignUp",

packages/nextjs/src/server/authMiddleware.test.ts

@@ -33,9 +33,10 @@ jest.mock('./redirect', () => {
 });
 
 import { paths, setHeader } from '../utils';
-import { authMiddleware, createRouteMatcher, DEFAULT_CONFIG_MATCHER, DEFAULT_IGNORED_ROUTES } from './authMiddleware';
+import { authMiddleware, DEFAULT_CONFIG_MATCHER, DEFAULT_IGNORED_ROUTES } from './authMiddleware';
 // used to assert the mock
 import { clerkClient } from './clerkClient';
+import { createRouteMatcher } from './routeMatcher';
 
 /**
  * Disable console warnings about config matchers

.changeset/funny-avocados-shout.md

@@ -0,0 +1,64 @@
+---
+'@clerk/nextjs': patch
+---
+
+Introduce the new `clerkMiddleware` helper to allow for more flexibility in how Clerk is integrated into your Next.js middleware. Example usage can be found below, for more details, For more details, please see the [clerkMiddleware](https://clerk.com/docs/references/nextjs/clerkMiddleware) documentation.
+The `clerkMiddleware` helper effectively replaces the older `authMiddleware` helper, which is now considered deprecated and will be removed in the next major release.
+
+### 1. Protect a route that requires authentication
+
+```js
+import { clerkMiddleware } from '@clerk/nextjs/server';
+
+export default clerkMiddleware(auth => {
+ const { userId } = auth().protect();
+ // userId is now available for use in your route handler
+ // for page requests, calling protect will automatically redirect the user to the sign-in URL if they are not authenticated
+ return NextResponse.next();
+});
+```
+
+
+### 2. Protect a route that requires specific permissions
+
+```js
+import { clerkMiddleware } from '@clerk/nextjs/server';
+
+export default clerkMiddleware(auth => {
+ const { userId } = auth().protect({ permission: 'org:domains:delete'});
+ // userId is now available for use in your route handler
+ // for page requests, calling protect will automatically throw a notFound error if the user does not have the required permissions
+ return NextResponse.next();
+});
+```
+
+### 2. Manually redirect to sign-in URL using the redirectToSignIn helper
+
+```js
+import { clerkMiddleware } from '@clerk/nextjs/server';
+
+export default clerkMiddleware(auth => {
+ // If you want more fine-grained control, you can always use the low-level redirectToSignIn helper
+ if(!auth().userId) {
+ return auth().redirectToSignIn();
+ }
+
+ return NextResponse.next();
+});
+```
+
+This commit also introduces the experimental `createRouteMatcher` helper, which can be used to create a route matcher that matches a route against the current request. This is useful for creating custom logic based on which routes you want to handle as protected or public.
+
+```js
+import { clerkMiddleware, experimental_createRouteMatcher } from '@clerk/nextjs/server';
+
+const isProtectedRoute = experimental_createRouteMatcher([/protected.*/]);
+
+export default clerkMiddleware((auth, request) => {
+ if(isProtectedRoute(request)) {
+ auth().protect();
+ }
+
+ return NextResponse.next();
+});
+```

integration/constants.ts

@@ -38,6 +38,7 @@ export const constants = {
  */
  E2E_APP_SK: process.env.E2E_APP_SK,
  E2E_APP_PK: process.env.E2E_APP_PK,
+ E2E_CLERK_API_URL: process.env.E2E_CLERK_API_URL,
  /**
  * The version of the dependency to use, controlled programmatically.
  */

integration/models/longRunningApplication.ts

@@ -43,7 +43,7 @@ export const longRunningApplication = (params: LongRunningApplicationParams) =>
  if (!stateFile.getLongRunningApps() || [port, serverUrl, pid, appDir, env].filter(Boolean).length === 0) {
  return;
  }
- const data = stateFile.getLongRunningApps()[id];
+ const data = stateFile.getLongRunningApps()[id] || {};
  port ||= data.port;
  serverUrl ||= data.serverUrl;
  pid ||= data.pid;

integration/scripts/setup.ts

@@ -1,15 +1,15 @@
-/* eslint-disable turbo/no-undeclared-env-vars */
 import { constants } from '../constants';
 
 export const parseEnvOptions = () => {
  const appIds = constants.E2E_APP_ID ? constants.E2E_APP_ID.split(',') : [];
  const appUrl = constants.E2E_APP_URL;
  const appPk = constants.E2E_APP_PK;
  const appSk = constants.E2E_APP_SK;
+ const clerkApiUrl = constants.E2E_CLERK_API_URL;
 
  if (appIds.length && appUrl) {
  throw new Error('E2E_APP_ID cannot be used with E2E_APP_URL');
  }
 
- return { appIds, appUrl, appPk, appSk };
+ return { appIds, appUrl, appPk, appSk, clerkApiUrl };
 };

integration/testUtils/testAgainstRunningApps.ts

@@ -20,7 +20,7 @@ type RunningAppsParams = {
  */
 const runningApps = (params: RunningAppsParams = {}) => {
  const withEnv = [params.withEnv].flat().filter(Boolean);
- const { appIds, appUrl, appPk, appSk } = parseEnvOptions();
+ const { appIds, appUrl, appPk, appSk, clerkApiUrl } = parseEnvOptions();
  if (appIds.length) {
  // if appIds are provided, we only return the apps with the given ids
  const filter = app => (withEnv.length ? withEnv.includes(app.env) : true);
@@ -31,6 +31,7 @@ const runningApps = (params: RunningAppsParams = {}) => {
  const env = environmentConfig()
  .setId('tempEnv')
  .setEnvVariable('private', 'CLERK_SECRET_KEY', appSk)
+ .setEnvVariable('private', 'CLERK_API_URL', clerkApiUrl)
  .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', appPk);
  return [longRunningApplication({ id: 'standalone', env, serverUrl: appUrl, config: applicationConfig() })];
 };

integration/tests/protect.test.ts

@@ -77,7 +77,7 @@ testAgainstRunningApps({ withEnv: [appConfigs.envs.withCustomRoles] })('authoriz
  await u.page.goToRelative('/settings/auth-has');
  await expect(u.page.getByText(/User is missing permissions/i)).toBeVisible();
  await u.page.goToRelative('/settings/auth-protect');
- await expect(u.page.getByText(/this page could not be found/i)).toBeVisible();
+ await u.po.signIn.waitForMounted();
  });
 
  test('Protect in RSCs and RCCs as `viewer`', async ({ page, context }) => {

packages/backend/src/constants.ts

@@ -42,6 +42,7 @@ const Headers = {
  Host: 'host',
  ContentType: 'content-type',
  SecFetchDest: 'sec-fetch-dest',
+ Location: 'location',
 } as const;
 
 const ContentTypes = {
@@ -58,3 +59,5 @@ export const constants = {
  ContentTypes,
  QueryParameters,
 } as const;
+
+export type Constants = typeof constants;

packages/backend/src/tokens/clerkRequest.ts

@@ -1,25 +1,14 @@
 import { parse as parseCookies } from 'cookie';
 
 import { constants } from '../constants';
-
-export type WithClerkUrl<T> = T & {
- /**
- * When a NextJs app is hosted on a platform different from Vercel
- * or inside a container (Netlify, Fly.io, AWS Amplify, docker etc),
- * req.url is always set to `localhost:3000` instead of the actual host of the app.
- *
- * The `authMiddleware` uses the value of the available req.headers in order to construct
- * and use the correct url internally. This url is then exposed as `experimental_clerkUrl`,
- * intended to be used within `beforeAuth` and `afterAuth` if needed.
- */
- clerkUrl: URL;
-};
+import type { ClerkUrl, WithClerkUrl } from './clerkUrl';
+import { createClerkUrl } from './clerkUrl';
 
 class ClerkRequest extends Request {
- readonly clerkUrl: URL;
+ readonly clerkUrl: ClerkUrl;
  readonly cookies: Map<string, string>;
 
- public constructor(req: Request) {
+ public constructor(req: ClerkRequest | Request) {
  super(req, req);
  this.clerkUrl = this.deriveUrlFromHeaders(req);
  this.cookies = this.parseCookies(req);
@@ -44,7 +33,7 @@ class ClerkRequest extends Request {
  const resolvedProtocol = this.getFirstValueFromHeader(forwardedProto) ?? protocol?.replace(/[:/]/, '');
  const origin = resolvedHost && resolvedProtocol ? `${resolvedProtocol}://${resolvedHost}` : initialUrl.origin;
 
- return new URL(initialUrl.pathname + initialUrl.search, origin);
+ return createClerkUrl(initialUrl.pathname + initialUrl.search, origin);
  }
 
  private getFirstValueFromHeader(value?: string | null) {
@@ -62,7 +51,7 @@ class ClerkRequest extends Request {
 }
 
 export const createClerkRequest = (...args: ConstructorParameters<typeof ClerkRequest>): ClerkRequest => {
- return new ClerkRequest(...args);
+ return args[0] instanceof ClerkRequest ? args[0] : new ClerkRequest(...args);
 };
 
 export type { ClerkRequest };

packages/backend/src/tokens/clerkUrl.ts

@@ -0,0 +1,24 @@
+class ClerkUrl extends URL {
+ public isCrossOrigin(other: URL | string) {
+ return this.origin !== new URL(other.toString()).origin;
+ }
+}
+
+export type WithClerkUrl<T> = T & {
+ /**
+ * When a NextJs app is hosted on a platform different from Vercel
+ * or inside a container (Netlify, Fly.io, AWS Amplify, docker etc),
+ * req.url is always set to `localhost:3000` instead of the actual host of the app.
+ *
+ * The `authMiddleware` uses the value of the available req.headers in order to construct
+ * and use the correct url internally. This url is then exposed as `experimental_clerkUrl`,
+ * intended to be used within `beforeAuth` and `afterAuth` if needed.
+ */
+ clerkUrl: ClerkUrl;
+};
+
+export const createClerkUrl = (...args: ConstructorParameters<typeof ClerkUrl>): ClerkUrl => {
+ return new ClerkUrl(...args);
+};
+
+export type { ClerkUrl };

packages/fastify/src/__snapshots__/constants.test.ts.snap

@@ -24,6 +24,7 @@ exports[`constants from environment variables 1`] = `
  "ForwardedPort": "x-forwarded-port",
  "ForwardedProto": "x-forwarded-proto",
  "Host": "host",
+ "Location": "location",
  "Origin": "origin",
  "Referrer": "referer",
  "SecFetchDest": "sec-fetch-dest",

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

@@ -1,14 +1,12 @@
-import type { ClerkProviderOptionsWrapper } from '@clerk/clerk-react';
-import type { InitialState } from '@clerk/types';
+import type { InitialState, Without } from '@clerk/types';
 import React from 'react';
 
+import type { NextClerkProviderProps } from '../../types';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
 import { ClientClerkProvider } from '../client/ClerkProvider';
 import { initialState } from './auth';
 
-type NextAppClerkProviderProps = ClerkProviderOptionsWrapper;
-
-export function ClerkProvider(props: NextAppClerkProviderProps) {
+export function ClerkProvider(props: Without<NextClerkProviderProps, '__unstable_invokeMiddlewareOnAuthStateChange'>) {
  const { children, ...rest } = props;
  const state = initialState()?.__clerk_ssr_state as InitialState;
 

packages/nextjs/src/app-router/server/auth.ts

@@ -1,18 +1,20 @@
 import type { AuthObject } from '@clerk/backend/internal';
+import { notFound, redirect } from 'next/navigation';
 
 import { authAuthHeaderMissing } from '../../server/errors';
 import { buildClerkProps, createGetAuth } from '../../server/getAuth';
-import type { AuthProtect } from './protect';
-import { createProtect } from './protect';
+import type { AuthProtect } from '../../server/protect';
+import { createProtect } from '../../server/protect';
 import { buildRequestLike } from './utils';
 
 export const auth = (): AuthObject & { protect: AuthProtect } => {
+ const request = buildRequestLike();
  const authObject = createGetAuth({
  debugLoggerName: 'auth()',
  noAuthStatusMessage: authAuthHeaderMissing(),
- })(buildRequestLike());
+ })(request);
 
- return Object.assign(authObject, { protect: createProtect(authObject) });
+ return Object.assign(authObject, { protect: createProtect({ request, authObject, notFound, redirect }) });
 };
 
 export const initialState = () => {

packages/nextjs/src/constants.ts

@@ -2,6 +2,8 @@ const Headers = {
  NextRewrite: 'x-middleware-rewrite',
  NextResume: 'x-middleware-next',
  NextRedirect: 'Location',
+ NextUrl: 'next-url',
+ NextAction: 'next-action',
 } as const;
 
 export const constants = {

packages/nextjs/src/pages/__tests__/index.test.tsx

@@ -31,27 +31,6 @@ describe('ClerkProvider', () => {
  it('domain + isSatellite (satellite app)', () => {
  expectTypeOf({ ...defaultProps, domain: 'test', isSatellite: true }).toMatchTypeOf<ClerkProviderProps>();
  });
-
- it('only domain is not allowed', () => {
- expectTypeOf({ ...defaultProps, domain: 'test' }).not.toMatchTypeOf<ClerkProviderProps>();
- });
-
- it('only isSatellite is not allowed', () => {
- expectTypeOf({ ...defaultProps, isSatellite: true }).not.toMatchTypeOf<ClerkProviderProps>();
- });
-
- it('proxyUrl + domain is not allowed', () => {
- expectTypeOf({ ...defaultProps, proxyUrl: 'test', domain: 'test' }).not.toMatchTypeOf<ClerkProviderProps>();
- });
-
- it('proxyUrl + domain + isSatellite is not allowed', () => {
- expectTypeOf({
- ...defaultProps,
- proxyUrl: 'test',
- domain: 'test',
- isSatellite: true,
- }).not.toMatchTypeOf<ClerkProviderProps>();
- });
  });
 
  describe('clerkJSVariant', () => {

packages/nextjs/src/server/__tests__/__snapshots__/exports.test.ts.snap

@@ -6,8 +6,10 @@ exports[`/server public exports should not include a breaking change 1`] = `
  "authMiddleware",
  "buildClerkProps",
  "clerkClient",
+ "clerkMiddleware",
  "createClerkClient",
  "currentUser",
+ "experimental_createRouteMatcher",
  "getAuth",
  "redirectToSignIn",
  "redirectToSignUp",

packages/nextjs/src/server/authMiddleware.test.ts

@@ -33,9 +33,10 @@ jest.mock('./redirect', () => {
 });
 
 import { paths, setHeader } from '../utils';
-import { authMiddleware, createRouteMatcher, DEFAULT_CONFIG_MATCHER, DEFAULT_IGNORED_ROUTES } from './authMiddleware';
+import { authMiddleware, DEFAULT_CONFIG_MATCHER, DEFAULT_IGNORED_ROUTES } from './authMiddleware';
 // used to assert the mock
 import { clerkClient } from './clerkClient';
+import { createRouteMatcher } from './routeMatcher';
 
 /**
  * Disable console warnings about config matchers

.changeset/funny-avocados-shout.md

@@ -0,0 +1,64 @@
+---
+'@clerk/nextjs': patch
+---
+
+Introduce the new `clerkMiddleware` helper to allow for more flexibility in how Clerk is integrated into your Next.js middleware. Example usage can be found below, for more details, For more details, please see the [clerkMiddleware](https://clerk.com/docs/references/nextjs/clerkMiddleware) documentation.
+The `clerkMiddleware` helper effectively replaces the older `authMiddleware` helper, which is now considered deprecated and will be removed in the next major release.
+
+### 1. Protect a route that requires authentication
+
+```js
+import { clerkMiddleware } from '@clerk/nextjs/server';
+
+export default clerkMiddleware(auth => {
+ const { userId } = auth().protect();
+ // userId is now available for use in your route handler
+ // for page requests, calling protect will automatically redirect the user to the sign-in URL if they are not authenticated
+ return NextResponse.next();
+});
+```
+
+
+### 2. Protect a route that requires specific permissions
+
+```js
+import { clerkMiddleware } from '@clerk/nextjs/server';
+
+export default clerkMiddleware(auth => {
+ const { userId } = auth().protect({ permission: 'org:domains:delete'});
+ // userId is now available for use in your route handler
+ // for page requests, calling protect will automatically throw a notFound error if the user does not have the required permissions
+ return NextResponse.next();
+});
+```
+
+### 2. Manually redirect to sign-in URL using the redirectToSignIn helper
+
+```js
+import { clerkMiddleware } from '@clerk/nextjs/server';
+
+export default clerkMiddleware(auth => {
+ // If you want more fine-grained control, you can always use the low-level redirectToSignIn helper
+ if(!auth().userId) {
+ return auth().redirectToSignIn();
+ }
+
+ return NextResponse.next();
+});
+```
+
+This commit also introduces the experimental `createRouteMatcher` helper, which can be used to create a route matcher that matches a route against the current request. This is useful for creating custom logic based on which routes you want to handle as protected or public.
+
+```js
+import { clerkMiddleware, experimental_createRouteMatcher } from '@clerk/nextjs/server';
+
+const isProtectedRoute = experimental_createRouteMatcher([/protected.*/]);
+
+export default clerkMiddleware((auth, request) => {
+ if(isProtectedRoute(request)) {
+ auth().protect();
+ }
+
+ return NextResponse.next();
+});
+```

integration/constants.ts

@@ -38,6 +38,7 @@ export const constants = {
  */
  E2E_APP_SK: process.env.E2E_APP_SK,
  E2E_APP_PK: process.env.E2E_APP_PK,
+ E2E_CLERK_API_URL: process.env.E2E_CLERK_API_URL,
  /**
  * The version of the dependency to use, controlled programmatically.
  */

integration/models/longRunningApplication.ts

@@ -43,7 +43,7 @@ export const longRunningApplication = (params: LongRunningApplicationParams) =>
  if (!stateFile.getLongRunningApps() || [port, serverUrl, pid, appDir, env].filter(Boolean).length === 0) {
  return;
  }
- const data = stateFile.getLongRunningApps()[id];
+ const data = stateFile.getLongRunningApps()[id] || {};
  port ||= data.port;
  serverUrl ||= data.serverUrl;
  pid ||= data.pid;

integration/scripts/setup.ts

@@ -1,15 +1,15 @@
-/* eslint-disable turbo/no-undeclared-env-vars */
 import { constants } from '../constants';
 
 export const parseEnvOptions = () => {
  const appIds = constants.E2E_APP_ID ? constants.E2E_APP_ID.split(',') : [];
  const appUrl = constants.E2E_APP_URL;
  const appPk = constants.E2E_APP_PK;
  const appSk = constants.E2E_APP_SK;
+ const clerkApiUrl = constants.E2E_CLERK_API_URL;
 
  if (appIds.length && appUrl) {
  throw new Error('E2E_APP_ID cannot be used with E2E_APP_URL');
  }
 
- return { appIds, appUrl, appPk, appSk };
+ return { appIds, appUrl, appPk, appSk, clerkApiUrl };
 };

integration/testUtils/testAgainstRunningApps.ts

@@ -20,7 +20,7 @@ type RunningAppsParams = {
  */
 const runningApps = (params: RunningAppsParams = {}) => {
  const withEnv = [params.withEnv].flat().filter(Boolean);
- const { appIds, appUrl, appPk, appSk } = parseEnvOptions();
+ const { appIds, appUrl, appPk, appSk, clerkApiUrl } = parseEnvOptions();
  if (appIds.length) {
  // if appIds are provided, we only return the apps with the given ids
  const filter = app => (withEnv.length ? withEnv.includes(app.env) : true);
@@ -31,6 +31,7 @@ const runningApps = (params: RunningAppsParams = {}) => {
  const env = environmentConfig()
  .setId('tempEnv')
  .setEnvVariable('private', 'CLERK_SECRET_KEY', appSk)
+ .setEnvVariable('private', 'CLERK_API_URL', clerkApiUrl)
  .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', appPk);
  return [longRunningApplication({ id: 'standalone', env, serverUrl: appUrl, config: applicationConfig() })];
 };

integration/tests/protect.test.ts

@@ -77,7 +77,7 @@ testAgainstRunningApps({ withEnv: [appConfigs.envs.withCustomRoles] })('authoriz
  await u.page.goToRelative('/settings/auth-has');
  await expect(u.page.getByText(/User is missing permissions/i)).toBeVisible();
  await u.page.goToRelative('/settings/auth-protect');
- await expect(u.page.getByText(/this page could not be found/i)).toBeVisible();
+ await u.po.signIn.waitForMounted();
  });
 
  test('Protect in RSCs and RCCs as `viewer`', async ({ page, context }) => {

packages/backend/src/constants.ts

@@ -42,6 +42,7 @@ const Headers = {
  Host: 'host',
  ContentType: 'content-type',
  SecFetchDest: 'sec-fetch-dest',
+ Location: 'location',
 } as const;
 
 const ContentTypes = {
@@ -58,3 +59,5 @@ export const constants = {
  ContentTypes,
  QueryParameters,
 } as const;
+
+export type Constants = typeof constants;

packages/backend/src/tokens/clerkRequest.ts

@@ -1,25 +1,14 @@
 import { parse as parseCookies } from 'cookie';
 
 import { constants } from '../constants';
-
-export type WithClerkUrl<T> = T & {
- /**
- * When a NextJs app is hosted on a platform different from Vercel
- * or inside a container (Netlify, Fly.io, AWS Amplify, docker etc),
- * req.url is always set to `localhost:3000` instead of the actual host of the app.
- *
- * The `authMiddleware` uses the value of the available req.headers in order to construct
- * and use the correct url internally. This url is then exposed as `experimental_clerkUrl`,
- * intended to be used within `beforeAuth` and `afterAuth` if needed.
- */
- clerkUrl: URL;
-};
+import type { ClerkUrl, WithClerkUrl } from './clerkUrl';
+import { createClerkUrl } from './clerkUrl';
 
 class ClerkRequest extends Request {
- readonly clerkUrl: URL;
+ readonly clerkUrl: ClerkUrl;
  readonly cookies: Map<string, string>;
 
- public constructor(req: Request) {
+ public constructor(req: ClerkRequest | Request) {
  super(req, req);
  this.clerkUrl = this.deriveUrlFromHeaders(req);
  this.cookies = this.parseCookies(req);
@@ -44,7 +33,7 @@ class ClerkRequest extends Request {
  const resolvedProtocol = this.getFirstValueFromHeader(forwardedProto) ?? protocol?.replace(/[:/]/, '');
  const origin = resolvedHost && resolvedProtocol ? `${resolvedProtocol}://${resolvedHost}` : initialUrl.origin;
 
- return new URL(initialUrl.pathname + initialUrl.search, origin);
+ return createClerkUrl(initialUrl.pathname + initialUrl.search, origin);
  }
 
  private getFirstValueFromHeader(value?: string | null) {
@@ -62,7 +51,7 @@ class ClerkRequest extends Request {
 }
 
 export const createClerkRequest = (...args: ConstructorParameters<typeof ClerkRequest>): ClerkRequest => {
- return new ClerkRequest(...args);
+ return args[0] instanceof ClerkRequest ? args[0] : new ClerkRequest(...args);
 };
 
 export type { ClerkRequest };

packages/backend/src/tokens/clerkUrl.ts

@@ -0,0 +1,24 @@
+class ClerkUrl extends URL {
+ public isCrossOrigin(other: URL | string) {
+ return this.origin !== new URL(other.toString()).origin;
+ }
+}
+
+export type WithClerkUrl<T> = T & {
+ /**
+ * When a NextJs app is hosted on a platform different from Vercel
+ * or inside a container (Netlify, Fly.io, AWS Amplify, docker etc),
+ * req.url is always set to `localhost:3000` instead of the actual host of the app.
+ *
+ * The `authMiddleware` uses the value of the available req.headers in order to construct
+ * and use the correct url internally. This url is then exposed as `experimental_clerkUrl`,
+ * intended to be used within `beforeAuth` and `afterAuth` if needed.
+ */
+ clerkUrl: ClerkUrl;
+};
+
+export const createClerkUrl = (...args: ConstructorParameters<typeof ClerkUrl>): ClerkUrl => {
+ return new ClerkUrl(...args);
+};
+
+export type { ClerkUrl };

packages/fastify/src/__snapshots__/constants.test.ts.snap

@@ -24,6 +24,7 @@ exports[`constants from environment variables 1`] = `
  "ForwardedPort": "x-forwarded-port",
  "ForwardedProto": "x-forwarded-proto",
  "Host": "host",
+ "Location": "location",
  "Origin": "origin",
  "Referrer": "referer",
  "SecFetchDest": "sec-fetch-dest",

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

@@ -1,14 +1,12 @@
-import type { ClerkProviderOptionsWrapper } from '@clerk/clerk-react';
-import type { InitialState } from '@clerk/types';
+import type { InitialState, Without } from '@clerk/types';
 import React from 'react';
 
+import type { NextClerkProviderProps } from '../../types';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
 import { ClientClerkProvider } from '../client/ClerkProvider';
 import { initialState } from './auth';
 
-type NextAppClerkProviderProps = ClerkProviderOptionsWrapper;
-
-export function ClerkProvider(props: NextAppClerkProviderProps) {
+export function ClerkProvider(props: Without<NextClerkProviderProps, '__unstable_invokeMiddlewareOnAuthStateChange'>) {
  const { children, ...rest } = props;
  const state = initialState()?.__clerk_ssr_state as InitialState;
 

packages/nextjs/src/app-router/server/auth.ts

@@ -1,18 +1,20 @@
 import type { AuthObject } from '@clerk/backend/internal';
+import { notFound, redirect } from 'next/navigation';
 
 import { authAuthHeaderMissing } from '../../server/errors';
 import { buildClerkProps, createGetAuth } from '../../server/getAuth';
-import type { AuthProtect } from './protect';
-import { createProtect } from './protect';
+import type { AuthProtect } from '../../server/protect';
+import { createProtect } from '../../server/protect';
 import { buildRequestLike } from './utils';
 
 export const auth = (): AuthObject & { protect: AuthProtect } => {
+ const request = buildRequestLike();
  const authObject = createGetAuth({
  debugLoggerName: 'auth()',
  noAuthStatusMessage: authAuthHeaderMissing(),
- })(buildRequestLike());
+ })(request);
 
- return Object.assign(authObject, { protect: createProtect(authObject) });
+ return Object.assign(authObject, { protect: createProtect({ request, authObject, notFound, redirect }) });
 };
 
 export const initialState = () => {

packages/nextjs/src/constants.ts

@@ -2,6 +2,8 @@ const Headers = {
  NextRewrite: 'x-middleware-rewrite',
  NextResume: 'x-middleware-next',
  NextRedirect: 'Location',
+ NextUrl: 'next-url',
+ NextAction: 'next-action',
 } as const;
 
 export const constants = {

packages/nextjs/src/pages/__tests__/index.test.tsx

@@ -31,27 +31,6 @@ describe('ClerkProvider', () => {
  it('domain + isSatellite (satellite app)', () => {
  expectTypeOf({ ...defaultProps, domain: 'test', isSatellite: true }).toMatchTypeOf<ClerkProviderProps>();
  });
-
- it('only domain is not allowed', () => {
- expectTypeOf({ ...defaultProps, domain: 'test' }).not.toMatchTypeOf<ClerkProviderProps>();
- });
-
- it('only isSatellite is not allowed', () => {
- expectTypeOf({ ...defaultProps, isSatellite: true }).not.toMatchTypeOf<ClerkProviderProps>();
- });
-
- it('proxyUrl + domain is not allowed', () => {
- expectTypeOf({ ...defaultProps, proxyUrl: 'test', domain: 'test' }).not.toMatchTypeOf<ClerkProviderProps>();
- });
-
- it('proxyUrl + domain + isSatellite is not allowed', () => {
- expectTypeOf({
- ...defaultProps,
- proxyUrl: 'test',
- domain: 'test',
- isSatellite: true,
- }).not.toMatchTypeOf<ClerkProviderProps>();
- });
  });
 
  describe('clerkJSVariant', () => {

packages/nextjs/src/server/__tests__/__snapshots__/exports.test.ts.snap

@@ -6,8 +6,10 @@ exports[`/server public exports should not include a breaking change 1`] = `
  "authMiddleware",
  "buildClerkProps",
  "clerkClient",
+ "clerkMiddleware",
  "createClerkClient",
  "currentUser",
+ "experimental_createRouteMatcher",
  "getAuth",
  "redirectToSignIn",
  "redirectToSignUp",

packages/nextjs/src/server/authMiddleware.test.ts

@@ -33,9 +33,10 @@ jest.mock('./redirect', () => {
 });
 
 import { paths, setHeader } from '../utils';
-import { authMiddleware, createRouteMatcher, DEFAULT_CONFIG_MATCHER, DEFAULT_IGNORED_ROUTES } from './authMiddleware';
+import { authMiddleware, DEFAULT_CONFIG_MATCHER, DEFAULT_IGNORED_ROUTES } from './authMiddleware';
 // used to assert the mock
 import { clerkClient } from './clerkClient';
+import { createRouteMatcher } from './routeMatcher';
 
 /**
  * Disable console warnings about config matchers

.changeset/funny-avocados-shout.md

@@ -0,0 +1,64 @@
+---
+'@clerk/nextjs': patch
+---
+
+Introduce the new `clerkMiddleware` helper to allow for more flexibility in how Clerk is integrated into your Next.js middleware. Example usage can be found below, for more details, For more details, please see the [clerkMiddleware](https://clerk.com/docs/references/nextjs/clerkMiddleware) documentation.
+The `clerkMiddleware` helper effectively replaces the older `authMiddleware` helper, which is now considered deprecated and will be removed in the next major release.
+
+### 1. Protect a route that requires authentication
+
+```js
+import { clerkMiddleware } from '@clerk/nextjs/server';
+
+export default clerkMiddleware(auth => {
+ const { userId } = auth().protect();
+ // userId is now available for use in your route handler
+ // for page requests, calling protect will automatically redirect the user to the sign-in URL if they are not authenticated
+ return NextResponse.next();
+});
+```
+
+
+### 2. Protect a route that requires specific permissions
+
+```js
+import { clerkMiddleware } from '@clerk/nextjs/server';
+
+export default clerkMiddleware(auth => {
+ const { userId } = auth().protect({ permission: 'org:domains:delete'});
+ // userId is now available for use in your route handler
+ // for page requests, calling protect will automatically throw a notFound error if the user does not have the required permissions
+ return NextResponse.next();
+});
+```
+
+### 2. Manually redirect to sign-in URL using the redirectToSignIn helper
+
+```js
+import { clerkMiddleware } from '@clerk/nextjs/server';
+
+export default clerkMiddleware(auth => {
+ // If you want more fine-grained control, you can always use the low-level redirectToSignIn helper
+ if(!auth().userId) {
+ return auth().redirectToSignIn();
+ }
+
+ return NextResponse.next();
+});
+```
+
+This commit also introduces the experimental `createRouteMatcher` helper, which can be used to create a route matcher that matches a route against the current request. This is useful for creating custom logic based on which routes you want to handle as protected or public.
+
+```js
+import { clerkMiddleware, experimental_createRouteMatcher } from '@clerk/nextjs/server';
+
+const isProtectedRoute = experimental_createRouteMatcher([/protected.*/]);
+
+export default clerkMiddleware((auth, request) => {
+ if(isProtectedRoute(request)) {
+ auth().protect();
+ }
+
+ return NextResponse.next();
+});
+```

integration/constants.ts

@@ -38,6 +38,7 @@ export const constants = {
  */
  E2E_APP_SK: process.env.E2E_APP_SK,
  E2E_APP_PK: process.env.E2E_APP_PK,
+ E2E_CLERK_API_URL: process.env.E2E_CLERK_API_URL,
  /**
  * The version of the dependency to use, controlled programmatically.
  */

integration/models/longRunningApplication.ts

@@ -43,7 +43,7 @@ export const longRunningApplication = (params: LongRunningApplicationParams) =>
  if (!stateFile.getLongRunningApps() || [port, serverUrl, pid, appDir, env].filter(Boolean).length === 0) {
  return;
  }
- const data = stateFile.getLongRunningApps()[id];
+ const data = stateFile.getLongRunningApps()[id] || {};
  port ||= data.port;
  serverUrl ||= data.serverUrl;
  pid ||= data.pid;

integration/scripts/setup.ts

@@ -1,15 +1,15 @@
-/* eslint-disable turbo/no-undeclared-env-vars */
 import { constants } from '../constants';
 
 export const parseEnvOptions = () => {
  const appIds = constants.E2E_APP_ID ? constants.E2E_APP_ID.split(',') : [];
  const appUrl = constants.E2E_APP_URL;
  const appPk = constants.E2E_APP_PK;
  const appSk = constants.E2E_APP_SK;
+ const clerkApiUrl = constants.E2E_CLERK_API_URL;
 
  if (appIds.length && appUrl) {
  throw new Error('E2E_APP_ID cannot be used with E2E_APP_URL');
  }
 
- return { appIds, appUrl, appPk, appSk };
+ return { appIds, appUrl, appPk, appSk, clerkApiUrl };
 };

integration/testUtils/testAgainstRunningApps.ts

@@ -20,7 +20,7 @@ type RunningAppsParams = {
  */
 const runningApps = (params: RunningAppsParams = {}) => {
  const withEnv = [params.withEnv].flat().filter(Boolean);
- const { appIds, appUrl, appPk, appSk } = parseEnvOptions();
+ const { appIds, appUrl, appPk, appSk, clerkApiUrl } = parseEnvOptions();
  if (appIds.length) {
  // if appIds are provided, we only return the apps with the given ids
  const filter = app => (withEnv.length ? withEnv.includes(app.env) : true);
@@ -31,6 +31,7 @@ const runningApps = (params: RunningAppsParams = {}) => {
  const env = environmentConfig()
  .setId('tempEnv')
  .setEnvVariable('private', 'CLERK_SECRET_KEY', appSk)
+ .setEnvVariable('private', 'CLERK_API_URL', clerkApiUrl)
  .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', appPk);
  return [longRunningApplication({ id: 'standalone', env, serverUrl: appUrl, config: applicationConfig() })];
 };

integration/tests/protect.test.ts

@@ -77,7 +77,7 @@ testAgainstRunningApps({ withEnv: [appConfigs.envs.withCustomRoles] })('authoriz
  await u.page.goToRelative('/settings/auth-has');
  await expect(u.page.getByText(/User is missing permissions/i)).toBeVisible();
  await u.page.goToRelative('/settings/auth-protect');
- await expect(u.page.getByText(/this page could not be found/i)).toBeVisible();
+ await u.po.signIn.waitForMounted();
  });
 
  test('Protect in RSCs and RCCs as `viewer`', async ({ page, context }) => {

packages/backend/src/constants.ts

@@ -42,6 +42,7 @@ const Headers = {
  Host: 'host',
  ContentType: 'content-type',
  SecFetchDest: 'sec-fetch-dest',
+ Location: 'location',
 } as const;
 
 const ContentTypes = {
@@ -58,3 +59,5 @@ export const constants = {
  ContentTypes,
  QueryParameters,
 } as const;
+
+export type Constants = typeof constants;

packages/backend/src/tokens/clerkRequest.ts

@@ -1,25 +1,14 @@
 import { parse as parseCookies } from 'cookie';
 
 import { constants } from '../constants';
-
-export type WithClerkUrl<T> = T & {
- /**
- * When a NextJs app is hosted on a platform different from Vercel
- * or inside a container (Netlify, Fly.io, AWS Amplify, docker etc),
- * req.url is always set to `localhost:3000` instead of the actual host of the app.
- *
- * The `authMiddleware` uses the value of the available req.headers in order to construct
- * and use the correct url internally. This url is then exposed as `experimental_clerkUrl`,
- * intended to be used within `beforeAuth` and `afterAuth` if needed.
- */
- clerkUrl: URL;
-};
+import type { ClerkUrl, WithClerkUrl } from './clerkUrl';
+import { createClerkUrl } from './clerkUrl';
 
 class ClerkRequest extends Request {
- readonly clerkUrl: URL;
+ readonly clerkUrl: ClerkUrl;
  readonly cookies: Map<string, string>;
 
- public constructor(req: Request) {
+ public constructor(req: ClerkRequest | Request) {
  super(req, req);
  this.clerkUrl = this.deriveUrlFromHeaders(req);
  this.cookies = this.parseCookies(req);
@@ -44,7 +33,7 @@ class ClerkRequest extends Request {
  const resolvedProtocol = this.getFirstValueFromHeader(forwardedProto) ?? protocol?.replace(/[:/]/, '');
  const origin = resolvedHost && resolvedProtocol ? `${resolvedProtocol}://${resolvedHost}` : initialUrl.origin;
 
- return new URL(initialUrl.pathname + initialUrl.search, origin);
+ return createClerkUrl(initialUrl.pathname + initialUrl.search, origin);
  }
 
  private getFirstValueFromHeader(value?: string | null) {
@@ -62,7 +51,7 @@ class ClerkRequest extends Request {
 }
 
 export const createClerkRequest = (...args: ConstructorParameters<typeof ClerkRequest>): ClerkRequest => {
- return new ClerkRequest(...args);
+ return args[0] instanceof ClerkRequest ? args[0] : new ClerkRequest(...args);
 };
 
 export type { ClerkRequest };

packages/backend/src/tokens/clerkUrl.ts

@@ -0,0 +1,24 @@
+class ClerkUrl extends URL {
+ public isCrossOrigin(other: URL | string) {
+ return this.origin !== new URL(other.toString()).origin;
+ }
+}
+
+export type WithClerkUrl<T> = T & {
+ /**
+ * When a NextJs app is hosted on a platform different from Vercel
+ * or inside a container (Netlify, Fly.io, AWS Amplify, docker etc),
+ * req.url is always set to `localhost:3000` instead of the actual host of the app.
+ *
+ * The `authMiddleware` uses the value of the available req.headers in order to construct
+ * and use the correct url internally. This url is then exposed as `experimental_clerkUrl`,
+ * intended to be used within `beforeAuth` and `afterAuth` if needed.
+ */
+ clerkUrl: ClerkUrl;
+};
+
+export const createClerkUrl = (...args: ConstructorParameters<typeof ClerkUrl>): ClerkUrl => {
+ return new ClerkUrl(...args);
+};
+
+export type { ClerkUrl };

packages/fastify/src/__snapshots__/constants.test.ts.snap

@@ -24,6 +24,7 @@ exports[`constants from environment variables 1`] = `
  "ForwardedPort": "x-forwarded-port",
  "ForwardedProto": "x-forwarded-proto",
  "Host": "host",
+ "Location": "location",
  "Origin": "origin",
  "Referrer": "referer",
  "SecFetchDest": "sec-fetch-dest",

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

@@ -1,14 +1,12 @@
-import type { ClerkProviderOptionsWrapper } from '@clerk/clerk-react';
-import type { InitialState } from '@clerk/types';
+import type { InitialState, Without } from '@clerk/types';
 import React from 'react';
 
+import type { NextClerkProviderProps } from '../../types';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
 import { ClientClerkProvider } from '../client/ClerkProvider';
 import { initialState } from './auth';
 
-type NextAppClerkProviderProps = ClerkProviderOptionsWrapper;
-
-export function ClerkProvider(props: NextAppClerkProviderProps) {
+export function ClerkProvider(props: Without<NextClerkProviderProps, '__unstable_invokeMiddlewareOnAuthStateChange'>) {
  const { children, ...rest } = props;
  const state = initialState()?.__clerk_ssr_state as InitialState;
 

packages/nextjs/src/app-router/server/auth.ts

@@ -1,18 +1,20 @@
 import type { AuthObject } from '@clerk/backend/internal';
+import { notFound, redirect } from 'next/navigation';
 
 import { authAuthHeaderMissing } from '../../server/errors';
 import { buildClerkProps, createGetAuth } from '../../server/getAuth';
-import type { AuthProtect } from './protect';
-import { createProtect } from './protect';
+import type { AuthProtect } from '../../server/protect';
+import { createProtect } from '../../server/protect';
 import { buildRequestLike } from './utils';
 
 export const auth = (): AuthObject & { protect: AuthProtect } => {
+ const request = buildRequestLike();
  const authObject = createGetAuth({
  debugLoggerName: 'auth()',
  noAuthStatusMessage: authAuthHeaderMissing(),
- })(buildRequestLike());
+ })(request);
 
- return Object.assign(authObject, { protect: createProtect(authObject) });
+ return Object.assign(authObject, { protect: createProtect({ request, authObject, notFound, redirect }) });
 };
 
 export const initialState = () => {

packages/nextjs/src/constants.ts

@@ -2,6 +2,8 @@ const Headers = {
  NextRewrite: 'x-middleware-rewrite',
  NextResume: 'x-middleware-next',
  NextRedirect: 'Location',
+ NextUrl: 'next-url',
+ NextAction: 'next-action',
 } as const;
 
 export const constants = {

packages/nextjs/src/pages/__tests__/index.test.tsx

@@ -31,27 +31,6 @@ describe('ClerkProvider', () => {
  it('domain + isSatellite (satellite app)', () => {
  expectTypeOf({ ...defaultProps, domain: 'test', isSatellite: true }).toMatchTypeOf<ClerkProviderProps>();
  });
-
- it('only domain is not allowed', () => {
- expectTypeOf({ ...defaultProps, domain: 'test' }).not.toMatchTypeOf<ClerkProviderProps>();
- });
-
- it('only isSatellite is not allowed', () => {
- expectTypeOf({ ...defaultProps, isSatellite: true }).not.toMatchTypeOf<ClerkProviderProps>();
- });
-
- it('proxyUrl + domain is not allowed', () => {
- expectTypeOf({ ...defaultProps, proxyUrl: 'test', domain: 'test' }).not.toMatchTypeOf<ClerkProviderProps>();
- });
-
- it('proxyUrl + domain + isSatellite is not allowed', () => {
- expectTypeOf({
- ...defaultProps,
- proxyUrl: 'test',
- domain: 'test',
- isSatellite: true,
- }).not.toMatchTypeOf<ClerkProviderProps>();
- });
  });
 
  describe('clerkJSVariant', () => {

packages/nextjs/src/server/__tests__/__snapshots__/exports.test.ts.snap

@@ -6,8 +6,10 @@ exports[`/server public exports should not include a breaking change 1`] = `
  "authMiddleware",
  "buildClerkProps",
  "clerkClient",
+ "clerkMiddleware",
  "createClerkClient",
  "currentUser",
+ "experimental_createRouteMatcher",
  "getAuth",
  "redirectToSignIn",
  "redirectToSignUp",

packages/nextjs/src/server/authMiddleware.test.ts

@@ -33,9 +33,10 @@ jest.mock('./redirect', () => {
 });
 
 import { paths, setHeader } from '../utils';
-import { authMiddleware, createRouteMatcher, DEFAULT_CONFIG_MATCHER, DEFAULT_IGNORED_ROUTES } from './authMiddleware';
+import { authMiddleware, DEFAULT_CONFIG_MATCHER, DEFAULT_IGNORED_ROUTES } from './authMiddleware';
 // used to assert the mock
 import { clerkClient } from './clerkClient';
+import { createRouteMatcher } from './routeMatcher';
 
 /**
  * Disable console warnings about config matchers

.changeset/funny-avocados-shout.md

@@ -0,0 +1,64 @@
+---
+'@clerk/nextjs': patch
+---
+
+Introduce the new `clerkMiddleware` helper to allow for more flexibility in how Clerk is integrated into your Next.js middleware. Example usage can be found below, for more details, For more details, please see the [clerkMiddleware](https://clerk.com/docs/references/nextjs/clerkMiddleware) documentation.
+The `clerkMiddleware` helper effectively replaces the older `authMiddleware` helper, which is now considered deprecated and will be removed in the next major release.
+
+### 1. Protect a route that requires authentication
+
+```js
+import { clerkMiddleware } from '@clerk/nextjs/server';
+
+export default clerkMiddleware(auth => {
+ const { userId } = auth().protect();
+ // userId is now available for use in your route handler
+ // for page requests, calling protect will automatically redirect the user to the sign-in URL if they are not authenticated
+ return NextResponse.next();
+});
+```
+
+
+### 2. Protect a route that requires specific permissions
+
+```js
+import { clerkMiddleware } from '@clerk/nextjs/server';
+
+export default clerkMiddleware(auth => {
+ const { userId } = auth().protect({ permission: 'org:domains:delete'});
+ // userId is now available for use in your route handler
+ // for page requests, calling protect will automatically throw a notFound error if the user does not have the required permissions
+ return NextResponse.next();
+});
+```
+
+### 2. Manually redirect to sign-in URL using the redirectToSignIn helper
+
+```js
+import { clerkMiddleware } from '@clerk/nextjs/server';
+
+export default clerkMiddleware(auth => {
+ // If you want more fine-grained control, you can always use the low-level redirectToSignIn helper
+ if(!auth().userId) {
+ return auth().redirectToSignIn();
+ }
+
+ return NextResponse.next();
+});
+```
+
+This commit also introduces the experimental `createRouteMatcher` helper, which can be used to create a route matcher that matches a route against the current request. This is useful for creating custom logic based on which routes you want to handle as protected or public.
+
+```js
+import { clerkMiddleware, experimental_createRouteMatcher } from '@clerk/nextjs/server';
+
+const isProtectedRoute = experimental_createRouteMatcher([/protected.*/]);
+
+export default clerkMiddleware((auth, request) => {
+ if(isProtectedRoute(request)) {
+ auth().protect();
+ }
+
+ return NextResponse.next();
+});
+```

integration/constants.ts

@@ -38,6 +38,7 @@ export const constants = {
  */
  E2E_APP_SK: process.env.E2E_APP_SK,
  E2E_APP_PK: process.env.E2E_APP_PK,
+ E2E_CLERK_API_URL: process.env.E2E_CLERK_API_URL,
  /**
  * The version of the dependency to use, controlled programmatically.
  */

integration/models/longRunningApplication.ts

@@ -43,7 +43,7 @@ export const longRunningApplication = (params: LongRunningApplicationParams) =>
  if (!stateFile.getLongRunningApps() || [port, serverUrl, pid, appDir, env].filter(Boolean).length === 0) {
  return;
  }
- const data = stateFile.getLongRunningApps()[id];
+ const data = stateFile.getLongRunningApps()[id] || {};
  port ||= data.port;
  serverUrl ||= data.serverUrl;
  pid ||= data.pid;

integration/scripts/setup.ts

@@ -1,15 +1,15 @@
-/* eslint-disable turbo/no-undeclared-env-vars */
 import { constants } from '../constants';
 
 export const parseEnvOptions = () => {
  const appIds = constants.E2E_APP_ID ? constants.E2E_APP_ID.split(',') : [];
  const appUrl = constants.E2E_APP_URL;
  const appPk = constants.E2E_APP_PK;
  const appSk = constants.E2E_APP_SK;
+ const clerkApiUrl = constants.E2E_CLERK_API_URL;
 
  if (appIds.length && appUrl) {
  throw new Error('E2E_APP_ID cannot be used with E2E_APP_URL');
  }
 
- return { appIds, appUrl, appPk, appSk };
+ return { appIds, appUrl, appPk, appSk, clerkApiUrl };
 };

integration/testUtils/testAgainstRunningApps.ts

@@ -20,7 +20,7 @@ type RunningAppsParams = {
  */
 const runningApps = (params: RunningAppsParams = {}) => {
  const withEnv = [params.withEnv].flat().filter(Boolean);
- const { appIds, appUrl, appPk, appSk } = parseEnvOptions();
+ const { appIds, appUrl, appPk, appSk, clerkApiUrl } = parseEnvOptions();
  if (appIds.length) {
  // if appIds are provided, we only return the apps with the given ids
  const filter = app => (withEnv.length ? withEnv.includes(app.env) : true);
@@ -31,6 +31,7 @@ const runningApps = (params: RunningAppsParams = {}) => {
  const env = environmentConfig()
  .setId('tempEnv')
  .setEnvVariable('private', 'CLERK_SECRET_KEY', appSk)
+ .setEnvVariable('private', 'CLERK_API_URL', clerkApiUrl)
  .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', appPk);
  return [longRunningApplication({ id: 'standalone', env, serverUrl: appUrl, config: applicationConfig() })];
 };

integration/tests/protect.test.ts

@@ -77,7 +77,7 @@ testAgainstRunningApps({ withEnv: [appConfigs.envs.withCustomRoles] })('authoriz
  await u.page.goToRelative('/settings/auth-has');
  await expect(u.page.getByText(/User is missing permissions/i)).toBeVisible();
  await u.page.goToRelative('/settings/auth-protect');
- await expect(u.page.getByText(/this page could not be found/i)).toBeVisible();
+ await u.po.signIn.waitForMounted();
  });
 
  test('Protect in RSCs and RCCs as `viewer`', async ({ page, context }) => {

packages/backend/src/constants.ts

@@ -42,6 +42,7 @@ const Headers = {
  Host: 'host',
  ContentType: 'content-type',
  SecFetchDest: 'sec-fetch-dest',
+ Location: 'location',
 } as const;
 
 const ContentTypes = {
@@ -58,3 +59,5 @@ export const constants = {
  ContentTypes,
  QueryParameters,
 } as const;
+
+export type Constants = typeof constants;

packages/backend/src/tokens/clerkRequest.ts

@@ -1,25 +1,14 @@
 import { parse as parseCookies } from 'cookie';
 
 import { constants } from '../constants';
-
-export type WithClerkUrl<T> = T & {
- /**
- * When a NextJs app is hosted on a platform different from Vercel
- * or inside a container (Netlify, Fly.io, AWS Amplify, docker etc),
- * req.url is always set to `localhost:3000` instead of the actual host of the app.
- *
- * The `authMiddleware` uses the value of the available req.headers in order to construct
- * and use the correct url internally. This url is then exposed as `experimental_clerkUrl`,
- * intended to be used within `beforeAuth` and `afterAuth` if needed.
- */
- clerkUrl: URL;
-};
+import type { ClerkUrl, WithClerkUrl } from './clerkUrl';
+import { createClerkUrl } from './clerkUrl';
 
 class ClerkRequest extends Request {
- readonly clerkUrl: URL;
+ readonly clerkUrl: ClerkUrl;
  readonly cookies: Map<string, string>;
 
- public constructor(req: Request) {
+ public constructor(req: ClerkRequest | Request) {
  super(req, req);
  this.clerkUrl = this.deriveUrlFromHeaders(req);
  this.cookies = this.parseCookies(req);
@@ -44,7 +33,7 @@ class ClerkRequest extends Request {
  const resolvedProtocol = this.getFirstValueFromHeader(forwardedProto) ?? protocol?.replace(/[:/]/, '');
  const origin = resolvedHost && resolvedProtocol ? `${resolvedProtocol}://${resolvedHost}` : initialUrl.origin;
 
- return new URL(initialUrl.pathname + initialUrl.search, origin);
+ return createClerkUrl(initialUrl.pathname + initialUrl.search, origin);
  }
 
  private getFirstValueFromHeader(value?: string | null) {
@@ -62,7 +51,7 @@ class ClerkRequest extends Request {
 }
 
 export const createClerkRequest = (...args: ConstructorParameters<typeof ClerkRequest>): ClerkRequest => {
- return new ClerkRequest(...args);
+ return args[0] instanceof ClerkRequest ? args[0] : new ClerkRequest(...args);
 };
 
 export type { ClerkRequest };

packages/backend/src/tokens/clerkUrl.ts

@@ -0,0 +1,24 @@
+class ClerkUrl extends URL {
+ public isCrossOrigin(other: URL | string) {
+ return this.origin !== new URL(other.toString()).origin;
+ }
+}
+
+export type WithClerkUrl<T> = T & {
+ /**
+ * When a NextJs app is hosted on a platform different from Vercel
+ * or inside a container (Netlify, Fly.io, AWS Amplify, docker etc),
+ * req.url is always set to `localhost:3000` instead of the actual host of the app.
+ *
+ * The `authMiddleware` uses the value of the available req.headers in order to construct
+ * and use the correct url internally. This url is then exposed as `experimental_clerkUrl`,
+ * intended to be used within `beforeAuth` and `afterAuth` if needed.
+ */
+ clerkUrl: ClerkUrl;
+};
+
+export const createClerkUrl = (...args: ConstructorParameters<typeof ClerkUrl>): ClerkUrl => {
+ return new ClerkUrl(...args);
+};
+
+export type { ClerkUrl };

packages/fastify/src/__snapshots__/constants.test.ts.snap

@@ -24,6 +24,7 @@ exports[`constants from environment variables 1`] = `
  "ForwardedPort": "x-forwarded-port",
  "ForwardedProto": "x-forwarded-proto",
  "Host": "host",
+ "Location": "location",
  "Origin": "origin",
  "Referrer": "referer",
  "SecFetchDest": "sec-fetch-dest",

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

@@ -1,14 +1,12 @@
-import type { ClerkProviderOptionsWrapper } from '@clerk/clerk-react';
-import type { InitialState } from '@clerk/types';
+import type { InitialState, Without } from '@clerk/types';
 import React from 'react';
 
+import type { NextClerkProviderProps } from '../../types';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
 import { ClientClerkProvider } from '../client/ClerkProvider';
 import { initialState } from './auth';
 
-type NextAppClerkProviderProps = ClerkProviderOptionsWrapper;
-
-export function ClerkProvider(props: NextAppClerkProviderProps) {
+export function ClerkProvider(props: Without<NextClerkProviderProps, '__unstable_invokeMiddlewareOnAuthStateChange'>) {
  const { children, ...rest } = props;
  const state = initialState()?.__clerk_ssr_state as InitialState;
 

packages/nextjs/src/app-router/server/auth.ts

@@ -1,18 +1,20 @@
 import type { AuthObject } from '@clerk/backend/internal';
+import { notFound, redirect } from 'next/navigation';
 
 import { authAuthHeaderMissing } from '../../server/errors';
 import { buildClerkProps, createGetAuth } from '../../server/getAuth';
-import type { AuthProtect } from './protect';
-import { createProtect } from './protect';
+import type { AuthProtect } from '../../server/protect';
+import { createProtect } from '../../server/protect';
 import { buildRequestLike } from './utils';
 
 export const auth = (): AuthObject & { protect: AuthProtect } => {
+ const request = buildRequestLike();
  const authObject = createGetAuth({
  debugLoggerName: 'auth()',
  noAuthStatusMessage: authAuthHeaderMissing(),
- })(buildRequestLike());
+ })(request);
 
- return Object.assign(authObject, { protect: createProtect(authObject) });
+ return Object.assign(authObject, { protect: createProtect({ request, authObject, notFound, redirect }) });
 };
 
 export const initialState = () => {

packages/nextjs/src/constants.ts

@@ -2,6 +2,8 @@ const Headers = {
  NextRewrite: 'x-middleware-rewrite',
  NextResume: 'x-middleware-next',
  NextRedirect: 'Location',
+ NextUrl: 'next-url',
+ NextAction: 'next-action',
 } as const;
 
 export const constants = {

packages/nextjs/src/pages/__tests__/index.test.tsx

@@ -31,27 +31,6 @@ describe('ClerkProvider', () => {
  it('domain + isSatellite (satellite app)', () => {
  expectTypeOf({ ...defaultProps, domain: 'test', isSatellite: true }).toMatchTypeOf<ClerkProviderProps>();
  });
-
- it('only domain is not allowed', () => {
- expectTypeOf({ ...defaultProps, domain: 'test' }).not.toMatchTypeOf<ClerkProviderProps>();
- });
-
- it('only isSatellite is not allowed', () => {
- expectTypeOf({ ...defaultProps, isSatellite: true }).not.toMatchTypeOf<ClerkProviderProps>();
- });
-
- it('proxyUrl + domain is not allowed', () => {
- expectTypeOf({ ...defaultProps, proxyUrl: 'test', domain: 'test' }).not.toMatchTypeOf<ClerkProviderProps>();
- });
-
- it('proxyUrl + domain + isSatellite is not allowed', () => {
- expectTypeOf({
- ...defaultProps,
- proxyUrl: 'test',
- domain: 'test',
- isSatellite: true,
- }).not.toMatchTypeOf<ClerkProviderProps>();
- });
  });
 
  describe('clerkJSVariant', () => {

packages/nextjs/src/server/__tests__/__snapshots__/exports.test.ts.snap

@@ -6,8 +6,10 @@ exports[`/server public exports should not include a breaking change 1`] = `
  "authMiddleware",
  "buildClerkProps",
  "clerkClient",
+ "clerkMiddleware",
  "createClerkClient",
  "currentUser",
+ "experimental_createRouteMatcher",
  "getAuth",
  "redirectToSignIn",
  "redirectToSignUp",

packages/nextjs/src/server/authMiddleware.test.ts

@@ -33,9 +33,10 @@ jest.mock('./redirect', () => {
 });
 
 import { paths, setHeader } from '../utils';
-import { authMiddleware, createRouteMatcher, DEFAULT_CONFIG_MATCHER, DEFAULT_IGNORED_ROUTES } from './authMiddleware';
+import { authMiddleware, DEFAULT_CONFIG_MATCHER, DEFAULT_IGNORED_ROUTES } from './authMiddleware';
 // used to assert the mock
 import { clerkClient } from './clerkClient';
+import { createRouteMatcher } from './routeMatcher';
 
 /**
  * Disable console warnings about config matchers

.changeset/funny-avocados-shout.md

@@ -0,0 +1,64 @@
+---
+'@clerk/nextjs': patch
+---
+
+Introduce the new `clerkMiddleware` helper to allow for more flexibility in how Clerk is integrated into your Next.js middleware. Example usage can be found below, for more details, For more details, please see the [clerkMiddleware](https://clerk.com/docs/references/nextjs/clerkMiddleware) documentation.
+The `clerkMiddleware` helper effectively replaces the older `authMiddleware` helper, which is now considered deprecated and will be removed in the next major release.
+
+### 1. Protect a route that requires authentication
+
+```js
+import { clerkMiddleware } from '@clerk/nextjs/server';
+
+export default clerkMiddleware(auth => {
+ const { userId } = auth().protect();
+ // userId is now available for use in your route handler
+ // for page requests, calling protect will automatically redirect the user to the sign-in URL if they are not authenticated
+ return NextResponse.next();
+});
+```
+
+
+### 2. Protect a route that requires specific permissions
+
+```js
+import { clerkMiddleware } from '@clerk/nextjs/server';
+
+export default clerkMiddleware(auth => {
+ const { userId } = auth().protect({ permission: 'org:domains:delete'});
+ // userId is now available for use in your route handler
+ // for page requests, calling protect will automatically throw a notFound error if the user does not have the required permissions
+ return NextResponse.next();
+});
+```
+
+### 2. Manually redirect to sign-in URL using the redirectToSignIn helper
+
+```js
+import { clerkMiddleware } from '@clerk/nextjs/server';
+
+export default clerkMiddleware(auth => {
+ // If you want more fine-grained control, you can always use the low-level redirectToSignIn helper
+ if(!auth().userId) {
+ return auth().redirectToSignIn();
+ }
+
+ return NextResponse.next();
+});
+```
+
+This commit also introduces the experimental `createRouteMatcher` helper, which can be used to create a route matcher that matches a route against the current request. This is useful for creating custom logic based on which routes you want to handle as protected or public.
+
+```js
+import { clerkMiddleware, experimental_createRouteMatcher } from '@clerk/nextjs/server';
+
+const isProtectedRoute = experimental_createRouteMatcher([/protected.*/]);
+
+export default clerkMiddleware((auth, request) => {
+ if(isProtectedRoute(request)) {
+ auth().protect();
+ }
+
+ return NextResponse.next();
+});
+```

integration/constants.ts

@@ -38,6 +38,7 @@ export const constants = {
  */
  E2E_APP_SK: process.env.E2E_APP_SK,
  E2E_APP_PK: process.env.E2E_APP_PK,
+ E2E_CLERK_API_URL: process.env.E2E_CLERK_API_URL,
  /**
  * The version of the dependency to use, controlled programmatically.
  */

integration/models/longRunningApplication.ts

@@ -43,7 +43,7 @@ export const longRunningApplication = (params: LongRunningApplicationParams) =>
  if (!stateFile.getLongRunningApps() || [port, serverUrl, pid, appDir, env].filter(Boolean).length === 0) {
  return;
  }
- const data = stateFile.getLongRunningApps()[id];
+ const data = stateFile.getLongRunningApps()[id] || {};
  port ||= data.port;
  serverUrl ||= data.serverUrl;
  pid ||= data.pid;

integration/scripts/setup.ts

@@ -1,15 +1,15 @@
-/* eslint-disable turbo/no-undeclared-env-vars */
 import { constants } from '../constants';
 
 export const parseEnvOptions = () => {
  const appIds = constants.E2E_APP_ID ? constants.E2E_APP_ID.split(',') : [];
  const appUrl = constants.E2E_APP_URL;
  const appPk = constants.E2E_APP_PK;
  const appSk = constants.E2E_APP_SK;
+ const clerkApiUrl = constants.E2E_CLERK_API_URL;
 
  if (appIds.length && appUrl) {
  throw new Error('E2E_APP_ID cannot be used with E2E_APP_URL');
  }
 
- return { appIds, appUrl, appPk, appSk };
+ return { appIds, appUrl, appPk, appSk, clerkApiUrl };
 };

integration/testUtils/testAgainstRunningApps.ts

@@ -20,7 +20,7 @@ type RunningAppsParams = {
  */
 const runningApps = (params: RunningAppsParams = {}) => {
  const withEnv = [params.withEnv].flat().filter(Boolean);
- const { appIds, appUrl, appPk, appSk } = parseEnvOptions();
+ const { appIds, appUrl, appPk, appSk, clerkApiUrl } = parseEnvOptions();
  if (appIds.length) {
  // if appIds are provided, we only return the apps with the given ids
  const filter = app => (withEnv.length ? withEnv.includes(app.env) : true);
@@ -31,6 +31,7 @@ const runningApps = (params: RunningAppsParams = {}) => {
  const env = environmentConfig()
  .setId('tempEnv')
  .setEnvVariable('private', 'CLERK_SECRET_KEY', appSk)
+ .setEnvVariable('private', 'CLERK_API_URL', clerkApiUrl)
  .setEnvVariable('public', 'CLERK_PUBLISHABLE_KEY', appPk);
  return [longRunningApplication({ id: 'standalone', env, serverUrl: appUrl, config: applicationConfig() })];
 };

integration/tests/protect.test.ts

@@ -77,7 +77,7 @@ testAgainstRunningApps({ withEnv: [appConfigs.envs.withCustomRoles] })('authoriz
  await u.page.goToRelative('/settings/auth-has');
  await expect(u.page.getByText(/User is missing permissions/i)).toBeVisible();
  await u.page.goToRelative('/settings/auth-protect');
- await expect(u.page.getByText(/this page could not be found/i)).toBeVisible();
+ await u.po.signIn.waitForMounted();
  });
 
  test('Protect in RSCs and RCCs as `viewer`', async ({ page, context }) => {

packages/backend/src/constants.ts

@@ -42,6 +42,7 @@ const Headers = {
  Host: 'host',
  ContentType: 'content-type',
  SecFetchDest: 'sec-fetch-dest',
+ Location: 'location',
 } as const;
 
 const ContentTypes = {
@@ -58,3 +59,5 @@ export const constants = {
  ContentTypes,
  QueryParameters,
 } as const;
+
+export type Constants = typeof constants;

packages/backend/src/tokens/clerkRequest.ts

@@ -1,25 +1,14 @@
 import { parse as parseCookies } from 'cookie';
 
 import { constants } from '../constants';
-
-export type WithClerkUrl<T> = T & {
- /**
- * When a NextJs app is hosted on a platform different from Vercel
- * or inside a container (Netlify, Fly.io, AWS Amplify, docker etc),
- * req.url is always set to `localhost:3000` instead of the actual host of the app.
- *
- * The `authMiddleware` uses the value of the available req.headers in order to construct
- * and use the correct url internally. This url is then exposed as `experimental_clerkUrl`,
- * intended to be used within `beforeAuth` and `afterAuth` if needed.
- */
- clerkUrl: URL;
-};
+import type { ClerkUrl, WithClerkUrl } from './clerkUrl';
+import { createClerkUrl } from './clerkUrl';
 
 class ClerkRequest extends Request {
- readonly clerkUrl: URL;
+ readonly clerkUrl: ClerkUrl;
  readonly cookies: Map<string, string>;
 
- public constructor(req: Request) {
+ public constructor(req: ClerkRequest | Request) {
  super(req, req);
  this.clerkUrl = this.deriveUrlFromHeaders(req);
  this.cookies = this.parseCookies(req);
@@ -44,7 +33,7 @@ class ClerkRequest extends Request {
  const resolvedProtocol = this.getFirstValueFromHeader(forwardedProto) ?? protocol?.replace(/[:/]/, '');
  const origin = resolvedHost && resolvedProtocol ? `${resolvedProtocol}://${resolvedHost}` : initialUrl.origin;
 
- return new URL(initialUrl.pathname + initialUrl.search, origin);
+ return createClerkUrl(initialUrl.pathname + initialUrl.search, origin);
  }
 
  private getFirstValueFromHeader(value?: string | null) {
@@ -62,7 +51,7 @@ class ClerkRequest extends Request {
 }
 
 export const createClerkRequest = (...args: ConstructorParameters<typeof ClerkRequest>): ClerkRequest => {
- return new ClerkRequest(...args);
+ return args[0] instanceof ClerkRequest ? args[0] : new ClerkRequest(...args);
 };
 
 export type { ClerkRequest };

packages/backend/src/tokens/clerkUrl.ts

@@ -0,0 +1,24 @@
+class ClerkUrl extends URL {
+ public isCrossOrigin(other: URL | string) {
+ return this.origin !== new URL(other.toString()).origin;
+ }
+}
+
+export type WithClerkUrl<T> = T & {
+ /**
+ * When a NextJs app is hosted on a platform different from Vercel
+ * or inside a container (Netlify, Fly.io, AWS Amplify, docker etc),
+ * req.url is always set to `localhost:3000` instead of the actual host of the app.
+ *
+ * The `authMiddleware` uses the value of the available req.headers in order to construct
+ * and use the correct url internally. This url is then exposed as `experimental_clerkUrl`,
+ * intended to be used within `beforeAuth` and `afterAuth` if needed.
+ */
+ clerkUrl: ClerkUrl;
+};
+
+export const createClerkUrl = (...args: ConstructorParameters<typeof ClerkUrl>): ClerkUrl => {
+ return new ClerkUrl(...args);
+};
+
+export type { ClerkUrl };

packages/fastify/src/__snapshots__/constants.test.ts.snap

@@ -24,6 +24,7 @@ exports[`constants from environment variables 1`] = `
  "ForwardedPort": "x-forwarded-port",
  "ForwardedProto": "x-forwarded-proto",
  "Host": "host",
+ "Location": "location",
  "Origin": "origin",
  "Referrer": "referer",
  "SecFetchDest": "sec-fetch-dest",

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

@@ -1,14 +1,12 @@
-import type { ClerkProviderOptionsWrapper } from '@clerk/clerk-react';
-import type { InitialState } from '@clerk/types';
+import type { InitialState, Without } from '@clerk/types';
 import React from 'react';
 
+import type { NextClerkProviderProps } from '../../types';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
 import { ClientClerkProvider } from '../client/ClerkProvider';
 import { initialState } from './auth';
 
-type NextAppClerkProviderProps = ClerkProviderOptionsWrapper;
-
-export function ClerkProvider(props: NextAppClerkProviderProps) {
+export function ClerkProvider(props: Without<NextClerkProviderProps, '__unstable_invokeMiddlewareOnAuthStateChange'>) {
  const { children, ...rest } = props;
  const state = initialState()?.__clerk_ssr_state as InitialState;
 

packages/nextjs/src/app-router/server/auth.ts

@@ -1,18 +1,20 @@
 import type { AuthObject } from '@clerk/backend/internal';
+import { notFound, redirect } from 'next/navigation';
 
 import { authAuthHeaderMissing } from '../../server/errors';
 import { buildClerkProps, createGetAuth } from '../../server/getAuth';
-import type { AuthProtect } from './protect';
-import { createProtect } from './protect';
+import type { AuthProtect } from '../../server/protect';
+import { createProtect } from '../../server/protect';
 import { buildRequestLike } from './utils';
 
 export const auth = (): AuthObject & { protect: AuthProtect } => {
+ const request = buildRequestLike();
  const authObject = createGetAuth({
  debugLoggerName: 'auth()',
  noAuthStatusMessage: authAuthHeaderMissing(),
- })(buildRequestLike());
+ })(request);
 
- return Object.assign(authObject, { protect: createProtect(authObject) });
+ return Object.assign(authObject, { protect: createProtect({ request, authObject, notFound, redirect }) });
 };
 
 export const initialState = () => {

packages/nextjs/src/constants.ts

@@ -2,6 +2,8 @@ const Headers = {
  NextRewrite: 'x-middleware-rewrite',
  NextResume: 'x-middleware-next',
  NextRedirect: 'Location',
+ NextUrl: 'next-url',
+ NextAction: 'next-action',
 } as const;
 
 export const constants = {

packages/nextjs/src/pages/__tests__/index.test.tsx

@@ -31,27 +31,6 @@ describe('ClerkProvider', () => {
  it('domain + isSatellite (satellite app)', () => {
  expectTypeOf({ ...defaultProps, domain: 'test', isSatellite: true }).toMatchTypeOf<ClerkProviderProps>();
  });
-
- it('only domain is not allowed', () => {
- expectTypeOf({ ...defaultProps, domain: 'test' }).not.toMatchTypeOf<ClerkProviderProps>();
- });
-
- it('only isSatellite is not allowed', () => {
- expectTypeOf({ ...defaultProps, isSatellite: true }).not.toMatchTypeOf<ClerkProviderProps>();
- });
-
- it('proxyUrl + domain is not allowed', () => {
- expectTypeOf({ ...defaultProps, proxyUrl: 'test', domain: 'test' }).not.toMatchTypeOf<ClerkProviderProps>();
- });
-
- it('proxyUrl + domain + isSatellite is not allowed', () => {
- expectTypeOf({
- ...defaultProps,
- proxyUrl: 'test',
- domain: 'test',
- isSatellite: true,
- }).not.toMatchTypeOf<ClerkProviderProps>();
- });
  });
 
  describe('clerkJSVariant', () => {

packages/nextjs/src/server/__tests__/__snapshots__/exports.test.ts.snap

@@ -6,8 +6,10 @@ exports[`/server public exports should not include a breaking change 1`] = `
  "authMiddleware",
  "buildClerkProps",
  "clerkClient",
+ "clerkMiddleware",
  "createClerkClient",
  "currentUser",
+ "experimental_createRouteMatcher",
  "getAuth",
  "redirectToSignIn",
  "redirectToSignUp",

packages/nextjs/src/server/authMiddleware.test.ts

@@ -33,9 +33,10 @@ jest.mock('./redirect', () => {
 });
 
 import { paths, setHeader } from '../utils';
-import { authMiddleware, createRouteMatcher, DEFAULT_CONFIG_MATCHER, DEFAULT_IGNORED_ROUTES } from './authMiddleware';
+import { authMiddleware, DEFAULT_CONFIG_MATCHER, DEFAULT_IGNORED_ROUTES } from './authMiddleware';
 // used to assert the mock
 import { clerkClient } from './clerkClient';
+import { createRouteMatcher } from './routeMatcher';
 
 /**
  * Disable console warnings about config matchers