feat(nextjs): [improved] Hint correct middleware location when missing clerkMiddleware

.changeset/weak-phones-retire.md

@@ -0,0 +1,5 @@
+---
+'@clerk/nextjs': patch
+---
+
+Bug fix: Remove warning for accessing Node APIs when running `next build` with `clerkMiddleware` imported.

packages/nextjs/src/app-router/keyless-actions.ts

@@ -72,6 +72,6 @@ export async function deleteKeylessAction() {
  return;
  }
 
- await import('../server/keyless-node.js').then(m => m.removeKeyless());
+ await import('../server/keyless-node.js').then(m => m.removeKeyless()).catch(() => {});
  return;
 }

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

@@ -8,6 +8,7 @@ import { createClerkClientWithOptions } from '../../server/createClerkClient';
 import type { NextClerkProviderProps } from '../../types';
 import { canUseKeyless } from '../../utils/feature-flags';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
+import { onlyTry } from '../../utils/only-try';
 import { isNext13 } from '../../utils/sdk-versions';
 import { ClientClerkProvider } from '../client/ClerkProvider';
 import { deleteKeylessAction } from '../keyless-actions';
@@ -24,15 +25,6 @@ const getNonceFromCSPHeader = React.cache(async function getNonceFromCSPHeader()
  return getScriptNonceFromHeader((await headers()).get('Content-Security-Policy') || '') || '';
 });
 
-/** Discards errors thrown by attempted code */
-const onlyTry = (cb: () => unknown) => {
- try {
- cb();
- } catch {
- // ignore
- }
-};
-
 export async function ClerkProvider(
  props: Without<NextClerkProviderProps, '__unstable_invokeMiddlewareOnAuthStateChange'>,
 ) {

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

@@ -3,12 +3,13 @@ import { constants, createClerkRequest, createRedirect, type RedirectFun } from
 import { notFound, redirect } from 'next/navigation';
 
 import { PUBLISHABLE_KEY, SIGN_IN_URL, SIGN_UP_URL } from '../../server/constants';
-import { createGetAuth } from '../../server/createGetAuth';
+import { createAsyncGetAuth } from '../../server/createGetAuth';
 import { authAuthHeaderMissing } from '../../server/errors';
 import { getAuthKeyFromRequest, getHeader } from '../../server/headers-utils';
 import type { AuthProtect } from '../../server/protect';
 import { createProtect } from '../../server/protect';
 import { decryptClerkRequestData } from '../../server/utils';
+import { isNextWithUnstableServerActions } from '../../utils/sdk-versions';
 import { buildRequestLike } from './utils';
 
 /**
@@ -25,8 +26,10 @@ type Auth = AuthObject & {
  */
  redirectToSignIn: RedirectFun<ReturnType<typeof redirect>>;
 };
