feat(nextjs): Hint correct middleware location when missing clerkMiddleware #4979

panteliselef · 2025-01-23T11:15:34Z

Description

When the middleware.ts file is mislocated, Clerk will throw a related error as clerkMiddeware needs to run for the server-side helpers to work.

This PR aims to improve the error by showing actionable steps, as we identified that 1 out of 3 users will misplace the middleware file when using Next for the first time.

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

…e-when-middlewarets-is-mis

This reverts commit 7c287f9.

This reverts commit af2d82a.

…leware

changeset-bot · 2025-01-23T11:15:39Z

🦋 Changeset detected

Latest commit: 47d3f31

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@clerk/nextjs	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2025-01-23T11:15:39Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

1 Skipped Deployment

Name	Status	Preview	Comments	Updated (UTC)
clerk-js-sandbox	⬜️ Skipped (Inspect)			Jan 27, 2025 1:18pm

panteliselef · 2025-01-23T11:16:38Z

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


    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}`,


Our relatively new clerkClient() also depends on headers()

panteliselef · 2025-01-23T12:15:20Z

packages/nextjs/src/server/createGetAuth.ts

+export const createGetAuthAsync = ({
+  debugLoggerName,
+  noAuthStatusMessage,
+}: {
+  debugLoggerName: string;
+  noAuthStatusMessage: string;
+}) =>
+  createGetAuth({
+    debugLoggerName: debugLoggerName,
+    transformer: async ({ request, options, logger }) => {
+      if (!detectClerkMiddleware(request)) {
+        // Keep the same behaviour for versions that may have issues with bundling `node:fs`
+        if (isNextWithUnstableServerActions) {
+          assertAuthStatus(request, noAuthStatusMessage);
+        }
+
+        const missConfiguredMiddlewareLocation = await import('./keyless-node.js')
+          .then(m => m.suggestMiddlewareLocation())
+          .catch(() => undefined);
+
+        if (missConfiguredMiddlewareLocation) {
+          throw new Error(missConfiguredMiddlewareLocation);


So the refactor was necessary for using await import() without breaking the synchronous getAuth() for pages router.

From my previous experience with keyless using require() would not prevent issues when accessing node:fs

To remind folks we've hit issues with Next 13 and 14 where node:fs would leak to the browser, when code was accessing the module from a server action, causing the app to break.

…rror-message-when-middlewarets-is-mis

…e-when-middlewarets-is-mis

jacekradko · 2025-01-23T14:28:11Z

packages/nextjs/src/server/createGetAuth.ts

  });

-export const getAuth = createGetAuth({
+export const createGetAuthAsync = ({


I don't think it really makes sense to rename methods based on async unless we are going to support both versions sync/async. Do we need both?

getAuth is a publicly consumed api for the pages router. making it async will be a breaking change.

jacekradko

The code looks good. 👍🏼

As a team, I think we should talk about how to go forward with more async things creeping into the SDK and this duality of sync/async will become more and more problematic.

…rror-message-when-middlewarets-is-mis

alexcarpenter

Testing this I am seeing server logs that it can't detect clerkMiddleware(), when I do have it in place.

panteliselef · 2025-01-24T16:43:23Z

@alexcarpenter I cannot reproduce, are you sure the error in your terminal are not from before ?

alexcarpenter · 2025-01-24T16:45:01Z

!snapshot

clerk-cookie · 2025-01-24T16:47:26Z

Hey @alexcarpenter - the snapshot version command generated the following package versions:

Package	Version
@clerk/astro	2.1.16-snapshot.v20250124164546
@clerk/backend	1.23.8-snapshot.v20250124164546
@clerk/chrome-extension	2.2.2-snapshot.v20250124164546
@clerk/clerk-js	5.49.1-snapshot.v20250124164546
@clerk/elements	0.22.16-snapshot.v20250124164546
@clerk/clerk-expo	2.7.0-snapshot.v20250124164546
@clerk/expo-passkeys	0.1.15-snapshot.v20250124164546
@clerk/express	1.3.43-snapshot.v20250124164546
@clerk/fastify	2.1.16-snapshot.v20250124164546
@clerk/localizations	3.10.1-snapshot.v20250124164546
@clerk/nextjs	6.10.3-snapshot.v20250124164546
@clerk/nuxt	1.0.12-snapshot.v20250124164546
@clerk/clerk-react	5.22.7-snapshot.v20250124164546
@clerk/react-router	1.0.2-snapshot.v20250124164546
@clerk/remix	4.4.18-snapshot.v20250124164546
@clerk/shared	2.20.15-snapshot.v20250124164546
@clerk/tanstack-start	0.8.17-snapshot.v20250124164546
@clerk/testing	1.4.16-snapshot.v20250124164546
@clerk/themes	2.2.13-snapshot.v20250124164546
@clerk/types	4.44.1-snapshot.v20250124164546
@clerk/ui	0.3.17-snapshot.v20250124164546
@clerk/vue	1.1.7-snapshot.v20250124164546

Tip: Use the snippet copy button below to quickly install the required packages.
@clerk/astro

npm i @clerk/astro@2.1.16-snapshot.v20250124164546 --save-exact

@clerk/backend

npm i @clerk/backend@1.23.8-snapshot.v20250124164546 --save-exact

@clerk/chrome-extension

npm i @clerk/chrome-extension@2.2.2-snapshot.v20250124164546 --save-exact

@clerk/clerk-js

npm i @clerk/clerk-js@5.49.1-snapshot.v20250124164546 --save-exact

@clerk/elements

npm i @clerk/elements@0.22.16-snapshot.v20250124164546 --save-exact

@clerk/clerk-expo

npm i @clerk/clerk-expo@2.7.0-snapshot.v20250124164546 --save-exact

@clerk/expo-passkeys

npm i @clerk/expo-passkeys@0.1.15-snapshot.v20250124164546 --save-exact

@clerk/express

npm i @clerk/express@1.3.43-snapshot.v20250124164546 --save-exact

@clerk/fastify

npm i @clerk/fastify@2.1.16-snapshot.v20250124164546 --save-exact

@clerk/localizations

npm i @clerk/localizations@3.10.1-snapshot.v20250124164546 --save-exact

@clerk/nextjs

npm i @clerk/nextjs@6.10.3-snapshot.v20250124164546 --save-exact

@clerk/nuxt

npm i @clerk/nuxt@1.0.12-snapshot.v20250124164546 --save-exact

@clerk/clerk-react

npm i @clerk/clerk-react@5.22.7-snapshot.v20250124164546 --save-exact

@clerk/react-router

npm i @clerk/react-router@1.0.2-snapshot.v20250124164546 --save-exact

@clerk/remix

npm i @clerk/remix@4.4.18-snapshot.v20250124164546 --save-exact

@clerk/shared

npm i @clerk/shared@2.20.15-snapshot.v20250124164546 --save-exact

@clerk/tanstack-start

npm i @clerk/tanstack-start@0.8.17-snapshot.v20250124164546 --save-exact

@clerk/testing

npm i @clerk/testing@1.4.16-snapshot.v20250124164546 --save-exact

@clerk/themes

npm i @clerk/themes@2.2.13-snapshot.v20250124164546 --save-exact

@clerk/types

npm i @clerk/types@4.44.1-snapshot.v20250124164546 --save-exact

@clerk/ui

npm i @clerk/ui@0.3.17-snapshot.v20250124164546 --save-exact

@clerk/vue

npm i @clerk/vue@1.1.7-snapshot.v20250124164546 --save-exact

nikosdouvlis

@panteliselef good job identifying that so many people hit this (~33% of new installs!!!). This is an easy fix but the impact is huge in this case 👏🏻

nikosdouvlis · 2025-01-27T09:36:41Z

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


    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/server/keyless-node.ts

nikosdouvlis · 2025-01-27T09:48:48Z

packages/nextjs/src/server/keyless-node.ts

+  const { existsSync } = safeNodeRuntimeFs();
+  const path = safeNodeRuntimePath();
+
+  const projectWithAppSrc = path.join(process.cwd(), 'src', 'app');


Minor, but I would probably write this one like:

Suggested change

const projectWithAppSrc = path.join(process.cwd(), 'src', 'app');

const projectWithAppSrc = existsSync(path.join(process.cwd(), 'src', 'app'));

simply because projectWithAppSrc sounds like a boolean. Feel free to ignore of course

nikosdouvlis · 2025-01-27T10:00:29Z

packages/nextjs/src/server/createGetAuth.ts

+// Utility type to determine if a type is a Promise
+type IsPromise<T> = T extends Promise<any> ? true : false;
+
+const createGetAuth = <


Good job building the conditional types used here.
It looks like the majority of the logic is with each transformer function. Would it be simpler to drop the transformer abstraction altogether, drop createGetAuth and end up with 2 methods:

createSyncGetAuth

createAsyncGetAuth
(notice I moved the 'sync'/'async' adjective before the 'getAuth' part, which is a minor detail as the adjective describes the returned function and not the builder.

Duplicating a few lines would probably be worth it if we could remove an abstraction layer. What do you think?

.changeset/fuzzy-rockets-smash.md

anagstef

Great improvement! 🚀

Co-authored-by: Stefanos Anagnostou <anagstef@users.noreply.github.com> Co-authored-by: Nikos Douvlis <nikosdouvlis@gmail.com>

…e-when-middlewarets-is-mis

…lerkMiddleware (#4979)" This reverts commit 3e932b4.

…lerkMiddleware (#4979) (#5026)

…issing clerkMiddleware (#4979) (#5026)" This reverts commit 932c8c4.

…leware (#4979)

…lerkMiddleware (#4979) (#5026)

panteliselef added 5 commits January 23, 2025 11:50

wip

7c287f9

Merge branch 'main' into elef/actls-63-look-at-improving-error-messag…

1363cb5

…e-when-middlewarets-is-mis

Revert "wip"

af2d82a

This reverts commit 7c287f9.

Revert "Revert "wip""

8075667

This reverts commit af2d82a.

feat(nextjs): Hint correct middleware location when missing clerkMidd…

040628c

…leware

clerk-cookie added the nextjs label Jan 23, 2025

vercel bot deployed to Preview January 23, 2025 11:16 View deployment

panteliselef added 2 commits January 23, 2025 13:27

missed file

4da1637

prevent breaking sync getAuth()

d1d82f8

vercel bot temporarily deployed to Preview January 23, 2025 12:10 Inactive

panteliselef commented Jan 23, 2025

View reviewed changes

Merge branch 'refs/heads/main' into elef/actls-63-look-at-improving-e…

b7e2cfb

…rror-message-when-middlewarets-is-mis

vercel bot deployed to Preview January 23, 2025 12:17 View deployment

panteliselef self-assigned this Jan 23, 2025

Merge branch 'main' into elef/actls-63-look-at-improving-error-messag…

2eb1023

…e-when-middlewarets-is-mis

vercel bot deployed to Preview January 23, 2025 12:25 View deployment

panteliselef requested a review from a team January 23, 2025 12:33

jacekradko reviewed Jan 23, 2025

View reviewed changes

panteliselef added 2 commits January 24, 2025 17:54

replace root with ./

fd8bc74

Merge branch 'refs/heads/main' into elef/actls-63-look-at-improving-e…

551b528

…rror-message-when-middlewarets-is-mis

vercel bot deployed to Preview January 24, 2025 16:00 View deployment

alexcarpenter reviewed Jan 24, 2025

View reviewed changes

fix lint errors

4dad459

vercel bot temporarily deployed to Preview January 24, 2025 17:06 Inactive

alexcarpenter approved these changes Jan 24, 2025

View reviewed changes

nikosdouvlis approved these changes Jan 27, 2025

View reviewed changes

anagstef reviewed Jan 27, 2025

View reviewed changes

.changeset/fuzzy-rockets-smash.md Outdated Show resolved Hide resolved

anagstef approved these changes Jan 27, 2025

View reviewed changes

Apply suggestions from code review

85a7694

Co-authored-by: Stefanos Anagnostou <anagstef@users.noreply.github.com> Co-authored-by: Nikos Douvlis <nikosdouvlis@gmail.com>

vercel bot deployed to Preview January 27, 2025 12:29 View deployment

panteliselef added 2 commits January 27, 2025 15:05

address review comments

88768ab

Merge branch 'main' into elef/actls-63-look-at-improving-error-messag…

300d426

…e-when-middlewarets-is-mis

vercel bot deployed to Preview January 27, 2025 13:10 View deployment

fix tests

09795c3

vercel bot temporarily deployed to Preview January 27, 2025 13:10 Inactive

remove eslint rules

47d3f31

vercel bot temporarily deployed to Preview January 27, 2025 13:18 Inactive

panteliselef merged commit 3e932b4 into main Jan 27, 2025
29 checks passed

panteliselef deleted the elef/actls-63-look-at-improving-error-message-when-middlewarets-is-mis branch January 27, 2025 13:29

clerk-cookie mentioned this pull request Jan 27, 2025

ci(repo): Version packages #4992

Merged

panteliselef added a commit that referenced this pull request Jan 28, 2025

Revert "feat(nextjs): Hint correct middleware location when missing c…

4de08d3

…lerkMiddleware (#4979)" This reverts commit 3e932b4.

panteliselef added a commit that referenced this pull request Jan 28, 2025

Revert "feat(nextjs): Hint correct middleware location when missing c…

932c8c4

…lerkMiddleware (#4979) (#5026)

clerk-cookie mentioned this pull request Jan 28, 2025

ci(repo): Version packages #5021

Merged

panteliselef added a commit that referenced this pull request Jan 28, 2025

Revert "Revert "feat(nextjs): Hint correct middleware location when m…

19d7256

…issing clerkMiddleware (#4979) (#5026)" This reverts commit 932c8c4.

panteliselef mentioned this pull request Jan 28, 2025

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

Merged

9 tasks

wobsoriano pushed a commit that referenced this pull request Feb 8, 2025

feat(nextjs): Hint correct middleware location when missing clerkMidd…

d0be419

…leware (#4979)

wobsoriano pushed a commit that referenced this pull request Feb 8, 2025

Revert "feat(nextjs): Hint correct middleware location when missing c…

3342ef8

…lerkMiddleware (#4979) (#5026)

	const projectWithAppSrc = path.join(process.cwd(), 'src', 'app');
	const projectWithAppSrc = existsSync(path.join(process.cwd(), 'src', 'app'));

Uh oh!

feat(nextjs): Hint correct middleware location when missing clerkMiddleware #4979

feat(nextjs): Hint correct middleware location when missing clerkMiddleware #4979

Uh oh!

Conversation

panteliselef commented Jan 23, 2025 • edited by nikosdouvlis Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Type of change

Uh oh!

changeset-bot bot commented Jan 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Jan 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

panteliselef Jan 23, 2025

Choose a reason for hiding this comment

Uh oh!

nikosdouvlis Jan 27, 2025

Choose a reason for hiding this comment

Uh oh!

panteliselef Jan 23, 2025

Choose a reason for hiding this comment

Uh oh!

jacekradko Jan 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

panteliselef Jan 23, 2025

Choose a reason for hiding this comment

Uh oh!

jacekradko left a comment

Choose a reason for hiding this comment

Uh oh!

alexcarpenter left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

panteliselef commented Jan 24, 2025

Uh oh!

alexcarpenter commented Jan 24, 2025

Uh oh!

clerk-cookie commented Jan 24, 2025

Uh oh!

nikosdouvlis left a comment

Choose a reason for hiding this comment

Uh oh!

nikosdouvlis Jan 27, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

nikosdouvlis Jan 27, 2025

Choose a reason for hiding this comment

Uh oh!

nikosdouvlis Jan 27, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

anagstef left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

panteliselef commented Jan 23, 2025 •

edited by nikosdouvlis

Loading

changeset-bot bot commented Jan 23, 2025 •

edited

Loading

vercel bot commented Jan 23, 2025 •

edited

Loading

jacekradko Jan 23, 2025 •

edited

Loading

alexcarpenter left a comment •

edited

Loading