feat(nextjs): Introduce clerkMiddleware by nikosdouvlis · Pull Request #2404 · clerk/javascript

nikosdouvlis · 2023-12-19T14:01:32Z

Description

`clerkMiddleware` API:

export default clerkMiddleware(auth => {
  auth().protect();
  auth().protect({ permission: 'org:domains:delete' });
  auth().protect({ permission: 'org:domains:delete' }, { redirectUrl: 'https://clerk.com' });

  auth().redirectToSignIn();
  auth().redirectToSignIn({ returnBackUrl: 'https://clerk.com' });

  const { userId, redirectToSignIn } = auth();
  if (!userId) {
    return redirectToSignIn();
  }

  return NextResponse.next();
});

`protect` API:

The protect API can be used to protect pages, route handlers, server actions and any other request that can be intercepted using the middleware. It can be used to handle both unauthenticated and unauthorized requests.

Calling protect without arguments will catch all unauthenticated requests, and depending on the context it's used in, it will either redirect to the sign-in URL (for page requests) or throw a notFound error (for route handlers and server actions). If a redirectUrl is provided, protect will always respect it and redirect to it.

Calling protect with the same arguments the has API accepts, will catch all unauthorized requests, and throw a notFound error (for route handlers and server actions). If a redirectUrl is provided, protect will always respect it and redirect to it.

SDK-647

Checklist

npm test runs as expected.
npm run 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

Packages affected

changeset-bot · 2023-12-19T14:01:36Z

🦋 Changeset detected

Latest commit: 832ca35

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

This PR includes changesets to release 2 packages

Name	Type
@clerk/nextjs	Patch
@clerk/elements	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

dimkl · 2023-12-19T14:43:29Z