+
 export interface AuthFn {
  (): Promise<Auth>;
+
  /**
  * `auth` includes a single property, the `protect()` method, which you can use in two ways:
  * - to check if a user is authenticated (signed in)
@@ -60,9 +63,22 @@ export const auth: AuthFn = async () => {
  require('server-only');
 
  const request = await buildRequestLike();
- const authObject = createGetAuth({
+
+ const stepsBasedOnSrcDirectory = async () => {
+ if (isNextWithUnstableServerActions) {
+ return [];
+ }
+
+ try {
+ const isSrcAppDir = await import('../../server/fs/middleware-location.js').then(m => m.hasSrcAppDir());
+ return [`Your Middleware exists at ./${isSrcAppDir ? 'src/' : ''}middleware.(ts|js)`];
+ } catch {
+ return [];
+ }
+ };
+ const authObject = await createAsyncGetAuth({
  debugLoggerName: 'auth()',
- noAuthStatusMessage: authAuthHeaderMissing(),
+ noAuthStatusMessage: authAuthHeaderMissing('auth', await stepsBasedOnSrcDirectory()),
  })(request);
 
  const clerkUrl = getAuthKeyFromRequest(request, 'ClerkUrl');

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

@@ -34,7 +34,7 @@ export async function buildRequestLike(): Promise<NextRequest> {
  }
 
  throw new Error(
- `Clerk: auth()and currentUser() are only supported in App Router (/app directory).\nIf you're using /pages, try getAuth() instead.\nOriginal error: ${e}`,
+ `Clerk: auth(), currentUser() and clerkClient(), are only supported in App Router (/app directory).\nIf you're using /pages, try getAuth() instead.\nOriginal error: ${e}`,
  );
  }
 }

packages/nextjs/src/runtime/browser/safe-node-apis.js

@@ -3,5 +3,6 @@
  */
 const fs = undefined;
 const path = undefined;
+const cwd = undefined;
 
-module.exports = { fs, path };
+module.exports = { fs, path, cwd };

packages/nextjs/src/runtime/node/safe-node-apis.js

@@ -14,4 +14,6 @@ const fs = {
  rmSync,
 };
 
-module.exports = { fs, path };
+const cwd = () => process.cwd();
+
+module.exports = { fs, path, cwd };

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

@@ -3,7 +3,7 @@ import hmacSHA1 from 'crypto-js/hmac-sha1';
 import { NextRequest } from 'next/server';
 import { describe, expect, it } from 'vitest';
 
-import { createGetAuth, getAuth } from '../createGetAuth';
+import { createSyncGetAuth, getAuth } from '../createGetAuth';
 
 const mockSecretKey = 'sk_test_mock';
 
@@ -16,7 +16,7 @@ const mockTokenSignature = hmacSHA1(mockToken, 'sk_test_mock').toString();
 
 describe('createGetAuth(opts)', () => {
  it('returns a getAuth function', () => {
- expect(createGetAuth({ debugLoggerName: 'test', noAuthStatusMessage: 'test' })).toBeInstanceOf(Function);
+ expect(createSyncGetAuth({ debugLoggerName: 'test', noAuthStatusMessage: 'test' })).toBeInstanceOf(Function);
  });
 });
 

packages/nextjs/src/server/createGetAuth.ts

@@ -3,15 +3,60 @@ import { constants } from '@clerk/backend/internal';
 import { isTruthy } from '@clerk/shared/underscore';
 
 import { withLogger } from '../utils/debugLogger';
+import { isNextWithUnstableServerActions } from '../utils/sdk-versions';
 import { getAuthDataFromRequest } from './data/getAuthDataFromRequest';
 import { getAuthAuthHeaderMissing } from './errors';
-import { getHeader } from './headers-utils';
+import { detectClerkMiddleware, getHeader } from './headers-utils';
 import type { RequestLike } from './types';
 import { assertAuthStatus } from './utils';
 
-export const createGetAuth = ({
+/**
+ * The async variant of our old `createGetAuth` allows for asynchronous code inside its callback.
+ * Should be used with function like `auth()` that are already asynchronous.
+ */
+export const createAsyncGetAuth = ({
+ debugLoggerName,
  noAuthStatusMessage,
+}: {
+ debugLoggerName: string;
+ noAuthStatusMessage: string;
+}) =>
+ withLogger(debugLoggerName, logger => {
+ return async (req: RequestLike, opts?: { secretKey?: string }): Promise<AuthObject> => {
+ if (isTruthy(getHeader(req, constants.Headers.EnableDebug))) {
+ logger.enable();
+ }
+
+ if (!detectClerkMiddleware(req)) {
+ // Keep the same behaviour for versions that may have issues with bundling `node:fs`
+ if (isNextWithUnstableServerActions) {
+ assertAuthStatus(req, noAuthStatusMessage);
+ }
+
+ const missConfiguredMiddlewareLocation = await import('./fs/middleware-location.js')
+ .then(m => m.suggestMiddlewareLocation())
+ .catch(() => undefined);
+
+ if (missConfiguredMiddlewareLocation) {
+ throw new Error(missConfiguredMiddlewareLocation);
+ }
+
+ // still throw there is no suggested move location
+ assertAuthStatus(req, noAuthStatusMessage);
+ }
+
+ return getAuthDataFromRequest(req, { ...opts, logger });
+ };
+ });
+
+/**
+ * Previous known as `createGetAuth`. We needed to create a sync and async variant in order to allow for improvements
+ * that required dynamic imports (using `require` would not work).
+ * It powers the synchronous top-level api `getAuh()`.
+ */
+export const createSyncGetAuth = ({
  debugLoggerName,
+ noAuthStatusMessage,
 }: {
  debugLoggerName: string;
  noAuthStatusMessage: string;
@@ -23,7 +68,6 @@ export const createGetAuth = ({
  }
 
  assertAuthStatus(req, noAuthStatusMessage);
-
  return getAuthDataFromRequest(req, { ...opts, logger });
  };
  });
@@ -107,7 +151,7 @@ export const createGetAuth = ({
  * }
  * ```
  */
-export const getAuth = createGetAuth({
+export const getAuth = createSyncGetAuth({
  debugLoggerName: 'getAuth()',
  noAuthStatusMessage: getAuthAuthHeaderMissing(),
 });

packages/nextjs/src/server/errors.ts

@@ -20,9 +20,9 @@ Check if signInUrl is missing from your configuration or if it is not an absolut
 
 export const getAuthAuthHeaderMissing = () => authAuthHeaderMissing('getAuth');
 
-export const authAuthHeaderMissing = (helperName = 'auth') =>
+export const authAuthHeaderMissing = (helperName = 'auth', prefixSteps?: string[]) =>
  `Clerk: ${helperName}() was called but Clerk can't detect usage of clerkMiddleware(). Please ensure the following:
-- clerkMiddleware() is used in your Next.js Middleware.
+- ${prefixSteps ? [...prefixSteps, ''].join('\n- ') : ' '}clerkMiddleware() is used in your Next.js Middleware.
 - Your Middleware matcher is configured to match this route or page.
 - If you are using the src directory, make sure the Middleware file is inside of it.
 

packages/nextjs/src/server/fs/middleware-location.ts

@@ -0,0 +1,55 @@
+import { nodeCwdOrThrow, nodeFsOrThrow, nodePathOrThrow } from './utils';
+
+function hasSrcAppDir() {
+ const { existsSync } = nodeFsOrThrow();
+ const path = nodePathOrThrow();
+ const cwd = nodeCwdOrThrow();
+
+ const projectWithAppSrc = path.join(cwd(), 'src', 'app');
+
+ return !!existsSync(projectWithAppSrc);
+}
+
+function suggestMiddlewareLocation() {
+ const fileExtensions = ['ts', 'js'] as const;
+ const suggestionMessage = (
+ extension: (typeof fileExtensions)[number],
+ to: 'src/' | '',
+ from: 'src/app/' | 'app/' | '',
+ ) =>
+ `Clerk: clerkMiddleware() was not run, your middleware file might be misplaced. Move your middleware file to ./${to}middleware.${extension}. Currently located at ./${from}middleware.${extension}`;
+
+ const { existsSync } = nodeFsOrThrow();
+ const path = nodePathOrThrow();
+ const cwd = nodeCwdOrThrow();
+
+ const projectWithAppSrcPath = path.join(cwd(), 'src', 'app');
+ const projectWithAppPath = path.join(cwd(), 'app');
+
+ const checkMiddlewareLocation = (
+ basePath: string,
+ to: 'src/' | '',
+ from: 'src/app/' | 'app/' | '',
+ ): string | undefined => {
+ for (const fileExtension of fileExtensions) {
+ if (existsSync(path.join(basePath, `middleware.${fileExtension}`))) {
+ return suggestionMessage(fileExtension, to, from);
+ }
+ }
+ return undefined;
+ };
+
+ if (existsSync(projectWithAppSrcPath)) {
+ return (
+ checkMiddlewareLocation(projectWithAppSrcPath, 'src/', 'src/app/') || checkMiddlewareLocation(cwd(), 'src/', '')
+ );
+ }
+
+ if (existsSync(projectWithAppPath)) {
+ return checkMiddlewareLocation(projectWithAppPath, '', 'app/');
+ }
+
+ return undefined;
+}
+
+export { suggestMiddlewareLocation, hasSrcAppDir };

packages/nextjs/src/server/fs/utils.ts

@@ -0,0 +1,33 @@
+/**
+ * Attention: Only import this module when the node runtime is used.
+ * We are using conditional imports to mitigate bundling issues with Next.js server actions on version prior to 14.1.0.
+ */
+// @ts-ignore
+import nodeRuntime from '#safe-node-apis';
+
+const throwMissingFsModule = (module: string) => {
+ throw new Error(`Clerk: ${module} is missing. This is an internal error. Please contact Clerk's support.`);
+};
+
+const nodeFsOrThrow = () => {
+ if (!nodeRuntime.fs) {
+ throwMissingFsModule('fs');
+ }
+ return nodeRuntime.fs;
+};
+
+const nodePathOrThrow = () => {
+ if (!nodeRuntime.path) {
+ throwMissingFsModule('path');
+ }
+ return nodeRuntime.path;
+};
+
+const nodeCwdOrThrow = () => {
+ if (!nodeRuntime.cwd) {
+ throwMissingFsModule('cwd');
+ }
+ return nodeRuntime.cwd;
+};
+
+export { nodeCwdOrThrow, nodeFsOrThrow, nodePathOrThrow };

.changeset/weak-phones-retire.md

@@ -0,0 +1,5 @@
+---
+'@clerk/nextjs': patch
+---
+
+Bug fix: Remove warning for accessing Node APIs when running `next build` with `clerkMiddleware` imported.

packages/nextjs/src/app-router/keyless-actions.ts

@@ -72,6 +72,6 @@ export async function deleteKeylessAction() {
  return;
  }
 
- await import('../server/keyless-node.js').then(m => m.removeKeyless());
+ await import('../server/keyless-node.js').then(m => m.removeKeyless()).catch(() => {});
  return;
 }

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

@@ -8,6 +8,7 @@ import { createClerkClientWithOptions } from '../../server/createClerkClient';
 import type { NextClerkProviderProps } from '../../types';
 import { canUseKeyless } from '../../utils/feature-flags';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
+import { onlyTry } from '../../utils/only-try';
 import { isNext13 } from '../../utils/sdk-versions';
 import { ClientClerkProvider } from '../client/ClerkProvider';
 import { deleteKeylessAction } from '../keyless-actions';
@@ -24,15 +25,6 @@ const getNonceFromCSPHeader = React.cache(async function getNonceFromCSPHeader()
  return getScriptNonceFromHeader((await headers()).get('Content-Security-Policy') || '') || '';
 });
 
-/** Discards errors thrown by attempted code */
-const onlyTry = (cb: () => unknown) => {
- try {
- cb();
- } catch {
- // ignore
- }
-};
-
 export async function ClerkProvider(
  props: Without<NextClerkProviderProps, '__unstable_invokeMiddlewareOnAuthStateChange'>,
 ) {

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

@@ -3,12 +3,13 @@ import { constants, createClerkRequest, createRedirect, type RedirectFun } from
 import { notFound, redirect } from 'next/navigation';
 
 import { PUBLISHABLE_KEY, SIGN_IN_URL, SIGN_UP_URL } from '../../server/constants';
-import { createGetAuth } from '../../server/createGetAuth';
+import { createAsyncGetAuth } from '../../server/createGetAuth';
 import { authAuthHeaderMissing } from '../../server/errors';
 import { getAuthKeyFromRequest, getHeader } from '../../server/headers-utils';
 import type { AuthProtect } from '../../server/protect';
 import { createProtect } from '../../server/protect';
 import { decryptClerkRequestData } from '../../server/utils';
+import { isNextWithUnstableServerActions } from '../../utils/sdk-versions';
 import { buildRequestLike } from './utils';
 
 /**
@@ -25,8 +26,10 @@ type Auth = AuthObject & {
  */
  redirectToSignIn: RedirectFun<ReturnType<typeof redirect>>;
 };
+
 export interface AuthFn {
  (): Promise<Auth>;
+
  /**
  * `auth` includes a single property, the `protect()` method, which you can use in two ways:
  * - to check if a user is authenticated (signed in)
@@ -60,9 +63,22 @@ export const auth: AuthFn = async () => {
  require('server-only');
 
  const request = await buildRequestLike();
- const authObject = createGetAuth({
+
+ const stepsBasedOnSrcDirectory = async () => {
+ if (isNextWithUnstableServerActions) {
+ return [];
+ }
+
+ try {
+ const isSrcAppDir = await import('../../server/fs/middleware-location.js').then(m => m.hasSrcAppDir());
+ return [`Your Middleware exists at ./${isSrcAppDir ? 'src/' : ''}middleware.(ts|js)`];
+ } catch {
+ return [];
+ }
+ };
+ const authObject = await createAsyncGetAuth({
  debugLoggerName: 'auth()',
- noAuthStatusMessage: authAuthHeaderMissing(),
+ noAuthStatusMessage: authAuthHeaderMissing('auth', await stepsBasedOnSrcDirectory()),
  })(request);
 
  const clerkUrl = getAuthKeyFromRequest(request, 'ClerkUrl');

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

@@ -34,7 +34,7 @@ export async function buildRequestLike(): Promise<NextRequest> {
  }
 
  throw new Error(
- `Clerk: auth()and currentUser() are only supported in App Router (/app directory).\nIf you're using /pages, try getAuth() instead.\nOriginal error: ${e}`,
+ `Clerk: auth(), currentUser() and clerkClient(), are only supported in App Router (/app directory).\nIf you're using /pages, try getAuth() instead.\nOriginal error: ${e}`,
  );
  }
 }

packages/nextjs/src/runtime/browser/safe-node-apis.js

@@ -3,5 +3,6 @@
  */
 const fs = undefined;
 const path = undefined;
+const cwd = undefined;
 
-module.exports = { fs, path };
+module.exports = { fs, path, cwd };

packages/nextjs/src/runtime/node/safe-node-apis.js

@@ -14,4 +14,6 @@ const fs = {
  rmSync,
 };
 
-module.exports = { fs, path };
+const cwd = () => process.cwd();
+
+module.exports = { fs, path, cwd };

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

@@ -3,7 +3,7 @@ import hmacSHA1 from 'crypto-js/hmac-sha1';
 import { NextRequest } from 'next/server';
 import { describe, expect, it } from 'vitest';
 
-import { createGetAuth, getAuth } from '../createGetAuth';
+import { createSyncGetAuth, getAuth } from '../createGetAuth';
 
 const mockSecretKey = 'sk_test_mock';
 
@@ -16,7 +16,7 @@ const mockTokenSignature = hmacSHA1(mockToken, 'sk_test_mock').toString();
 
 describe('createGetAuth(opts)', () => {
  it('returns a getAuth function', () => {
- expect(createGetAuth({ debugLoggerName: 'test', noAuthStatusMessage: 'test' })).toBeInstanceOf(Function);
+ expect(createSyncGetAuth({ debugLoggerName: 'test', noAuthStatusMessage: 'test' })).toBeInstanceOf(Function);
  });
 });
 

packages/nextjs/src/server/createGetAuth.ts

@@ -3,15 +3,60 @@ import { constants } from '@clerk/backend/internal';
 import { isTruthy } from '@clerk/shared/underscore';
 
 import { withLogger } from '../utils/debugLogger';
+import { isNextWithUnstableServerActions } from '../utils/sdk-versions';
 import { getAuthDataFromRequest } from './data/getAuthDataFromRequest';
 import { getAuthAuthHeaderMissing } from './errors';
-import { getHeader } from './headers-utils';
+import { detectClerkMiddleware, getHeader } from './headers-utils';
 import type { RequestLike } from './types';
 import { assertAuthStatus } from './utils';
 
-export const createGetAuth = ({
+/**
+ * The async variant of our old `createGetAuth` allows for asynchronous code inside its callback.
+ * Should be used with function like `auth()` that are already asynchronous.
+ */
+export const createAsyncGetAuth = ({
+ debugLoggerName,
  noAuthStatusMessage,
+}: {
+ debugLoggerName: string;
+ noAuthStatusMessage: string;
+}) =>
+ withLogger(debugLoggerName, logger => {
+ return async (req: RequestLike, opts?: { secretKey?: string }): Promise<AuthObject> => {
+ if (isTruthy(getHeader(req, constants.Headers.EnableDebug))) {
+ logger.enable();
+ }
+
+ if (!detectClerkMiddleware(req)) {
+ // Keep the same behaviour for versions that may have issues with bundling `node:fs`
+ if (isNextWithUnstableServerActions) {
+ assertAuthStatus(req, noAuthStatusMessage);
+ }
+
+ const missConfiguredMiddlewareLocation = await import('./fs/middleware-location.js')
+ .then(m => m.suggestMiddlewareLocation())
+ .catch(() => undefined);
+
+ if (missConfiguredMiddlewareLocation) {
+ throw new Error(missConfiguredMiddlewareLocation);
+ }
+
+ // still throw there is no suggested move location
+ assertAuthStatus(req, noAuthStatusMessage);
+ }
+
+ return getAuthDataFromRequest(req, { ...opts, logger });
+ };
+ });
+
+/**
+ * Previous known as `createGetAuth`. We needed to create a sync and async variant in order to allow for improvements
+ * that required dynamic imports (using `require` would not work).
+ * It powers the synchronous top-level api `getAuh()`.
+ */
+export const createSyncGetAuth = ({
  debugLoggerName,
+ noAuthStatusMessage,
 }: {
  debugLoggerName: string;
  noAuthStatusMessage: string;
@@ -23,7 +68,6 @@ export const createGetAuth = ({
  }
 
  assertAuthStatus(req, noAuthStatusMessage);
-
  return getAuthDataFromRequest(req, { ...opts, logger });
  };
  });
@@ -107,7 +151,7 @@ export const createGetAuth = ({
  * }
  * ```
  */
-export const getAuth = createGetAuth({
+export const getAuth = createSyncGetAuth({
  debugLoggerName: 'getAuth()',
  noAuthStatusMessage: getAuthAuthHeaderMissing(),
 });

packages/nextjs/src/server/errors.ts

@@ -20,9 +20,9 @@ Check if signInUrl is missing from your configuration or if it is not an absolut
 
 export const getAuthAuthHeaderMissing = () => authAuthHeaderMissing('getAuth');
 
-export const authAuthHeaderMissing = (helperName = 'auth') =>
+export const authAuthHeaderMissing = (helperName = 'auth', prefixSteps?: string[]) =>
  `Clerk: ${helperName}() was called but Clerk can't detect usage of clerkMiddleware(). Please ensure the following:
-- clerkMiddleware() is used in your Next.js Middleware.
+- ${prefixSteps ? [...prefixSteps, ''].join('\n- ') : ' '}clerkMiddleware() is used in your Next.js Middleware.
 - Your Middleware matcher is configured to match this route or page.
 - If you are using the src directory, make sure the Middleware file is inside of it.
 

packages/nextjs/src/server/fs/middleware-location.ts

@@ -0,0 +1,55 @@
+import { nodeCwdOrThrow, nodeFsOrThrow, nodePathOrThrow } from './utils';
+
+function hasSrcAppDir() {
+ const { existsSync } = nodeFsOrThrow();
+ const path = nodePathOrThrow();
+ const cwd = nodeCwdOrThrow();
+
+ const projectWithAppSrc = path.join(cwd(), 'src', 'app');
+
+ return !!existsSync(projectWithAppSrc);
+}
+
+function suggestMiddlewareLocation() {
+ const fileExtensions = ['ts', 'js'] as const;
+ const suggestionMessage = (
+ extension: (typeof fileExtensions)[number],
+ to: 'src/' | '',
+ from: 'src/app/' | 'app/' | '',
+ ) =>
+ `Clerk: clerkMiddleware() was not run, your middleware file might be misplaced. Move your middleware file to ./${to}middleware.${extension}. Currently located at ./${from}middleware.${extension}`;
+
+ const { existsSync } = nodeFsOrThrow();
+ const path = nodePathOrThrow();
+ const cwd = nodeCwdOrThrow();
+
+ const projectWithAppSrcPath = path.join(cwd(), 'src', 'app');
+ const projectWithAppPath = path.join(cwd(), 'app');
+
+ const checkMiddlewareLocation = (
+ basePath: string,
+ to: 'src/' | '',
+ from: 'src/app/' | 'app/' | '',
+ ): string | undefined => {
+ for (const fileExtension of fileExtensions) {
+ if (existsSync(path.join(basePath, `middleware.${fileExtension}`))) {
+ return suggestionMessage(fileExtension, to, from);
+ }
+ }
+ return undefined;
+ };
+
+ if (existsSync(projectWithAppSrcPath)) {
+ return (
+ checkMiddlewareLocation(projectWithAppSrcPath, 'src/', 'src/app/') || checkMiddlewareLocation(cwd(), 'src/', '')
+ );
+ }
+
+ if (existsSync(projectWithAppPath)) {
+ return checkMiddlewareLocation(projectWithAppPath, '', 'app/');
+ }
+
+ return undefined;
+}
+
+export { suggestMiddlewareLocation, hasSrcAppDir };

packages/nextjs/src/server/fs/utils.ts

@@ -0,0 +1,33 @@
+/**
+ * Attention: Only import this module when the node runtime is used.
+ * We are using conditional imports to mitigate bundling issues with Next.js server actions on version prior to 14.1.0.
+ */
+// @ts-ignore
+import nodeRuntime from '#safe-node-apis';
+
+const throwMissingFsModule = (module: string) => {
+ throw new Error(`Clerk: ${module} is missing. This is an internal error. Please contact Clerk's support.`);
+};
+
+const nodeFsOrThrow = () => {
+ if (!nodeRuntime.fs) {
+ throwMissingFsModule('fs');
+ }
+ return nodeRuntime.fs;
+};
+
+const nodePathOrThrow = () => {
+ if (!nodeRuntime.path) {
+ throwMissingFsModule('path');
+ }
+ return nodeRuntime.path;
+};
+
+const nodeCwdOrThrow = () => {
+ if (!nodeRuntime.cwd) {
+ throwMissingFsModule('cwd');
+ }
+ return nodeRuntime.cwd;
+};
+
+export { nodeCwdOrThrow, nodeFsOrThrow, nodePathOrThrow };

.changeset/weak-phones-retire.md

@@ -0,0 +1,5 @@
+---
+'@clerk/nextjs': patch
+---
+
+Bug fix: Remove warning for accessing Node APIs when running `next build` with `clerkMiddleware` imported.

packages/nextjs/src/app-router/keyless-actions.ts

@@ -72,6 +72,6 @@ export async function deleteKeylessAction() {
  return;
  }
 
- await import('../server/keyless-node.js').then(m => m.removeKeyless());
+ await import('../server/keyless-node.js').then(m => m.removeKeyless()).catch(() => {});
  return;
 }

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

@@ -8,6 +8,7 @@ import { createClerkClientWithOptions } from '../../server/createClerkClient';
 import type { NextClerkProviderProps } from '../../types';
 import { canUseKeyless } from '../../utils/feature-flags';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
+import { onlyTry } from '../../utils/only-try';
 import { isNext13 } from '../../utils/sdk-versions';
 import { ClientClerkProvider } from '../client/ClerkProvider';
 import { deleteKeylessAction } from '../keyless-actions';
@@ -24,15 +25,6 @@ const getNonceFromCSPHeader = React.cache(async function getNonceFromCSPHeader()
  return getScriptNonceFromHeader((await headers()).get('Content-Security-Policy') || '') || '';
 });
 
-/** Discards errors thrown by attempted code */
-const onlyTry = (cb: () => unknown) => {
- try {
- cb();
- } catch {
- // ignore
- }
-};
-
 export async function ClerkProvider(
  props: Without<NextClerkProviderProps, '__unstable_invokeMiddlewareOnAuthStateChange'>,
 ) {

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

@@ -3,12 +3,13 @@ import { constants, createClerkRequest, createRedirect, type RedirectFun } from
 import { notFound, redirect } from 'next/navigation';
 
 import { PUBLISHABLE_KEY, SIGN_IN_URL, SIGN_UP_URL } from '../../server/constants';
-import { createGetAuth } from '../../server/createGetAuth';
+import { createAsyncGetAuth } from '../../server/createGetAuth';
 import { authAuthHeaderMissing } from '../../server/errors';
 import { getAuthKeyFromRequest, getHeader } from '../../server/headers-utils';
 import type { AuthProtect } from '../../server/protect';
 import { createProtect } from '../../server/protect';
 import { decryptClerkRequestData } from '../../server/utils';
+import { isNextWithUnstableServerActions } from '../../utils/sdk-versions';
 import { buildRequestLike } from './utils';
 
 /**
@@ -25,8 +26,10 @@ type Auth = AuthObject & {
  */
  redirectToSignIn: RedirectFun<ReturnType<typeof redirect>>;
 };
+
 export interface AuthFn {
  (): Promise<Auth>;
+
  /**
  * `auth` includes a single property, the `protect()` method, which you can use in two ways:
  * - to check if a user is authenticated (signed in)
@@ -60,9 +63,22 @@ export const auth: AuthFn = async () => {
  require('server-only');
 
  const request = await buildRequestLike();
- const authObject = createGetAuth({
+
+ const stepsBasedOnSrcDirectory = async () => {
+ if (isNextWithUnstableServerActions) {
+ return [];
+ }
+
+ try {
+ const isSrcAppDir = await import('../../server/fs/middleware-location.js').then(m => m.hasSrcAppDir());
+ return [`Your Middleware exists at ./${isSrcAppDir ? 'src/' : ''}middleware.(ts|js)`];
+ } catch {
+ return [];
+ }
+ };
+ const authObject = await createAsyncGetAuth({
  debugLoggerName: 'auth()',
- noAuthStatusMessage: authAuthHeaderMissing(),
+ noAuthStatusMessage: authAuthHeaderMissing('auth', await stepsBasedOnSrcDirectory()),
  })(request);
 
  const clerkUrl = getAuthKeyFromRequest(request, 'ClerkUrl');

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

@@ -34,7 +34,7 @@ export async function buildRequestLike(): Promise<NextRequest> {
  }
 
  throw new Error(
- `Clerk: auth()and currentUser() are only supported in App Router (/app directory).\nIf you're using /pages, try getAuth() instead.\nOriginal error: ${e}`,
+ `Clerk: auth(), currentUser() and clerkClient(), are only supported in App Router (/app directory).\nIf you're using /pages, try getAuth() instead.\nOriginal error: ${e}`,
  );
  }
 }

packages/nextjs/src/runtime/browser/safe-node-apis.js

@@ -3,5 +3,6 @@
  */
 const fs = undefined;
 const path = undefined;
+const cwd = undefined;
 
-module.exports = { fs, path };
+module.exports = { fs, path, cwd };

packages/nextjs/src/runtime/node/safe-node-apis.js

@@ -14,4 +14,6 @@ const fs = {
  rmSync,
 };
 
-module.exports = { fs, path };
+const cwd = () => process.cwd();
+
+module.exports = { fs, path, cwd };

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

@@ -3,7 +3,7 @@ import hmacSHA1 from 'crypto-js/hmac-sha1';
 import { NextRequest } from 'next/server';
 import { describe, expect, it } from 'vitest';
 
-import { createGetAuth, getAuth } from '../createGetAuth';
+import { createSyncGetAuth, getAuth } from '../createGetAuth';
 
 const mockSecretKey = 'sk_test_mock';
 
@@ -16,7 +16,7 @@ const mockTokenSignature = hmacSHA1(mockToken, 'sk_test_mock').toString();
 
 describe('createGetAuth(opts)', () => {
  it('returns a getAuth function', () => {
- expect(createGetAuth({ debugLoggerName: 'test', noAuthStatusMessage: 'test' })).toBeInstanceOf(Function);
+ expect(createSyncGetAuth({ debugLoggerName: 'test', noAuthStatusMessage: 'test' })).toBeInstanceOf(Function);
  });
 });
 

packages/nextjs/src/server/createGetAuth.ts

@@ -3,15 +3,60 @@ import { constants } from '@clerk/backend/internal';
 import { isTruthy } from '@clerk/shared/underscore';
 
 import { withLogger } from '../utils/debugLogger';
+import { isNextWithUnstableServerActions } from '../utils/sdk-versions';
 import { getAuthDataFromRequest } from './data/getAuthDataFromRequest';
 import { getAuthAuthHeaderMissing } from './errors';
-import { getHeader } from './headers-utils';
+import { detectClerkMiddleware, getHeader } from './headers-utils';
 import type { RequestLike } from './types';
 import { assertAuthStatus } from './utils';
 
-export const createGetAuth = ({
+/**
+ * The async variant of our old `createGetAuth` allows for asynchronous code inside its callback.
+ * Should be used with function like `auth()` that are already asynchronous.
+ */
+export const createAsyncGetAuth = ({
+ debugLoggerName,
  noAuthStatusMessage,
+}: {
+ debugLoggerName: string;
+ noAuthStatusMessage: string;
+}) =>
+ withLogger(debugLoggerName, logger => {
+ return async (req: RequestLike, opts?: { secretKey?: string }): Promise<AuthObject> => {
+ if (isTruthy(getHeader(req, constants.Headers.EnableDebug))) {
+ logger.enable();
+ }
+
+ if (!detectClerkMiddleware(req)) {
+ // Keep the same behaviour for versions that may have issues with bundling `node:fs`
+ if (isNextWithUnstableServerActions) {
+ assertAuthStatus(req, noAuthStatusMessage);
+ }
+
+ const missConfiguredMiddlewareLocation = await import('./fs/middleware-location.js')
+ .then(m => m.suggestMiddlewareLocation())
+ .catch(() => undefined);
+
+ if (missConfiguredMiddlewareLocation) {
+ throw new Error(missConfiguredMiddlewareLocation);
+ }
+
+ // still throw there is no suggested move location
+ assertAuthStatus(req, noAuthStatusMessage);
+ }
+
+ return getAuthDataFromRequest(req, { ...opts, logger });
+ };
+ });
+
+/**
+ * Previous known as `createGetAuth`. We needed to create a sync and async variant in order to allow for improvements
+ * that required dynamic imports (using `require` would not work).
+ * It powers the synchronous top-level api `getAuh()`.
+ */
+export const createSyncGetAuth = ({
  debugLoggerName,
+ noAuthStatusMessage,
 }: {
  debugLoggerName: string;
  noAuthStatusMessage: string;
@@ -23,7 +68,6 @@ export const createGetAuth = ({
  }
 
  assertAuthStatus(req, noAuthStatusMessage);
-
  return getAuthDataFromRequest(req, { ...opts, logger });
  };
  });
@@ -107,7 +151,7 @@ export const createGetAuth = ({
  * }
  * ```
  */
-export const getAuth = createGetAuth({
+export const getAuth = createSyncGetAuth({
  debugLoggerName: 'getAuth()',
  noAuthStatusMessage: getAuthAuthHeaderMissing(),
 });

packages/nextjs/src/server/errors.ts

@@ -20,9 +20,9 @@ Check if signInUrl is missing from your configuration or if it is not an absolut
 
 export const getAuthAuthHeaderMissing = () => authAuthHeaderMissing('getAuth');
 
-export const authAuthHeaderMissing = (helperName = 'auth') =>
+export const authAuthHeaderMissing = (helperName = 'auth', prefixSteps?: string[]) =>
  `Clerk: ${helperName}() was called but Clerk can't detect usage of clerkMiddleware(). Please ensure the following:
-- clerkMiddleware() is used in your Next.js Middleware.
+- ${prefixSteps ? [...prefixSteps, ''].join('\n- ') : ' '}clerkMiddleware() is used in your Next.js Middleware.
 - Your Middleware matcher is configured to match this route or page.
 - If you are using the src directory, make sure the Middleware file is inside of it.
 

packages/nextjs/src/server/fs/middleware-location.ts

@@ -0,0 +1,55 @@
+import { nodeCwdOrThrow, nodeFsOrThrow, nodePathOrThrow } from './utils';
+
+function hasSrcAppDir() {
+ const { existsSync } = nodeFsOrThrow();
+ const path = nodePathOrThrow();
+ const cwd = nodeCwdOrThrow();
+
+ const projectWithAppSrc = path.join(cwd(), 'src', 'app');
+
+ return !!existsSync(projectWithAppSrc);
+}
+
+function suggestMiddlewareLocation() {
+ const fileExtensions = ['ts', 'js'] as const;
+ const suggestionMessage = (
+ extension: (typeof fileExtensions)[number],
+ to: 'src/' | '',
+ from: 'src/app/' | 'app/' | '',
+ ) =>
+ `Clerk: clerkMiddleware() was not run, your middleware file might be misplaced. Move your middleware file to ./${to}middleware.${extension}. Currently located at ./${from}middleware.${extension}`;
+
+ const { existsSync } = nodeFsOrThrow();
+ const path = nodePathOrThrow();
+ const cwd = nodeCwdOrThrow();
+
+ const projectWithAppSrcPath = path.join(cwd(), 'src', 'app');
+ const projectWithAppPath = path.join(cwd(), 'app');
+
+ const checkMiddlewareLocation = (
+ basePath: string,
+ to: 'src/' | '',
+ from: 'src/app/' | 'app/' | '',
+ ): string | undefined => {
+ for (const fileExtension of fileExtensions) {
+ if (existsSync(path.join(basePath, `middleware.${fileExtension}`))) {
+ return suggestionMessage(fileExtension, to, from);
+ }
+ }
+ return undefined;
+ };
+
+ if (existsSync(projectWithAppSrcPath)) {
+ return (
+ checkMiddlewareLocation(projectWithAppSrcPath, 'src/', 'src/app/') || checkMiddlewareLocation(cwd(), 'src/', '')
+ );
+ }
+
+ if (existsSync(projectWithAppPath)) {
+ return checkMiddlewareLocation(projectWithAppPath, '', 'app/');
+ }
+
+ return undefined;
+}
+
+export { suggestMiddlewareLocation, hasSrcAppDir };

packages/nextjs/src/server/fs/utils.ts

@@ -0,0 +1,33 @@
+/**
+ * Attention: Only import this module when the node runtime is used.
+ * We are using conditional imports to mitigate bundling issues with Next.js server actions on version prior to 14.1.0.
+ */
+// @ts-ignore
+import nodeRuntime from '#safe-node-apis';
+
+const throwMissingFsModule = (module: string) => {
+ throw new Error(`Clerk: ${module} is missing. This is an internal error. Please contact Clerk's support.`);
+};
+
+const nodeFsOrThrow = () => {
+ if (!nodeRuntime.fs) {
+ throwMissingFsModule('fs');
+ }
+ return nodeRuntime.fs;
+};
+
+const nodePathOrThrow = () => {
+ if (!nodeRuntime.path) {
+ throwMissingFsModule('path');
+ }
+ return nodeRuntime.path;
+};
+
+const nodeCwdOrThrow = () => {
+ if (!nodeRuntime.cwd) {
+ throwMissingFsModule('cwd');
+ }
+ return nodeRuntime.cwd;
+};
+
+export { nodeCwdOrThrow, nodeFsOrThrow, nodePathOrThrow };

.changeset/weak-phones-retire.md

@@ -0,0 +1,5 @@
+---
+'@clerk/nextjs': patch
+---
+
+Bug fix: Remove warning for accessing Node APIs when running `next build` with `clerkMiddleware` imported.

packages/nextjs/src/app-router/keyless-actions.ts

@@ -72,6 +72,6 @@ export async function deleteKeylessAction() {
  return;
  }
 
- await import('../server/keyless-node.js').then(m => m.removeKeyless());
+ await import('../server/keyless-node.js').then(m => m.removeKeyless()).catch(() => {});
  return;
 }

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

@@ -8,6 +8,7 @@ import { createClerkClientWithOptions } from '../../server/createClerkClient';
 import type { NextClerkProviderProps } from '../../types';
 import { canUseKeyless } from '../../utils/feature-flags';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
+import { onlyTry } from '../../utils/only-try';
 import { isNext13 } from '../../utils/sdk-versions';
 import { ClientClerkProvider } from '../client/ClerkProvider';
 import { deleteKeylessAction } from '../keyless-actions';
@@ -24,15 +25,6 @@ const getNonceFromCSPHeader = React.cache(async function getNonceFromCSPHeader()
  return getScriptNonceFromHeader((await headers()).get('Content-Security-Policy') || '') || '';
 });
 
-/** Discards errors thrown by attempted code */
-const onlyTry = (cb: () => unknown) => {
- try {
- cb();
- } catch {
- // ignore
- }
-};
-
 export async function ClerkProvider(
  props: Without<NextClerkProviderProps, '__unstable_invokeMiddlewareOnAuthStateChange'>,
 ) {

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

@@ -3,12 +3,13 @@ import { constants, createClerkRequest, createRedirect, type RedirectFun } from
 import { notFound, redirect } from 'next/navigation';
 
 import { PUBLISHABLE_KEY, SIGN_IN_URL, SIGN_UP_URL } from '../../server/constants';
-import { createGetAuth } from '../../server/createGetAuth';
+import { createAsyncGetAuth } from '../../server/createGetAuth';
 import { authAuthHeaderMissing } from '../../server/errors';
 import { getAuthKeyFromRequest, getHeader } from '../../server/headers-utils';
 import type { AuthProtect } from '../../server/protect';
 import { createProtect } from '../../server/protect';
 import { decryptClerkRequestData } from '../../server/utils';
+import { isNextWithUnstableServerActions } from '../../utils/sdk-versions';
 import { buildRequestLike } from './utils';
 
 /**
@@ -25,8 +26,10 @@ type Auth = AuthObject & {
  */
  redirectToSignIn: RedirectFun<ReturnType<typeof redirect>>;
 };
+
 export interface AuthFn {
  (): Promise<Auth>;
+
  /**
  * `auth` includes a single property, the `protect()` method, which you can use in two ways:
  * - to check if a user is authenticated (signed in)
@@ -60,9 +63,22 @@ export const auth: AuthFn = async () => {
  require('server-only');
 
  const request = await buildRequestLike();
- const authObject = createGetAuth({
+
+ const stepsBasedOnSrcDirectory = async () => {
+ if (isNextWithUnstableServerActions) {
+ return [];
+ }
+
+ try {
+ const isSrcAppDir = await import('../../server/fs/middleware-location.js').then(m => m.hasSrcAppDir());
+ return [`Your Middleware exists at ./${isSrcAppDir ? 'src/' : ''}middleware.(ts|js)`];
+ } catch {
+ return [];
+ }
+ };
+ const authObject = await createAsyncGetAuth({
  debugLoggerName: 'auth()',
- noAuthStatusMessage: authAuthHeaderMissing(),
+ noAuthStatusMessage: authAuthHeaderMissing('auth', await stepsBasedOnSrcDirectory()),
  })(request);
 
  const clerkUrl = getAuthKeyFromRequest(request, 'ClerkUrl');

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

@@ -34,7 +34,7 @@ export async function buildRequestLike(): Promise<NextRequest> {
  }
 
  throw new Error(
- `Clerk: auth()and currentUser() are only supported in App Router (/app directory).\nIf you're using /pages, try getAuth() instead.\nOriginal error: ${e}`,
+ `Clerk: auth(), currentUser() and clerkClient(), are only supported in App Router (/app directory).\nIf you're using /pages, try getAuth() instead.\nOriginal error: ${e}`,
  );
  }
 }

packages/nextjs/src/runtime/browser/safe-node-apis.js

@@ -3,5 +3,6 @@
  */
 const fs = undefined;
 const path = undefined;
+const cwd = undefined;
 
-module.exports = { fs, path };
+module.exports = { fs, path, cwd };

packages/nextjs/src/runtime/node/safe-node-apis.js

@@ -14,4 +14,6 @@ const fs = {
  rmSync,
 };
 
-module.exports = { fs, path };
+const cwd = () => process.cwd();
+
+module.exports = { fs, path, cwd };

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

@@ -3,7 +3,7 @@ import hmacSHA1 from 'crypto-js/hmac-sha1';
 import { NextRequest } from 'next/server';
 import { describe, expect, it } from 'vitest';
 
-import { createGetAuth, getAuth } from '../createGetAuth';
+import { createSyncGetAuth, getAuth } from '../createGetAuth';
 
 const mockSecretKey = 'sk_test_mock';
 
@@ -16,7 +16,7 @@ const mockTokenSignature = hmacSHA1(mockToken, 'sk_test_mock').toString();
 
 describe('createGetAuth(opts)', () => {
  it('returns a getAuth function', () => {
- expect(createGetAuth({ debugLoggerName: 'test', noAuthStatusMessage: 'test' })).toBeInstanceOf(Function);
+ expect(createSyncGetAuth({ debugLoggerName: 'test', noAuthStatusMessage: 'test' })).toBeInstanceOf(Function);
  });
 });
 

packages/nextjs/src/server/createGetAuth.ts

@@ -3,15 +3,60 @@ import { constants } from '@clerk/backend/internal';
 import { isTruthy } from '@clerk/shared/underscore';
 
 import { withLogger } from '../utils/debugLogger';
+import { isNextWithUnstableServerActions } from '../utils/sdk-versions';
 import { getAuthDataFromRequest } from './data/getAuthDataFromRequest';
 import { getAuthAuthHeaderMissing } from './errors';
-import { getHeader } from './headers-utils';
+import { detectClerkMiddleware, getHeader } from './headers-utils';
 import type { RequestLike } from './types';
 import { assertAuthStatus } from './utils';
 
-export const createGetAuth = ({
+/**
+ * The async variant of our old `createGetAuth` allows for asynchronous code inside its callback.
+ * Should be used with function like `auth()` that are already asynchronous.
+ */
+export const createAsyncGetAuth = ({
+ debugLoggerName,
  noAuthStatusMessage,
+}: {
+ debugLoggerName: string;
+ noAuthStatusMessage: string;
+}) =>
+ withLogger(debugLoggerName, logger => {
+ return async (req: RequestLike, opts?: { secretKey?: string }): Promise<AuthObject> => {
+ if (isTruthy(getHeader(req, constants.Headers.EnableDebug))) {
+ logger.enable();
+ }
+
+ if (!detectClerkMiddleware(req)) {
+ // Keep the same behaviour for versions that may have issues with bundling `node:fs`
+ if (isNextWithUnstableServerActions) {
+ assertAuthStatus(req, noAuthStatusMessage);
+ }
+
+ const missConfiguredMiddlewareLocation = await import('./fs/middleware-location.js')
+ .then(m => m.suggestMiddlewareLocation())
+ .catch(() => undefined);
+
+ if (missConfiguredMiddlewareLocation) {
+ throw new Error(missConfiguredMiddlewareLocation);
+ }
+
+ // still throw there is no suggested move location
+ assertAuthStatus(req, noAuthStatusMessage);
+ }
+
+ return getAuthDataFromRequest(req, { ...opts, logger });
+ };
+ });
+
+/**
+ * Previous known as `createGetAuth`. We needed to create a sync and async variant in order to allow for improvements
+ * that required dynamic imports (using `require` would not work).
+ * It powers the synchronous top-level api `getAuh()`.
+ */
+export const createSyncGetAuth = ({
  debugLoggerName,
+ noAuthStatusMessage,
 }: {
  debugLoggerName: string;
  noAuthStatusMessage: string;
@@ -23,7 +68,6 @@ export const createGetAuth = ({
  }
 
  assertAuthStatus(req, noAuthStatusMessage);
-
  return getAuthDataFromRequest(req, { ...opts, logger });
  };
  });
@@ -107,7 +151,7 @@ export const createGetAuth = ({
  * }
  * ```
  */
-export const getAuth = createGetAuth({
+export const getAuth = createSyncGetAuth({
  debugLoggerName: 'getAuth()',
  noAuthStatusMessage: getAuthAuthHeaderMissing(),
 });

packages/nextjs/src/server/errors.ts

@@ -20,9 +20,9 @@ Check if signInUrl is missing from your configuration or if it is not an absolut
 
 export const getAuthAuthHeaderMissing = () => authAuthHeaderMissing('getAuth');
 
-export const authAuthHeaderMissing = (helperName = 'auth') =>
+export const authAuthHeaderMissing = (helperName = 'auth', prefixSteps?: string[]) =>
  `Clerk: ${helperName}() was called but Clerk can't detect usage of clerkMiddleware(). Please ensure the following:
-- clerkMiddleware() is used in your Next.js Middleware.
+- ${prefixSteps ? [...prefixSteps, ''].join('\n- ') : ' '}clerkMiddleware() is used in your Next.js Middleware.
 - Your Middleware matcher is configured to match this route or page.
 - If you are using the src directory, make sure the Middleware file is inside of it.
 

packages/nextjs/src/server/fs/middleware-location.ts

@@ -0,0 +1,55 @@
+import { nodeCwdOrThrow, nodeFsOrThrow, nodePathOrThrow } from './utils';
+
+function hasSrcAppDir() {
+ const { existsSync } = nodeFsOrThrow();
+ const path = nodePathOrThrow();
+ const cwd = nodeCwdOrThrow();
+
+ const projectWithAppSrc = path.join(cwd(), 'src', 'app');
+
+ return !!existsSync(projectWithAppSrc);
+}
+
+function suggestMiddlewareLocation() {
+ const fileExtensions = ['ts', 'js'] as const;
+ const suggestionMessage = (
+ extension: (typeof fileExtensions)[number],
+ to: 'src/' | '',
+ from: 'src/app/' | 'app/' | '',
+ ) =>
+ `Clerk: clerkMiddleware() was not run, your middleware file might be misplaced. Move your middleware file to ./${to}middleware.${extension}. Currently located at ./${from}middleware.${extension}`;
+
+ const { existsSync } = nodeFsOrThrow();
+ const path = nodePathOrThrow();
+ const cwd = nodeCwdOrThrow();
+
+ const projectWithAppSrcPath = path.join(cwd(), 'src', 'app');
+ const projectWithAppPath = path.join(cwd(), 'app');
+
+ const checkMiddlewareLocation = (
+ basePath: string,
+ to: 'src/' | '',
+ from: 'src/app/' | 'app/' | '',
+ ): string | undefined => {
+ for (const fileExtension of fileExtensions) {
+ if (existsSync(path.join(basePath, `middleware.${fileExtension}`))) {
+ return suggestionMessage(fileExtension, to, from);
+ }
+ }
+ return undefined;
+ };
+
+ if (existsSync(projectWithAppSrcPath)) {
+ return (
+ checkMiddlewareLocation(projectWithAppSrcPath, 'src/', 'src/app/') || checkMiddlewareLocation(cwd(), 'src/', '')
+ );
+ }
+
+ if (existsSync(projectWithAppPath)) {
+ return checkMiddlewareLocation(projectWithAppPath, '', 'app/');
+ }
+
+ return undefined;
+}
+
+export { suggestMiddlewareLocation, hasSrcAppDir };

packages/nextjs/src/server/fs/utils.ts

@@ -0,0 +1,33 @@
+/**
+ * Attention: Only import this module when the node runtime is used.
+ * We are using conditional imports to mitigate bundling issues with Next.js server actions on version prior to 14.1.0.
+ */
+// @ts-ignore
+import nodeRuntime from '#safe-node-apis';
+
+const throwMissingFsModule = (module: string) => {
+ throw new Error(`Clerk: ${module} is missing. This is an internal error. Please contact Clerk's support.`);
+};
+
+const nodeFsOrThrow = () => {
+ if (!nodeRuntime.fs) {
+ throwMissingFsModule('fs');
+ }
+ return nodeRuntime.fs;
+};
+
+const nodePathOrThrow = () => {
+ if (!nodeRuntime.path) {
+ throwMissingFsModule('path');
+ }
+ return nodeRuntime.path;
+};
+
+const nodeCwdOrThrow = () => {
+ if (!nodeRuntime.cwd) {
+ throwMissingFsModule('cwd');
+ }
+ return nodeRuntime.cwd;
+};
+
+export { nodeCwdOrThrow, nodeFsOrThrow, nodePathOrThrow };

.changeset/weak-phones-retire.md

@@ -0,0 +1,5 @@
+---
+'@clerk/nextjs': patch
+---
+
+Bug fix: Remove warning for accessing Node APIs when running `next build` with `clerkMiddleware` imported.

packages/nextjs/src/app-router/keyless-actions.ts

@@ -72,6 +72,6 @@ export async function deleteKeylessAction() {
  return;
  }
 
- await import('../server/keyless-node.js').then(m => m.removeKeyless());
+ await import('../server/keyless-node.js').then(m => m.removeKeyless()).catch(() => {});
  return;
 }

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

@@ -8,6 +8,7 @@ import { createClerkClientWithOptions } from '../../server/createClerkClient';
 import type { NextClerkProviderProps } from '../../types';
 import { canUseKeyless } from '../../utils/feature-flags';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
+import { onlyTry } from '../../utils/only-try';
 import { isNext13 } from '../../utils/sdk-versions';
 import { ClientClerkProvider } from '../client/ClerkProvider';
 import { deleteKeylessAction } from '../keyless-actions';
@@ -24,15 +25,6 @@ const getNonceFromCSPHeader = React.cache(async function getNonceFromCSPHeader()
  return getScriptNonceFromHeader((await headers()).get('Content-Security-Policy') || '') || '';
 });
 
-/** Discards errors thrown by attempted code */
-const onlyTry = (cb: () => unknown) => {
- try {
- cb();
- } catch {
- // ignore
- }
-};
-
 export async function ClerkProvider(
  props: Without<NextClerkProviderProps, '__unstable_invokeMiddlewareOnAuthStateChange'>,
 ) {

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

@@ -3,12 +3,13 @@ import { constants, createClerkRequest, createRedirect, type RedirectFun } from
 import { notFound, redirect } from 'next/navigation';
 
 import { PUBLISHABLE_KEY, SIGN_IN_URL, SIGN_UP_URL } from '../../server/constants';
-import { createGetAuth } from '../../server/createGetAuth';
+import { createAsyncGetAuth } from '../../server/createGetAuth';
 import { authAuthHeaderMissing } from '../../server/errors';
 import { getAuthKeyFromRequest, getHeader } from '../../server/headers-utils';
 import type { AuthProtect } from '../../server/protect';
 import { createProtect } from '../../server/protect';
 import { decryptClerkRequestData } from '../../server/utils';
+import { isNextWithUnstableServerActions } from '../../utils/sdk-versions';
 import { buildRequestLike } from './utils';
 
 /**
@@ -25,8 +26,10 @@ type Auth = AuthObject & {
  */
  redirectToSignIn: RedirectFun<ReturnType<typeof redirect>>;
 };
+
 export interface AuthFn {
  (): Promise<Auth>;
+
  /**
  * `auth` includes a single property, the `protect()` method, which you can use in two ways:
  * - to check if a user is authenticated (signed in)
@@ -60,9 +63,22 @@ export const auth: AuthFn = async () => {
  require('server-only');
 
  const request = await buildRequestLike();
- const authObject = createGetAuth({
+
+ const stepsBasedOnSrcDirectory = async () => {
+ if (isNextWithUnstableServerActions) {
+ return [];
+ }
+
+ try {
+ const isSrcAppDir = await import('../../server/fs/middleware-location.js').then(m => m.hasSrcAppDir());
+ return [`Your Middleware exists at ./${isSrcAppDir ? 'src/' : ''}middleware.(ts|js)`];
+ } catch {
+ return [];
+ }
+ };
+ const authObject = await createAsyncGetAuth({
  debugLoggerName: 'auth()',
- noAuthStatusMessage: authAuthHeaderMissing(),
+ noAuthStatusMessage: authAuthHeaderMissing('auth', await stepsBasedOnSrcDirectory()),
  })(request);
 
  const clerkUrl = getAuthKeyFromRequest(request, 'ClerkUrl');

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

@@ -34,7 +34,7 @@ export async function buildRequestLike(): Promise<NextRequest> {
  }
 
  throw new Error(
- `Clerk: auth()and currentUser() are only supported in App Router (/app directory).\nIf you're using /pages, try getAuth() instead.\nOriginal error: ${e}`,
+ `Clerk: auth(), currentUser() and clerkClient(), are only supported in App Router (/app directory).\nIf you're using /pages, try getAuth() instead.\nOriginal error: ${e}`,
  );
  }
 }

packages/nextjs/src/runtime/browser/safe-node-apis.js

@@ -3,5 +3,6 @@
  */
 const fs = undefined;
 const path = undefined;
+const cwd = undefined;
 
-module.exports = { fs, path };
+module.exports = { fs, path, cwd };

packages/nextjs/src/runtime/node/safe-node-apis.js

@@ -14,4 +14,6 @@ const fs = {
  rmSync,
 };
 
-module.exports = { fs, path };
+const cwd = () => process.cwd();
+
+module.exports = { fs, path, cwd };

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

@@ -3,7 +3,7 @@ import hmacSHA1 from 'crypto-js/hmac-sha1';
 import { NextRequest } from 'next/server';
 import { describe, expect, it } from 'vitest';
 
-import { createGetAuth, getAuth } from '../createGetAuth';
+import { createSyncGetAuth, getAuth } from '../createGetAuth';
 
 const mockSecretKey = 'sk_test_mock';
 
@@ -16,7 +16,7 @@ const mockTokenSignature = hmacSHA1(mockToken, 'sk_test_mock').toString();
 
 describe('createGetAuth(opts)', () => {
  it('returns a getAuth function', () => {
- expect(createGetAuth({ debugLoggerName: 'test', noAuthStatusMessage: 'test' })).toBeInstanceOf(Function);
+ expect(createSyncGetAuth({ debugLoggerName: 'test', noAuthStatusMessage: 'test' })).toBeInstanceOf(Function);
  });
 });
 

packages/nextjs/src/server/createGetAuth.ts

@@ -3,15 +3,60 @@ import { constants } from '@clerk/backend/internal';
 import { isTruthy } from '@clerk/shared/underscore';
 
 import { withLogger } from '../utils/debugLogger';
+import { isNextWithUnstableServerActions } from '../utils/sdk-versions';
 import { getAuthDataFromRequest } from './data/getAuthDataFromRequest';
 import { getAuthAuthHeaderMissing } from './errors';
-import { getHeader } from './headers-utils';
+import { detectClerkMiddleware, getHeader } from './headers-utils';
 import type { RequestLike } from './types';
 import { assertAuthStatus } from './utils';
 
-export const createGetAuth = ({
+/**
+ * The async variant of our old `createGetAuth` allows for asynchronous code inside its callback.
+ * Should be used with function like `auth()` that are already asynchronous.
+ */
+export const createAsyncGetAuth = ({
+ debugLoggerName,
  noAuthStatusMessage,
+}: {
+ debugLoggerName: string;
+ noAuthStatusMessage: string;
+}) =>
+ withLogger(debugLoggerName, logger => {
+ return async (req: RequestLike, opts?: { secretKey?: string }): Promise<AuthObject> => {
+ if (isTruthy(getHeader(req, constants.Headers.EnableDebug))) {
+ logger.enable();
+ }
+
+ if (!detectClerkMiddleware(req)) {
+ // Keep the same behaviour for versions that may have issues with bundling `node:fs`
+ if (isNextWithUnstableServerActions) {
+ assertAuthStatus(req, noAuthStatusMessage);
+ }
+
+ const missConfiguredMiddlewareLocation = await import('./fs/middleware-location.js')
+ .then(m => m.suggestMiddlewareLocation())
+ .catch(() => undefined);
+
+ if (missConfiguredMiddlewareLocation) {
+ throw new Error(missConfiguredMiddlewareLocation);
+ }
+
+ // still throw there is no suggested move location
+ assertAuthStatus(req, noAuthStatusMessage);
+ }
+
+ return getAuthDataFromRequest(req, { ...opts, logger });
+ };
+ });
+
+/**
+ * Previous known as `createGetAuth`. We needed to create a sync and async variant in order to allow for improvements
+ * that required dynamic imports (using `require` would not work).
+ * It powers the synchronous top-level api `getAuh()`.
+ */
+export const createSyncGetAuth = ({
  debugLoggerName,
+ noAuthStatusMessage,
 }: {
  debugLoggerName: string;
  noAuthStatusMessage: string;
@@ -23,7 +68,6 @@ export const createGetAuth = ({
  }
 
  assertAuthStatus(req, noAuthStatusMessage);
-
  return getAuthDataFromRequest(req, { ...opts, logger });
  };
  });
@@ -107,7 +151,7 @@ export const createGetAuth = ({
  * }
  * ```
  */
-export const getAuth = createGetAuth({
+export const getAuth = createSyncGetAuth({
  debugLoggerName: 'getAuth()',
  noAuthStatusMessage: getAuthAuthHeaderMissing(),
 });

packages/nextjs/src/server/errors.ts

@@ -20,9 +20,9 @@ Check if signInUrl is missing from your configuration or if it is not an absolut
 
 export const getAuthAuthHeaderMissing = () => authAuthHeaderMissing('getAuth');
 
-export const authAuthHeaderMissing = (helperName = 'auth') =>
+export const authAuthHeaderMissing = (helperName = 'auth', prefixSteps?: string[]) =>
  `Clerk: ${helperName}() was called but Clerk can't detect usage of clerkMiddleware(). Please ensure the following:
-- clerkMiddleware() is used in your Next.js Middleware.
+- ${prefixSteps ? [...prefixSteps, ''].join('\n- ') : ' '}clerkMiddleware() is used in your Next.js Middleware.
 - Your Middleware matcher is configured to match this route or page.
 - If you are using the src directory, make sure the Middleware file is inside of it.
 

packages/nextjs/src/server/fs/middleware-location.ts

@@ -0,0 +1,55 @@
+import { nodeCwdOrThrow, nodeFsOrThrow, nodePathOrThrow } from './utils';
+
+function hasSrcAppDir() {
+ const { existsSync } = nodeFsOrThrow();
+ const path = nodePathOrThrow();
+ const cwd = nodeCwdOrThrow();
+
+ const projectWithAppSrc = path.join(cwd(), 'src', 'app');
+
+ return !!existsSync(projectWithAppSrc);
+}
+
+function suggestMiddlewareLocation() {
+ const fileExtensions = ['ts', 'js'] as const;
+ const suggestionMessage = (
+ extension: (typeof fileExtensions)[number],
+ to: 'src/' | '',
+ from: 'src/app/' | 'app/' | '',
+ ) =>
+ `Clerk: clerkMiddleware() was not run, your middleware file might be misplaced. Move your middleware file to ./${to}middleware.${extension}. Currently located at ./${from}middleware.${extension}`;
+
+ const { existsSync } = nodeFsOrThrow();
+ const path = nodePathOrThrow();
+ const cwd = nodeCwdOrThrow();
+
+ const projectWithAppSrcPath = path.join(cwd(), 'src', 'app');
+ const projectWithAppPath = path.join(cwd(), 'app');
+
+ const checkMiddlewareLocation = (
+ basePath: string,
+ to: 'src/' | '',
+ from: 'src/app/' | 'app/' | '',
+ ): string | undefined => {
+ for (const fileExtension of fileExtensions) {
+ if (existsSync(path.join(basePath, `middleware.${fileExtension}`))) {
+ return suggestionMessage(fileExtension, to, from);
+ }
+ }
+ return undefined;
+ };
+
+ if (existsSync(projectWithAppSrcPath)) {
+ return (
+ checkMiddlewareLocation(projectWithAppSrcPath, 'src/', 'src/app/') || checkMiddlewareLocation(cwd(), 'src/', '')
+ );
+ }
+
+ if (existsSync(projectWithAppPath)) {
+ return checkMiddlewareLocation(projectWithAppPath, '', 'app/');
+ }
+
+ return undefined;
+}
+
+export { suggestMiddlewareLocation, hasSrcAppDir };

packages/nextjs/src/server/fs/utils.ts

@@ -0,0 +1,33 @@
+/**
+ * Attention: Only import this module when the node runtime is used.
+ * We are using conditional imports to mitigate bundling issues with Next.js server actions on version prior to 14.1.0.
+ */
+// @ts-ignore
+import nodeRuntime from '#safe-node-apis';
+
+const throwMissingFsModule = (module: string) => {
+ throw new Error(`Clerk: ${module} is missing. This is an internal error. Please contact Clerk's support.`);
+};
+
+const nodeFsOrThrow = () => {
+ if (!nodeRuntime.fs) {
+ throwMissingFsModule('fs');
+ }
+ return nodeRuntime.fs;
+};
+
+const nodePathOrThrow = () => {
+ if (!nodeRuntime.path) {
+ throwMissingFsModule('path');
+ }
+ return nodeRuntime.path;
+};
+
+const nodeCwdOrThrow = () => {
+ if (!nodeRuntime.cwd) {
+ throwMissingFsModule('cwd');
+ }
+ return nodeRuntime.cwd;
+};
+
+export { nodeCwdOrThrow, nodeFsOrThrow, nodePathOrThrow };

.changeset/weak-phones-retire.md

@@ -0,0 +1,5 @@
+---
+'@clerk/nextjs': patch
+---
+
+Bug fix: Remove warning for accessing Node APIs when running `next build` with `clerkMiddleware` imported.

packages/nextjs/src/app-router/keyless-actions.ts

@@ -72,6 +72,6 @@ export async function deleteKeylessAction() {
  return;
  }
 
- await import('../server/keyless-node.js').then(m => m.removeKeyless());
+ await import('../server/keyless-node.js').then(m => m.removeKeyless()).catch(() => {});
  return;
 }

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

@@ -8,6 +8,7 @@ import { createClerkClientWithOptions } from '../../server/createClerkClient';
 import type { NextClerkProviderProps } from '../../types';
 import { canUseKeyless } from '../../utils/feature-flags';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
+import { onlyTry } from '../../utils/only-try';
 import { isNext13 } from '../../utils/sdk-versions';
 import { ClientClerkProvider } from '../client/ClerkProvider';
 import { deleteKeylessAction } from '../keyless-actions';
@@ -24,15 +25,6 @@ const getNonceFromCSPHeader = React.cache(async function getNonceFromCSPHeader()
  return getScriptNonceFromHeader((await headers()).get('Content-Security-Policy') || '') || '';
 });
 
-/** Discards errors thrown by attempted code */
-const onlyTry = (cb: () => unknown) => {
- try {
- cb();
- } catch {
- // ignore
- }
-};
-
 export async function ClerkProvider(
  props: Without<NextClerkProviderProps, '__unstable_invokeMiddlewareOnAuthStateChange'>,
 ) {

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

@@ -3,12 +3,13 @@ import { constants, createClerkRequest, createRedirect, type RedirectFun } from
 import { notFound, redirect } from 'next/navigation';
 
 import { PUBLISHABLE_KEY, SIGN_IN_URL, SIGN_UP_URL } from '../../server/constants';
-import { createGetAuth } from '../../server/createGetAuth';
+import { createAsyncGetAuth } from '../../server/createGetAuth';
 import { authAuthHeaderMissing } from '../../server/errors';
 import { getAuthKeyFromRequest, getHeader } from '../../server/headers-utils';
 import type { AuthProtect } from '../../server/protect';
 import { createProtect } from '../../server/protect';
 import { decryptClerkRequestData } from '../../server/utils';
+import { isNextWithUnstableServerActions } from '../../utils/sdk-versions';
 import { buildRequestLike } from './utils';
 
 /**
@@ -25,8 +26,10 @@ type Auth = AuthObject & {
  */
  redirectToSignIn: RedirectFun<ReturnType<typeof redirect>>;
 };
+
 export interface AuthFn {
  (): Promise<Auth>;
+
  /**
  * `auth` includes a single property, the `protect()` method, which you can use in two ways:
  * - to check if a user is authenticated (signed in)
@@ -60,9 +63,22 @@ export const auth: AuthFn = async () => {
  require('server-only');
 
  const request = await buildRequestLike();
- const authObject = createGetAuth({
+
+ const stepsBasedOnSrcDirectory = async () => {
+ if (isNextWithUnstableServerActions) {
+ return [];
+ }
+
+ try {
+ const isSrcAppDir = await import('../../server/fs/middleware-location.js').then(m => m.hasSrcAppDir());
+ return [`Your Middleware exists at ./${isSrcAppDir ? 'src/' : ''}middleware.(ts|js)`];
+ } catch {
+ return [];
+ }
+ };
+ const authObject = await createAsyncGetAuth({
  debugLoggerName: 'auth()',
- noAuthStatusMessage: authAuthHeaderMissing(),
+ noAuthStatusMessage: authAuthHeaderMissing('auth', await stepsBasedOnSrcDirectory()),
  })(request);
 
  const clerkUrl = getAuthKeyFromRequest(request, 'ClerkUrl');

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

@@ -34,7 +34,7 @@ export async function buildRequestLike(): Promise<NextRequest> {
  }
 
  throw new Error(
- `Clerk: auth()and currentUser() are only supported in App Router (/app directory).\nIf you're using /pages, try getAuth() instead.\nOriginal error: ${e}`,
+ `Clerk: auth(), currentUser() and clerkClient(), are only supported in App Router (/app directory).\nIf you're using /pages, try getAuth() instead.\nOriginal error: ${e}`,
  );
  }
 }

packages/nextjs/src/runtime/browser/safe-node-apis.js

@@ -3,5 +3,6 @@
  */
 const fs = undefined;
 const path = undefined;
+const cwd = undefined;
 
-module.exports = { fs, path };
+module.exports = { fs, path, cwd };

packages/nextjs/src/runtime/node/safe-node-apis.js

@@ -14,4 +14,6 @@ const fs = {
  rmSync,
 };
 
-module.exports = { fs, path };
+const cwd = () => process.cwd();
+
+module.exports = { fs, path, cwd };

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

@@ -3,7 +3,7 @@ import hmacSHA1 from 'crypto-js/hmac-sha1';
 import { NextRequest } from 'next/server';
 import { describe, expect, it } from 'vitest';
 
-import { createGetAuth, getAuth } from '../createGetAuth';
+import { createSyncGetAuth, getAuth } from '../createGetAuth';
 
 const mockSecretKey = 'sk_test_mock';
 
@@ -16,7 +16,7 @@ const mockTokenSignature = hmacSHA1(mockToken, 'sk_test_mock').toString();
 
 describe('createGetAuth(opts)', () => {
  it('returns a getAuth function', () => {
- expect(createGetAuth({ debugLoggerName: 'test', noAuthStatusMessage: 'test' })).toBeInstanceOf(Function);
+ expect(createSyncGetAuth({ debugLoggerName: 'test', noAuthStatusMessage: 'test' })).toBeInstanceOf(Function);
  });
 });
 

packages/nextjs/src/server/createGetAuth.ts

@@ -3,15 +3,60 @@ import { constants } from '@clerk/backend/internal';
 import { isTruthy } from '@clerk/shared/underscore';
 
 import { withLogger } from '../utils/debugLogger';
+import { isNextWithUnstableServerActions } from '../utils/sdk-versions';
 import { getAuthDataFromRequest } from './data/getAuthDataFromRequest';
 import { getAuthAuthHeaderMissing } from './errors';
-import { getHeader } from './headers-utils';
+import { detectClerkMiddleware, getHeader } from './headers-utils';
 import type { RequestLike } from './types';
 import { assertAuthStatus } from './utils';
 
-export const createGetAuth = ({
+/**
+ * The async variant of our old `createGetAuth` allows for asynchronous code inside its callback.
+ * Should be used with function like `auth()` that are already asynchronous.
+ */
+export const createAsyncGetAuth = ({
+ debugLoggerName,
  noAuthStatusMessage,
+}: {
+ debugLoggerName: string;
+ noAuthStatusMessage: string;
+}) =>
+ withLogger(debugLoggerName, logger => {
+ return async (req: RequestLike, opts?: { secretKey?: string }): Promise<AuthObject> => {
+ if (isTruthy(getHeader(req, constants.Headers.EnableDebug))) {
+ logger.enable();
+ }
+
+ if (!detectClerkMiddleware(req)) {
+ // Keep the same behaviour for versions that may have issues with bundling `node:fs`
+ if (isNextWithUnstableServerActions) {
+ assertAuthStatus(req, noAuthStatusMessage);
+ }
+
+ const missConfiguredMiddlewareLocation = await import('./fs/middleware-location.js')
+ .then(m => m.suggestMiddlewareLocation())
+ .catch(() => undefined);
+
+ if (missConfiguredMiddlewareLocation) {
+ throw new Error(missConfiguredMiddlewareLocation);
+ }
+
+ // still throw there is no suggested move location
+ assertAuthStatus(req, noAuthStatusMessage);
+ }
+
+ return getAuthDataFromRequest(req, { ...opts, logger });
+ };
+ });
+
+/**
+ * Previous known as `createGetAuth`. We needed to create a sync and async variant in order to allow for improvements
+ * that required dynamic imports (using `require` would not work).
+ * It powers the synchronous top-level api `getAuh()`.
+ */
+export const createSyncGetAuth = ({
  debugLoggerName,
+ noAuthStatusMessage,
 }: {
  debugLoggerName: string;
  noAuthStatusMessage: string;
@@ -23,7 +68,6 @@ export const createGetAuth = ({
  }
 
  assertAuthStatus(req, noAuthStatusMessage);
-
  return getAuthDataFromRequest(req, { ...opts, logger });
  };
  });
@@ -107,7 +151,7 @@ export const createGetAuth = ({
  * }
  * ```
  */
-export const getAuth = createGetAuth({
+export const getAuth = createSyncGetAuth({
  debugLoggerName: 'getAuth()',
  noAuthStatusMessage: getAuthAuthHeaderMissing(),
 });

packages/nextjs/src/server/errors.ts

@@ -20,9 +20,9 @@ Check if signInUrl is missing from your configuration or if it is not an absolut
 
 export const getAuthAuthHeaderMissing = () => authAuthHeaderMissing('getAuth');
 
-export const authAuthHeaderMissing = (helperName = 'auth') =>
+export const authAuthHeaderMissing = (helperName = 'auth', prefixSteps?: string[]) =>
  `Clerk: ${helperName}() was called but Clerk can't detect usage of clerkMiddleware(). Please ensure the following:
-- clerkMiddleware() is used in your Next.js Middleware.
+- ${prefixSteps ? [...prefixSteps, ''].join('\n- ') : ' '}clerkMiddleware() is used in your Next.js Middleware.
 - Your Middleware matcher is configured to match this route or page.
 - If you are using the src directory, make sure the Middleware file is inside of it.
 

packages/nextjs/src/server/fs/middleware-location.ts

@@ -0,0 +1,55 @@
+import { nodeCwdOrThrow, nodeFsOrThrow, nodePathOrThrow } from './utils';
+
+function hasSrcAppDir() {
+ const { existsSync } = nodeFsOrThrow();
+ const path = nodePathOrThrow();
+ const cwd = nodeCwdOrThrow();
+
+ const projectWithAppSrc = path.join(cwd(), 'src', 'app');
+
+ return !!existsSync(projectWithAppSrc);
+}
+
+function suggestMiddlewareLocation() {
+ const fileExtensions = ['ts', 'js'] as const;
+ const suggestionMessage = (
+ extension: (typeof fileExtensions)[number],
+ to: 'src/' | '',
+ from: 'src/app/' | 'app/' | '',
+ ) =>
+ `Clerk: clerkMiddleware() was not run, your middleware file might be misplaced. Move your middleware file to ./${to}middleware.${extension}. Currently located at ./${from}middleware.${extension}`;
+
+ const { existsSync } = nodeFsOrThrow();
+ const path = nodePathOrThrow();
+ const cwd = nodeCwdOrThrow();
+
+ const projectWithAppSrcPath = path.join(cwd(), 'src', 'app');
+ const projectWithAppPath = path.join(cwd(), 'app');
+
+ const checkMiddlewareLocation = (
+ basePath: string,
+ to: 'src/' | '',
+ from: 'src/app/' | 'app/' | '',
+ ): string | undefined => {
+ for (const fileExtension of fileExtensions) {
+ if (existsSync(path.join(basePath, `middleware.${fileExtension}`))) {
+ return suggestionMessage(fileExtension, to, from);
+ }
+ }
+ return undefined;
+ };
+
+ if (existsSync(projectWithAppSrcPath)) {
+ return (
+ checkMiddlewareLocation(projectWithAppSrcPath, 'src/', 'src/app/') || checkMiddlewareLocation(cwd(), 'src/', '')
+ );
+ }
+
+ if (existsSync(projectWithAppPath)) {
+ return checkMiddlewareLocation(projectWithAppPath, '', 'app/');
+ }
+
+ return undefined;
+}
+
+export { suggestMiddlewareLocation, hasSrcAppDir };

packages/nextjs/src/server/fs/utils.ts

@@ -0,0 +1,33 @@
+/**
+ * Attention: Only import this module when the node runtime is used.
+ * We are using conditional imports to mitigate bundling issues with Next.js server actions on version prior to 14.1.0.
+ */
+// @ts-ignore
+import nodeRuntime from '#safe-node-apis';
+
+const throwMissingFsModule = (module: string) => {
+ throw new Error(`Clerk: ${module} is missing. This is an internal error. Please contact Clerk's support.`);
+};
+
+const nodeFsOrThrow = () => {
+ if (!nodeRuntime.fs) {
+ throwMissingFsModule('fs');
+ }
+ return nodeRuntime.fs;
+};
+
+const nodePathOrThrow = () => {
+ if (!nodeRuntime.path) {
+ throwMissingFsModule('path');
+ }
+ return nodeRuntime.path;
+};
+
+const nodeCwdOrThrow = () => {
+ if (!nodeRuntime.cwd) {
+ throwMissingFsModule('cwd');
+ }
+ return nodeRuntime.cwd;
+};
+
+export { nodeCwdOrThrow, nodeFsOrThrow, nodePathOrThrow };

.changeset/weak-phones-retire.md

@@ -0,0 +1,5 @@
+---
+'@clerk/nextjs': patch
+---
+
+Bug fix: Remove warning for accessing Node APIs when running `next build` with `clerkMiddleware` imported.

packages/nextjs/src/app-router/keyless-actions.ts

@@ -72,6 +72,6 @@ export async function deleteKeylessAction() {
  return;
  }
 
- await import('../server/keyless-node.js').then(m => m.removeKeyless());
+ await import('../server/keyless-node.js').then(m => m.removeKeyless()).catch(() => {});
  return;
 }

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

@@ -8,6 +8,7 @@ import { createClerkClientWithOptions } from '../../server/createClerkClient';
 import type { NextClerkProviderProps } from '../../types';
 import { canUseKeyless } from '../../utils/feature-flags';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
+import { onlyTry } from '../../utils/only-try';
 import { isNext13 } from '../../utils/sdk-versions';
 import { ClientClerkProvider } from '../client/ClerkProvider';
 import { deleteKeylessAction } from '../keyless-actions';
@@ -24,15 +25,6 @@ const getNonceFromCSPHeader = React.cache(async function getNonceFromCSPHeader()
  return getScriptNonceFromHeader((await headers()).get('Content-Security-Policy') || '') || '';
 });
 
-/** Discards errors thrown by attempted code */
-const onlyTry = (cb: () => unknown) => {
- try {
- cb();
- } catch {
- // ignore
- }
-};
-
 export async function ClerkProvider(
  props: Without<NextClerkProviderProps, '__unstable_invokeMiddlewareOnAuthStateChange'>,
 ) {

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

@@ -3,12 +3,13 @@ import { constants, createClerkRequest, createRedirect, type RedirectFun } from
 import { notFound, redirect } from 'next/navigation';
 
 import { PUBLISHABLE_KEY, SIGN_IN_URL, SIGN_UP_URL } from '../../server/constants';
-import { createGetAuth } from '../../server/createGetAuth';
+import { createAsyncGetAuth } from '../../server/createGetAuth';
 import { authAuthHeaderMissing } from '../../server/errors';
 import { getAuthKeyFromRequest, getHeader } from '../../server/headers-utils';
 import type { AuthProtect } from '../../server/protect';
 import { createProtect } from '../../server/protect';
 import { decryptClerkRequestData } from '../../server/utils';
+import { isNextWithUnstableServerActions } from '../../utils/sdk-versions';
 import { buildRequestLike } from './utils';
 
 /**
@@ -25,8 +26,10 @@ type Auth = AuthObject & {
  */
  redirectToSignIn: RedirectFun<ReturnType<typeof redirect>>;
 };
+
 export interface AuthFn {
  (): Promise<Auth>;
+
  /**
  * `auth` includes a single property, the `protect()` method, which you can use in two ways:
  * - to check if a user is authenticated (signed in)
@@ -60,9 +63,22 @@ export const auth: AuthFn = async () => {
  require('server-only');
 
  const request = await buildRequestLike();
- const authObject = createGetAuth({
+
+ const stepsBasedOnSrcDirectory = async () => {
+ if (isNextWithUnstableServerActions) {
+ return [];
+ }
+
+ try {
+ const isSrcAppDir = await import('../../server/fs/middleware-location.js').then(m => m.hasSrcAppDir());
+ return [`Your Middleware exists at ./${isSrcAppDir ? 'src/' : ''}middleware.(ts|js)`];
+ } catch {
+ return [];
+ }
+ };
+ const authObject = await createAsyncGetAuth({
  debugLoggerName: 'auth()',
- noAuthStatusMessage: authAuthHeaderMissing(),
+ noAuthStatusMessage: authAuthHeaderMissing('auth', await stepsBasedOnSrcDirectory()),
  })(request);
 
  const clerkUrl = getAuthKeyFromRequest(request, 'ClerkUrl');

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

@@ -34,7 +34,7 @@ export async function buildRequestLike(): Promise<NextRequest> {
  }
 
  throw new Error(
- `Clerk: auth()and currentUser() are only supported in App Router (/app directory).\nIf you're using /pages, try getAuth() instead.\nOriginal error: ${e}`,
+ `Clerk: auth(), currentUser() and clerkClient(), are only supported in App Router (/app directory).\nIf you're using /pages, try getAuth() instead.\nOriginal error: ${e}`,
  );
  }
 }

packages/nextjs/src/runtime/browser/safe-node-apis.js

@@ -3,5 +3,6 @@
  */
 const fs = undefined;
 const path = undefined;
+const cwd = undefined;
 
-module.exports = { fs, path };
+module.exports = { fs, path, cwd };

packages/nextjs/src/runtime/node/safe-node-apis.js

@@ -14,4 +14,6 @@ const fs = {
  rmSync,
 };
 
-module.exports = { fs, path };
+const cwd = () => process.cwd();
+
+module.exports = { fs, path, cwd };

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

@@ -3,7 +3,7 @@ import hmacSHA1 from 'crypto-js/hmac-sha1';
 import { NextRequest } from 'next/server';
 import { describe, expect, it } from 'vitest';
 
-import { createGetAuth, getAuth } from '../createGetAuth';
+import { createSyncGetAuth, getAuth } from '../createGetAuth';
 
 const mockSecretKey = 'sk_test_mock';
 
@@ -16,7 +16,7 @@ const mockTokenSignature = hmacSHA1(mockToken, 'sk_test_mock').toString();
 
 describe('createGetAuth(opts)', () => {
  it('returns a getAuth function', () => {
- expect(createGetAuth({ debugLoggerName: 'test', noAuthStatusMessage: 'test' })).toBeInstanceOf(Function);
+ expect(createSyncGetAuth({ debugLoggerName: 'test', noAuthStatusMessage: 'test' })).toBeInstanceOf(Function);
  });
 });
 

packages/nextjs/src/server/createGetAuth.ts

@@ -3,15 +3,60 @@ import { constants } from '@clerk/backend/internal';
 import { isTruthy } from '@clerk/shared/underscore';
 
 import { withLogger } from '../utils/debugLogger';
+import { isNextWithUnstableServerActions } from '../utils/sdk-versions';
 import { getAuthDataFromRequest } from './data/getAuthDataFromRequest';
 import { getAuthAuthHeaderMissing } from './errors';
-import { getHeader } from './headers-utils';
+import { detectClerkMiddleware, getHeader } from './headers-utils';
 import type { RequestLike } from './types';
 import { assertAuthStatus } from './utils';
 
-export const createGetAuth = ({
+/**
+ * The async variant of our old `createGetAuth` allows for asynchronous code inside its callback.
+ * Should be used with function like `auth()` that are already asynchronous.
+ */
+export const createAsyncGetAuth = ({
+ debugLoggerName,
  noAuthStatusMessage,
+}: {
+ debugLoggerName: string;
+ noAuthStatusMessage: string;
+}) =>
+ withLogger(debugLoggerName, logger => {
+ return async (req: RequestLike, opts?: { secretKey?: string }): Promise<AuthObject> => {
+ if (isTruthy(getHeader(req, constants.Headers.EnableDebug))) {
+ logger.enable();
+ }
+
+ if (!detectClerkMiddleware(req)) {
+ // Keep the same behaviour for versions that may have issues with bundling `node:fs`
+ if (isNextWithUnstableServerActions) {
+ assertAuthStatus(req, noAuthStatusMessage);
+ }
+
+ const missConfiguredMiddlewareLocation = await import('./fs/middleware-location.js')
+ .then(m => m.suggestMiddlewareLocation())
+ .catch(() => undefined);
+
+ if (missConfiguredMiddlewareLocation) {
+ throw new Error(missConfiguredMiddlewareLocation);
+ }
+
+ // still throw there is no suggested move location
+ assertAuthStatus(req, noAuthStatusMessage);
+ }
+
+ return getAuthDataFromRequest(req, { ...opts, logger });
+ };
+ });
+
+/**
+ * Previous known as `createGetAuth`. We needed to create a sync and async variant in order to allow for improvements
+ * that required dynamic imports (using `require` would not work).
+ * It powers the synchronous top-level api `getAuh()`.
+ */
+export const createSyncGetAuth = ({
  debugLoggerName,
+ noAuthStatusMessage,
 }: {
  debugLoggerName: string;
  noAuthStatusMessage: string;
@@ -23,7 +68,6 @@ export const createGetAuth = ({
  }
 
  assertAuthStatus(req, noAuthStatusMessage);
-
  return getAuthDataFromRequest(req, { ...opts, logger });
  };
  });
@@ -107,7 +151,7 @@ export const createGetAuth = ({
  * }
  * ```
  */
-export const getAuth = createGetAuth({
+export const getAuth = createSyncGetAuth({
  debugLoggerName: 'getAuth()',
  noAuthStatusMessage: getAuthAuthHeaderMissing(),
 });

packages/nextjs/src/server/errors.ts

@@ -20,9 +20,9 @@ Check if signInUrl is missing from your configuration or if it is not an absolut
 
 export const getAuthAuthHeaderMissing = () => authAuthHeaderMissing('getAuth');
 
-export const authAuthHeaderMissing = (helperName = 'auth') =>
+export const authAuthHeaderMissing = (helperName = 'auth', prefixSteps?: string[]) =>
  `Clerk: ${helperName}() was called but Clerk can't detect usage of clerkMiddleware(). Please ensure the following:
-- clerkMiddleware() is used in your Next.js Middleware.
+- ${prefixSteps ? [...prefixSteps, ''].join('\n- ') : ' '}clerkMiddleware() is used in your Next.js Middleware.
 - Your Middleware matcher is configured to match this route or page.
 - If you are using the src directory, make sure the Middleware file is inside of it.
 

packages/nextjs/src/server/fs/middleware-location.ts

@@ -0,0 +1,55 @@
+import { nodeCwdOrThrow, nodeFsOrThrow, nodePathOrThrow } from './utils';
+
+function hasSrcAppDir() {
+ const { existsSync } = nodeFsOrThrow();
+ const path = nodePathOrThrow();
+ const cwd = nodeCwdOrThrow();
+
+ const projectWithAppSrc = path.join(cwd(), 'src', 'app');
+
+ return !!existsSync(projectWithAppSrc);
+}
+
+function suggestMiddlewareLocation() {
+ const fileExtensions = ['ts', 'js'] as const;
+ const suggestionMessage = (
+ extension: (typeof fileExtensions)[number],
+ to: 'src/' | '',
+ from: 'src/app/' | 'app/' | '',
+ ) =>
+ `Clerk: clerkMiddleware() was not run, your middleware file might be misplaced. Move your middleware file to ./${to}middleware.${extension}. Currently located at ./${from}middleware.${extension}`;
+
+ const { existsSync } = nodeFsOrThrow();
+ const path = nodePathOrThrow();
+ const cwd = nodeCwdOrThrow();
+
+ const projectWithAppSrcPath = path.join(cwd(), 'src', 'app');
+ const projectWithAppPath = path.join(cwd(), 'app');
+
+ const checkMiddlewareLocation = (
+ basePath: string,
+ to: 'src/' | '',
+ from: 'src/app/' | 'app/' | '',
+ ): string | undefined => {
+ for (const fileExtension of fileExtensions) {
+ if (existsSync(path.join(basePath, `middleware.${fileExtension}`))) {
+ return suggestionMessage(fileExtension, to, from);
+ }
+ }
+ return undefined;
+ };
+
+ if (existsSync(projectWithAppSrcPath)) {
+ return (
+ checkMiddlewareLocation(projectWithAppSrcPath, 'src/', 'src/app/') || checkMiddlewareLocation(cwd(), 'src/', '')
+ );
+ }
+
+ if (existsSync(projectWithAppPath)) {
+ return checkMiddlewareLocation(projectWithAppPath, '', 'app/');
+ }
+
+ return undefined;
+}
+
+export { suggestMiddlewareLocation, hasSrcAppDir };

packages/nextjs/src/server/fs/utils.ts

@@ -0,0 +1,33 @@
+/**
+ * Attention: Only import this module when the node runtime is used.
+ * We are using conditional imports to mitigate bundling issues with Next.js server actions on version prior to 14.1.0.
+ */
+// @ts-ignore
+import nodeRuntime from '#safe-node-apis';
+
+const throwMissingFsModule = (module: string) => {
+ throw new Error(`Clerk: ${module} is missing. This is an internal error. Please contact Clerk's support.`);
+};
+
+const nodeFsOrThrow = () => {
+ if (!nodeRuntime.fs) {
+ throwMissingFsModule('fs');
+ }
+ return nodeRuntime.fs;
+};
+
+const nodePathOrThrow = () => {
+ if (!nodeRuntime.path) {
+ throwMissingFsModule('path');
+ }
+ return nodeRuntime.path;
+};
+
+const nodeCwdOrThrow = () => {
+ if (!nodeRuntime.cwd) {
+ throwMissingFsModule('cwd');
+ }
+ return nodeRuntime.cwd;
+};
+
+export { nodeCwdOrThrow, nodeFsOrThrow, nodePathOrThrow };

.changeset/weak-phones-retire.md

@@ -0,0 +1,5 @@
+---
+'@clerk/nextjs': patch
+---
+
+Bug fix: Remove warning for accessing Node APIs when running `next build` with `clerkMiddleware` imported.

packages/nextjs/src/app-router/keyless-actions.ts

@@ -72,6 +72,6 @@ export async function deleteKeylessAction() {
  return;
  }
 
- await import('../server/keyless-node.js').then(m => m.removeKeyless());
+ await import('../server/keyless-node.js').then(m => m.removeKeyless()).catch(() => {});
  return;
 }

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

@@ -8,6 +8,7 @@ import { createClerkClientWithOptions } from '../../server/createClerkClient';
 import type { NextClerkProviderProps } from '../../types';
 import { canUseKeyless } from '../../utils/feature-flags';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
+import { onlyTry } from '../../utils/only-try';
 import { isNext13 } from '../../utils/sdk-versions';
 import { ClientClerkProvider } from '../client/ClerkProvider';
 import { deleteKeylessAction } from '../keyless-actions';
@@ -24,15 +25,6 @@ const getNonceFromCSPHeader = React.cache(async function getNonceFromCSPHeader()
  return getScriptNonceFromHeader((await headers()).get('Content-Security-Policy') || '') || '';
 });
 
-/** Discards errors thrown by attempted code */
-const onlyTry = (cb: () => unknown) => {
- try {
- cb();
- } catch {
- // ignore
- }
-};
-
 export async function ClerkProvider(
  props: Without<NextClerkProviderProps, '__unstable_invokeMiddlewareOnAuthStateChange'>,
 ) {

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

@@ -3,12 +3,13 @@ import { constants, createClerkRequest, createRedirect, type RedirectFun } from
 import { notFound, redirect } from 'next/navigation';
 
 import { PUBLISHABLE_KEY, SIGN_IN_URL, SIGN_UP_URL } from '../../server/constants';
-import { createGetAuth } from '../../server/createGetAuth';
+import { createAsyncGetAuth } from '../../server/createGetAuth';
 import { authAuthHeaderMissing } from '../../server/errors';
 import { getAuthKeyFromRequest, getHeader } from '../../server/headers-utils';
 import type { AuthProtect } from '../../server/protect';
 import { createProtect } from '../../server/protect';
 import { decryptClerkRequestData } from '../../server/utils';
+import { isNextWithUnstableServerActions } from '../../utils/sdk-versions';
 import { buildRequestLike } from './utils';
 
 /**
@@ -25,8 +26,10 @@ type Auth = AuthObject & {
  */
  redirectToSignIn: RedirectFun<ReturnType<typeof redirect>>;
 };
+
 export interface AuthFn {
  (): Promise<Auth>;
+
  /**
  * `auth` includes a single property, the `protect()` method, which you can use in two ways:
  * - to check if a user is authenticated (signed in)
@@ -60,9 +63,22 @@ export const auth: AuthFn = async () => {
  require('server-only');
 
  const request = await buildRequestLike();
- const authObject = createGetAuth({
+
+ const stepsBasedOnSrcDirectory = async () => {
+ if (isNextWithUnstableServerActions) {
+ return [];
+ }
+
+ try {
+ const isSrcAppDir = await import('../../server/fs/middleware-location.js').then(m => m.hasSrcAppDir());
+ return [`Your Middleware exists at ./${isSrcAppDir ? 'src/' : ''}middleware.(ts|js)`];
+ } catch {
+ return [];
+ }
+ };
+ const authObject = await createAsyncGetAuth({
  debugLoggerName: 'auth()',
- noAuthStatusMessage: authAuthHeaderMissing(),
+ noAuthStatusMessage: authAuthHeaderMissing('auth', await stepsBasedOnSrcDirectory()),
  })(request);
 
  const clerkUrl = getAuthKeyFromRequest(request, 'ClerkUrl');

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

@@ -34,7 +34,7 @@ export async function buildRequestLike(): Promise<NextRequest> {
  }
 
  throw new Error(
- `Clerk: auth()and currentUser() are only supported in App Router (/app directory).\nIf you're using /pages, try getAuth() instead.\nOriginal error: ${e}`,
+ `Clerk: auth(), currentUser() and clerkClient(), are only supported in App Router (/app directory).\nIf you're using /pages, try getAuth() instead.\nOriginal error: ${e}`,
  );
  }
 }

packages/nextjs/src/runtime/browser/safe-node-apis.js

@@ -3,5 +3,6 @@
  */
 const fs = undefined;
 const path = undefined;
+const cwd = undefined;
 
-module.exports = { fs, path };
+module.exports = { fs, path, cwd };

packages/nextjs/src/runtime/node/safe-node-apis.js

@@ -14,4 +14,6 @@ const fs = {
  rmSync,
 };
 
-module.exports = { fs, path };
+const cwd = () => process.cwd();
+
+module.exports = { fs, path, cwd };

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

@@ -3,7 +3,7 @@ import hmacSHA1 from 'crypto-js/hmac-sha1';
 import { NextRequest } from 'next/server';
 import { describe, expect, it } from 'vitest';
 
-import { createGetAuth, getAuth } from '../createGetAuth';
+import { createSyncGetAuth, getAuth } from '../createGetAuth';
 
 const mockSecretKey = 'sk_test_mock';
 
@@ -16,7 +16,7 @@ const mockTokenSignature = hmacSHA1(mockToken, 'sk_test_mock').toString();
 
 describe('createGetAuth(opts)', () => {
  it('returns a getAuth function', () => {
- expect(createGetAuth({ debugLoggerName: 'test', noAuthStatusMessage: 'test' })).toBeInstanceOf(Function);
+ expect(createSyncGetAuth({ debugLoggerName: 'test', noAuthStatusMessage: 'test' })).toBeInstanceOf(Function);
  });
 });
 

packages/nextjs/src/server/createGetAuth.ts

@@ -3,15 +3,60 @@ import { constants } from '@clerk/backend/internal';
 import { isTruthy } from '@clerk/shared/underscore';
 
 import { withLogger } from '../utils/debugLogger';
+import { isNextWithUnstableServerActions } from '../utils/sdk-versions';
 import { getAuthDataFromRequest } from './data/getAuthDataFromRequest';
 import { getAuthAuthHeaderMissing } from './errors';
-import { getHeader } from './headers-utils';
+import { detectClerkMiddleware, getHeader } from './headers-utils';
 import type { RequestLike } from './types';
 import { assertAuthStatus } from './utils';
 
-export const createGetAuth = ({
+/**
+ * The async variant of our old `createGetAuth` allows for asynchronous code inside its callback.
+ * Should be used with function like `auth()` that are already asynchronous.
+ */
+export const createAsyncGetAuth = ({
+ debugLoggerName,
  noAuthStatusMessage,
+}: {
+ debugLoggerName: string;
+ noAuthStatusMessage: string;
+}) =>
+ withLogger(debugLoggerName, logger => {
+ return async (req: RequestLike, opts?: { secretKey?: string }): Promise<AuthObject> => {
+ if (isTruthy(getHeader(req, constants.Headers.EnableDebug))) {
+ logger.enable();
+ }
+
+ if (!detectClerkMiddleware(req)) {
+ // Keep the same behaviour for versions that may have issues with bundling `node:fs`
+ if (isNextWithUnstableServerActions) {
+ assertAuthStatus(req, noAuthStatusMessage);
+ }
+
+ const missConfiguredMiddlewareLocation = await import('./fs/middleware-location.js')
+ .then(m => m.suggestMiddlewareLocation())
+ .catch(() => undefined);
+
+ if (missConfiguredMiddlewareLocation) {
+ throw new Error(missConfiguredMiddlewareLocation);
+ }
+
+ // still throw there is no suggested move location
+ assertAuthStatus(req, noAuthStatusMessage);
+ }
+
+ return getAuthDataFromRequest(req, { ...opts, logger });
+ };
+ });
+
+/**
+ * Previous known as `createGetAuth`. We needed to create a sync and async variant in order to allow for improvements
+ * that required dynamic imports (using `require` would not work).
+ * It powers the synchronous top-level api `getAuh()`.
+ */
+export const createSyncGetAuth = ({
  debugLoggerName,
+ noAuthStatusMessage,
 }: {
  debugLoggerName: string;
  noAuthStatusMessage: string;
@@ -23,7 +68,6 @@ export const createGetAuth = ({
  }
 
  assertAuthStatus(req, noAuthStatusMessage);
-
  return getAuthDataFromRequest(req, { ...opts, logger });
  };
  });
@@ -107,7 +151,7 @@ export const createGetAuth = ({
  * }
  * ```
  */
-export const getAuth = createGetAuth({
+export const getAuth = createSyncGetAuth({
  debugLoggerName: 'getAuth()',
  noAuthStatusMessage: getAuthAuthHeaderMissing(),
 });

packages/nextjs/src/server/errors.ts

@@ -20,9 +20,9 @@ Check if signInUrl is missing from your configuration or if it is not an absolut
 
 export const getAuthAuthHeaderMissing = () => authAuthHeaderMissing('getAuth');
 
-export const authAuthHeaderMissing = (helperName = 'auth') =>
+export const authAuthHeaderMissing = (helperName = 'auth', prefixSteps?: string[]) =>
  `Clerk: ${helperName}() was called but Clerk can't detect usage of clerkMiddleware(). Please ensure the following:
-- clerkMiddleware() is used in your Next.js Middleware.
+- ${prefixSteps ? [...prefixSteps, ''].join('\n- ') : ' '}clerkMiddleware() is used in your Next.js Middleware.
 - Your Middleware matcher is configured to match this route or page.
 - If you are using the src directory, make sure the Middleware file is inside of it.
 

packages/nextjs/src/server/fs/middleware-location.ts

@@ -0,0 +1,55 @@
+import { nodeCwdOrThrow, nodeFsOrThrow, nodePathOrThrow } from './utils';
+
+function hasSrcAppDir() {
+ const { existsSync } = nodeFsOrThrow();
+ const path = nodePathOrThrow();
+ const cwd = nodeCwdOrThrow();
+
+ const projectWithAppSrc = path.join(cwd(), 'src', 'app');
+
+ return !!existsSync(projectWithAppSrc);
+}
+
+function suggestMiddlewareLocation() {
+ const fileExtensions = ['ts', 'js'] as const;
+ const suggestionMessage = (
+ extension: (typeof fileExtensions)[number],
+ to: 'src/' | '',
+ from: 'src/app/' | 'app/' | '',
+ ) =>
+ `Clerk: clerkMiddleware() was not run, your middleware file might be misplaced. Move your middleware file to ./${to}middleware.${extension}. Currently located at ./${from}middleware.${extension}`;
+
+ const { existsSync } = nodeFsOrThrow();
+ const path = nodePathOrThrow();
+ const cwd = nodeCwdOrThrow();
+
+ const projectWithAppSrcPath = path.join(cwd(), 'src', 'app');
+ const projectWithAppPath = path.join(cwd(), 'app');
+
+ const checkMiddlewareLocation = (
+ basePath: string,
+ to: 'src/' | '',
+ from: 'src/app/' | 'app/' | '',
+ ): string | undefined => {
+ for (const fileExtension of fileExtensions) {
+ if (existsSync(path.join(basePath, `middleware.${fileExtension}`))) {
+ return suggestionMessage(fileExtension, to, from);
+ }
+ }
+ return undefined;
+ };
+
+ if (existsSync(projectWithAppSrcPath)) {
+ return (
+ checkMiddlewareLocation(projectWithAppSrcPath, 'src/', 'src/app/') || checkMiddlewareLocation(cwd(), 'src/', '')
+ );
+ }
+
+ if (existsSync(projectWithAppPath)) {
+ return checkMiddlewareLocation(projectWithAppPath, '', 'app/');
+ }
+
+ return undefined;
+}
+
+export { suggestMiddlewareLocation, hasSrcAppDir };

packages/nextjs/src/server/fs/utils.ts

@@ -0,0 +1,33 @@
+/**
+ * Attention: Only import this module when the node runtime is used.
+ * We are using conditional imports to mitigate bundling issues with Next.js server actions on version prior to 14.1.0.
+ */
+// @ts-ignore
+import nodeRuntime from '#safe-node-apis';
+
+const throwMissingFsModule = (module: string) => {
+ throw new Error(`Clerk: ${module} is missing. This is an internal error. Please contact Clerk's support.`);
+};
+
+const nodeFsOrThrow = () => {
+ if (!nodeRuntime.fs) {
+ throwMissingFsModule('fs');
+ }
+ return nodeRuntime.fs;
+};
+
+const nodePathOrThrow = () => {
+ if (!nodeRuntime.path) {
+ throwMissingFsModule('path');
+ }
+ return nodeRuntime.path;
+};
+
+const nodeCwdOrThrow = () => {
+ if (!nodeRuntime.cwd) {
+ throwMissingFsModule('cwd');
+ }
+ return nodeRuntime.cwd;
+};
+
+export { nodeCwdOrThrow, nodeFsOrThrow, nodePathOrThrow };