Support Async Dynamic APIs

[mobeigi]

Link to reproduction

No response

Environment Info

Binaries:
  Node: 20.16.0
  npm: N/A
  Yarn: N/A
  pnpm: N/A
Relevant Packages:
  payload: 3.0.0-beta.109
  next: 15.0.0-canary.172
  @payloadcms/db-postgres: 3.0.0-beta.109
  @payloadcms/email-nodemailer: 3.0.0-beta.109
  @payloadcms/graphql: 3.0.0-beta.109
  @payloadcms/next/utilities: 3.0.0-beta.109
  @payloadcms/plugin-cloud: 3.0.0-beta.109
  @payloadcms/plugin-nested-docs: 3.0.0-beta.109
  @payloadcms/plugin-redirects: 3.0.0-beta.109
  @payloadcms/plugin-seo: 3.0.0-beta.109
  @payloadcms/richtext-lexical: 3.0.0-beta.109
  @payloadcms/translations: 3.0.0-beta.109
  @payloadcms/ui/shared: 3.0.0-beta.109
  react: 19.0.0-rc-3edc000d-20240926
  react-dom: 19.0.0-rc-3edc000d-20240926
Operating System:
  Platform: win32
  Arch: x64
  Version: Windows 10 Pro
  Available memory (MB): 65459
  Available CPU cores: 24

Done in 3.03s.

Describe the Bug

As of Next.js v15.0.0-canary.171, the following change was introduced:
vercel/next.js#68812

You can read more about the change here:
vercel/next.js#68812

In short, it makes params / headers return promises so you have to await them. Its meant to also allow the previous approach for backwards compatability temporarily. However, it seems like this is not working as intended and it breaking next build (production builds).

The errors stem from the api/payload folder.

Example build error from yarn build:

   Linting and checking validity of types  ...Failed to compile.

.next/types/app/(payload)/admin/[[...segments]]/page.ts:30:29
Type error: Type 'Args' does not satisfy the constraint 'PageProps'.
  Types of property 'params' are incompatible.
    Type '{ segments: string[]; }' is missing the following properties from type 'Promise<SegmentParams>': then, catch, finally, [Symbol.toStringTag]

  28 |
  29 | // Check the prop type of the entry function
> 30 | checkFields<Diff<PageProps, FirstArg<TEntry['default']>, 'default'>>()
     |                             ^
  31 |
  32 | // Check the arguments and return type of the generateMetadata function
  33 | if ('generateMetadata' in entry) {
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

Example console errors during yarn dev:

In route /api/[...slug] a param property was accessed directly with `params.slug`. `params` is now a Promise and should be awaited before accessing properties of 
the underlying params object. In this version of Next.js direct access to param properties is still supported to facilitate migration but in a future version you will be required to await `params`. If this use is inside an async function await it. If this use is inside a synchronous function then convert the function to async or await it from outside this function and pass the result in.

Reproduction Steps

1. Use any Payload project using payload 3.0.0-beta.109 and nextjs 15.0.0-canary.171.
2. yarn dev
3. Load a /api/ route.
4. Observe errors in console.
5. yarn build
6. Observe type errors that fail the build.

Adapters and Plugins

No response

[DanRibbens]

The workaround until we can issue a fix in Payload is to use "next": "v15.0.0-canary.160" while we work on this.

[tomups]

I modified the Args type in src/app/(payload)/admin/[[...segments]]/page.tsx and src/app/(payload)/admin/[[...segments]]/not-found.tsx to

type Args = {
  params: Promise<{
    segments: string[];
  }>;
  searchParams: Promise<{
    [key: string]: string | string[];
  }>;
};

And it works fine now on the latest Next.js canary. But of course this can be overwritten at any point as mentioned in the file's comment, so not a permanent solution.

[todor0v]

@r1tsuu Is it still normal to get a warning after upgrading to Payload 3.0.0-beta.111 and Next.js 15.0.0-canary.173 and react/react-dom 19.0.0-rc-3edc000d-20240926 and applying the necessary changes to the payload files?

When opening the Payload admin, I get:

In route /api/[...slug] a header property was accessed directly with `headers().get('x-forwarded-proto')`. `headers()` now returns a Promise and the return value should be awaited before accessing properties of the underlying headers instance. In this version of Next.js direct access to `headers().get('x-forwarded-proto')` is still supported to facilitate migration but in a future version you will be required to await the result. If this `headers()` use is inside an async function await the return value before accessing attempting iteration. If this use is inside a synchronous function then convert the function to async or await the call from outside this function and pass the result in.

If I upgrade to the latest Next.js canary.179, that message changes to:

In route /api/[...slug] a header property was accessed directly with `headers().get('x-forwarded-proto')`. `headers()` should be awaited before using its value. Learn more: https://nextjs.org/docs/messages/sync-dynamic-apis

[AndKenneth]

I'm getting the same thing as @todor0v , I don't think it's a functional issue because the next team made the API backward compatible, but the console spam is a tad annoying.

[mobeigi]

@r1tsuu I believe this issue is resolved as of 3.0.0-beta.111 release release and can be closed.

@tomups It is a permanent solution, you change it once and if it is rewritten in the future, Payload will rewrite it using the correct newer syntax as long as you use beta version > 3.0.0-beta.111. The comment is there to let you know you shouldn't add extra misc functionality to the file since it will get overwritten.

@todor0v /api/[...slug] doesn't seem to be using headers in any way? What does your /api/[...slug] look like? Did you add a custom api route perhaps that is using headers? Search your repo for usages of next/headers and see if all usages are resolving promises. Also do a proper clean removing node_modules .next and restarting eslint / typescript servers too before checking again.

I am on 3.0.0-beta.111 and Next.js 15.0.0-canary.173 and react/react-dom 19.0.0-rc-3edc000d-20240926 and its working well for me with no errors.

[Because789]

@mobeigi I am on 3.0.0-beta.111, Next.js 15.0.0-canary.173 and react/react-dom 19.0.0-rc-3edc000d-20240926, too (with pnpm) and I'm still experiencing your original issue.

If it's working for you only with @tomups workaround, I don't think this should be closed.