v3 / Beta docs don't indicate that next.js 15 is a requirement

[mbifulco]

Documentation Issue

tl;dr: It seems that Next.js 15 is a prereq for Payload beta, and that isn't mentioned in the docs for existing projects. If it's not a requirement, installation seems to be broken for projects still on next.js 14

Additional Details

I've been working on adding Payload to an existing Next.js app that is still on "next": "~14.2.15",. I lost about a day of dev work to a set of warnings and errors that were very difficult to trace. I was seeing the following output when running my app:

⚠ Invalid next.config.mjs options detected: 
⚠     Unrecognized key(s) in object: 'outputFileTracingExcludes', 'outputFileTracingIncludes', 'serverExternalPackages'
⚠ See more info here: https://nextjs.org/docs/messages/invalid-next-config

The app still compiles with these warnings, but when I try to access payload at localhost:3000/admin, I see the following errors:

Module not found: Package path ./compiler-runtime is not exported from package /Users/mike/src/my-project/node_modules/react (see exports field in /Users/mike/src/my-project/node_modules/react/package.json)
> 1 | 'use client'
    | ^
  2 | import type { SanitizedConfig } from 'payload'
  3 |
  4 | import { useSearchParams } from '@payloadcms/ui'

Note that the above code is not mine, and seems to be upstream, in payload's source somewhere.

I eventually came across https://github.com/payloadcms/payload/issues/7501 and https://github.com/payloadcms/payload/pull/7541 which updates Payload to next.js 15.x.

As a result, the only fix I've found for this so far was to upgrade my project to next.js 15 using their guides. Once this is done, everything seems to work as expected -- but I'm not entirely sure I want to update my project to next 15, since that requires an update to react@19.0.0-rc-*... and shipping react RCs to production isn't something I'm super keen to do.

In addition to updating the docs found here I'd love some guidance here - is there a functional way to ship Payload without updating to Next@15, and React@RC?

[jmikrut]

Hey @mbifulco - yes, Next 15 is a requirement for Payload 3.0. We test and ensure that all of our functionality works with the React RCs but I do understand your feelings here.

If you have a big frontend that you're not ready to bring the React 19 RCs into, you could always run Payload separately as would have been done prior to 3.0. Running the CMS separate from your frontend is how any other headless CMS functions so it would really not be that big of a tradeoff.

You basically have to pick between:

1. Combine your frontend and backend, and have both run Next.js 15
2. Run Payload separately in a Next.js 15 app, and then continue to run your separate frontend on earlier versions of Next.js

In any case, we'll get the docs updated to note that Next.js 15 is a requirement of Payload in a very clear fashion. Good call. I'll keep this issue open until we do that.

[mbifulco]

Thanks! Appreciate the speedy response. I realize we're probably going to be in the minority here (eventually), but we actually still use the pages router. 👀

Adopting Payload would be our first use of the app router. We looked at it in early 2023, but decided that it was a bit early to jump in it at the time. I'm not opposed to using the app router by any stretch of the imagination, but it also feels like a potential hole in the docs for Payload - they assume we're using the app router as well.

I'll take a look at setting up payload in its own repo, that's a solid idea.