fix(nextjs): Handle dynamicIO errors when request apis are accessed on prerender

[panteliselef]

Description

This PR resolves the issue seen below when a next.js application is using dynamicIO: true.

 ⨯ unhandledRejection: Error: Clerk: auth() and currentUser() are only supported in App Router (/app directory).
If you're using /pages, try getAuth() instead.
Original error: Error: During prerendering, `headers()` rejects when the prerender is complete. Typically these errors are handled by React but if you move `headers()` to a different context by using `setTimeout`, `unstable_after`, or similar functions you may observe this error and you should handle it in that context.
    at buildRequestLike (turbopack://[project]/node_modules/@clerk/nextjs/src/app-router/server/utils.ts:35:10)
    at async getDynamicClerkState2 (turbopack://[project]/node_modules/@clerk/nextjs/src/app-router/server/ClerkProvider.tsx:17:18)
  33 |     }
  34 |
> 35 |     throw new Error(
     |          ^
  36 |       `Clerk: auth() and currentUser() are only supported in App Router (/app directory).\nIf you're using /pages, try getAuth() instead.\nOriginal error: ${e}`,
  37 |     );
  38 |   }

What is happening

There seems to be an issue when awaiting header() inside another scope. When we do that we need to always await that function.

Example with minimal reproduction

✅ Works

export async function ClerkProvider() {
 await (async () => {
    await headers();
  })()

  return <>{props.children}</>;
}

❌ Throws

export async function ClerkProvider() {
  (async () => {
    await headers();
  })()

  return <>{props.children}</>;
}

Example with our structure
✅ This code works properly and will not throw unhandledRejection

const getDynamicState = React.cache(async () => {
  await headers();
  return {};
});

const getNonce = React.cache(async () => {
  await headers();
  return "nonce";
});

export async function ClerkProvider(
  props: PropsWithChildren<{ dynamic: boolean }>
) {
  await getNonce();
  await getDynamicState();

  return <>{props.children}</>;
}

❌ This code works throws unhandledRejection

const getDynamicState = React.cache(async () => {
  // await buildRequest();
  await headers();
  return {};
});

const getNonce = React.cache(async () => {
  await headers();
  return "nonce";
});

export async function ClerkProvider(
  props: PropsWithChildren<{ dynamic: boolean }>
) {
  let statePromise: Promise<unknown> = Promise.resolve(null);
  let noncePromise = Promise.resolve("");

  if (props.dynamic) {
    noncePromise = getNonce();
    statePromise = getDynamicState();
  }

  await noncePromise;
  await statePromise;

  return <>{props.children}</>;
}

Fixes #4445

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

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

[changeset-bot]

🦋 Changeset detected

Latest commit: dd47dae

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]

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

Name	Status	Preview	Comments	Updated (UTC)
clerk-js-sandbox	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 13, 2025 6:42pm

[panteliselef]

!snapshot

[clerk-cookie]

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

Package	Version
@clerk/nextjs	6.9.7-snapshot.v20250101161910

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

npm i @clerk/[email protected] --save-exact

[jacekradko]

👍🏼