+      const res = new Response(null, { status: 307, headers: requestState.headers });
+      return decorateResponseWithObservabilityHeaders(res, requestState);
+    } else if (requestState.status === AuthStatus.Handshake) {
+      throw new Error('Clerk: handshake status without redirect');


🙃 let's use the errorThrower instead of Error.

@nikosdouvlis Reminder ☝️

brkalow · 2023-12-19T15:14:45Z

+      switch (e.message) {
+        case PROTECT_REWRITE:
+          // Rewrite to bonus URL to force not found error
+          return NextResponse.rewrite(`${clerkRequest.clerkUrl.origin}/clerk_${Date.now()}`);


🤔 this might pollute a consumer's logs, it's probably fine but we should call this out in the docs.

nikosdouvlis · 2023-12-22T16:45:39Z

+const isServerActionRequest = (req: Request) => {
+  return (
+    !!req.headers.get(nextConstants.Headers.NextUrl) &&
+    (req.headers.get(constants.Headers.Accept)?.includes('text/x-component') ||
+      req.headers.get(constants.Headers.ContentType)?.includes('multipart/form-data') ||
+      !!req.headers.get(nextConstants.Headers.NextAction))
+  );
+};
+
+const isPageRequest = (req: Request): boolean => {
+  return (
+    req.headers.get(constants.Headers.SecFetchDest) === 'document' ||
+    req.headers.get(constants.Headers.Accept)?.includes('text/html') ||
+    (!!req.headers.get(nextConstants.Headers.NextUrl) && !isServerActionRequest(req))
+  );
+};
+
+// In case we want to handle router handlers and server actions differently in the future
+// const isRouteHandler = (req: Request) => {
+//   return !isPageRequest(req) && !isServerAction(req);
+// };


Many thanks to @panteliselef for taking the time to investigate, test, and help me simplify these checks 🥇

Should we remove the commented out code?

We're leveraging the isPageRequest and isServerActionRequest checks to detect whether the current request is a page request. For page requests, instead of throwing a 404 or 401, we're redirecting to SIGN_IN_URL automatically. In order to achieve that, we're using native headers but also the `next-urk` and `next-action` headers of NextJS

…ithAuth

nikosdouvlis requested review from dimkl and panteliselef December 19, 2023 14:01

nikosdouvlis requested a review from SokratisVidros December 19, 2023 14:01

nikosdouvlis self-assigned this Dec 19, 2023

clerk-cookie added types nextjs remix backend labels Dec 19, 2023

nikosdouvlis mentioned this pull request Dec 19, 2023

WIP - feat(nextjs): Introduce clerkMiddleware #2371

Closed

24 tasks

dimkl approved these changes Dec 19, 2023

View reviewed changes

brkalow reviewed Dec 19, 2023

View reviewed changes

panteliselef reviewed Dec 20, 2023

View reviewed changes

Comment thread packages/types/src/multiDomain.ts Outdated

panteliselef reviewed Dec 20, 2023

View reviewed changes

Comment thread packages/nextjs/src/server/protect.ts Outdated

nikosdouvlis force-pushed the nikos/introduce-clerkmiddleware branch from bb318b2 to 0939fda Compare December 22, 2023 16:44

nikosdouvlis commented Dec 22, 2023

View reviewed changes

nikosdouvlis force-pushed the nikos/introduce-clerkmiddleware branch from 0939fda to 2ba6cc6 Compare December 22, 2023 16:51

clerk-cookie added the clerk-js label Dec 22, 2023

nikosdouvlis force-pushed the nikos/introduce-clerkmiddleware branch from 2ba6cc6 to 00c6a30 Compare January 3, 2024 01:12

clerk-cookie added react fastify and removed clerk-js labels Jan 3, 2024

nikosdouvlis force-pushed the nikos/introduce-clerkmiddleware branch from 00c6a30 to 8b7c324 Compare January 3, 2024 16:26

nikosdouvlis added 7 commits January 3, 2024 19:12

feat(nextjs): Introduce clerkMiddleware

d44453b

feat(*): Remove unnecessary RemixClerkProviderProps type

2caffea

feat(nextjs): Introduce clerkMiddleware.test.ts

3056a89

feat(nextjs): Rename appendDevBrowserOnCrossOrigin to serverRedirectW…

10d5c49

…ithAuth

feat(nextjs): Add changeset and inline docs

a5ca282

feat(nextjs): Update integration tests

832ca35

nikosdouvlis force-pushed the nikos/introduce-clerkmiddleware branch from 8b7c324 to 832ca35 Compare January 3, 2024 17:12

clerk-cookie added the integration label Jan 3, 2024

nikosdouvlis merged commit 9a87ece into main Jan 3, 2024

nikosdouvlis deleted the nikos/introduce-clerkmiddleware branch January 3, 2024 17:20

clerk-cookie mentioned this pull request Jan 3, 2024

Version Packages (alpha-v5) #2449

Merged

coderabbitai Bot mentioned this pull request Mar 28, 2026

Feat/nextjs 16 migration myoshi2891/Multi-Vendor-E-Commerce#102

Merged

coderabbitai Bot mentioned this pull request Apr 13, 2026

New update saeedsaiyed01/contractly#2

Merged

coderabbitai Bot mentioned this pull request May 12, 2026

implement auth danielUgochukwu/ghost-ai#2

Merged

This was referenced Jun 21, 2026

02: authentication amande53/Lavender-Muse-Code-Studio#1

Merged

implement auth taniya7/arc-ai#2

Merged

This was referenced Jul 8, 2026

Implemented auth with clerk nerdy1001/blueprint#2

Merged

implement auth akhmetovb/taugrid-ai#2

Merged

coderabbitai Bot mentioned this pull request Jul 24, 2026

Phase 3: Clerk認証(ログイン・保護・Convex連携・振り分け) yamk12nfu/warikapp#7

Merged

6 tasks

coderabbitai Bot mentioned this pull request Aug 5, 2026

feat: add protected application shell DoMinhHHung/BridgeWorksApps#2

Merged

This was referenced Aug 24, 2026

Add MCP context fetching and search functionality with OpenAI integra… Airshock72/vertex#7

Merged

Add Clerk authentication simiel/vertex#2

Merged

Navigation Menu

Uh oh!

feat(nextjs): Introduce clerkMiddleware - #2404

feat(nextjs): Introduce clerkMiddleware#2404
nikosdouvlis merged 7 commits into
mainfrom
nikos/introduce-clerkmiddleware

nikosdouvlis commented Dec 19, 2023 •

edited

Loading

Uh oh!

changeset-bot Bot commented Dec 19, 2023 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dimkl Dec 19, 2023

Uh oh!

SokratisVidros Jan 2, 2024

Uh oh!

Uh oh!

Uh oh!

Uh oh!

brkalow Dec 19, 2023

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nikosdouvlis Dec 22, 2023

Uh oh!

SokratisVidros Jan 2, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Uh oh!

Conversation

nikosdouvlis commented Dec 19, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

clerkMiddleware API:

protect API:

Checklist

Type of change

Packages affected

Uh oh!

changeset-bot Bot commented Dec 19, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dimkl Dec 19, 2023

Choose a reason for hiding this comment

Uh oh!

SokratisVidros Jan 2, 2024

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

brkalow Dec 19, 2023

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nikosdouvlis Dec 22, 2023

Choose a reason for hiding this comment

Uh oh!

SokratisVidros Jan 2, 2024

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

nikosdouvlis commented Dec 19, 2023 •

edited

Loading

`clerkMiddleware` API:

`protect` API:

changeset-bot Bot commented Dec 19, 2023 •

edited

Loading