Move Payload to Next.js

[zubricks]

If we moved Payload from vanilla Express / React to Next.js, we could offload a significant amount of the work we're responsible for and promote a massive degree of simplification.

Everything could be in one repo. Payload endpoints would be opened up directly inside of your Next app folder, right alongside your frontend.

Payload would still be headless, you will still be able to leverage it completely headless just as you do now with Sveltekit, etc. The config would barely change, all of our API endpoints would remain exactly as they are.and the Payload Local API would remain the same.

We would also be able to more easily maintain first-party boilerplates for other frontend frameworks because we won't have to keep up with so many different Next approaches.

*If you still wanted to deploy Payload as a traditional Express server, you could, thanks to Next.js custom server capabilities.

That said, we’ve already started the work to move Payload to Next.js.

Goals

• Modularize the local API to be a standalone package
• Modularize Admin UI to be a separate component library
• Remove webpack aliases entirely
• Be able to deploy to serverless out of the box
• Remove requirement of maintaining webpack and vite bundlers - just differ to nextjs compiler
• Optimize serverless cold starts

[seripap]

Would this mean next-payload is obsolete and integrating with a Next app would be seamless, or rather, built in?

[klauss194]

@seripap Don't worry. When vercel decides that you can't host your app easily out of their platform or just decide to update Nextjs - we will have no idea how payload & upstream dependencies will behave.

[seripap]

I don't think I've had a problem hosting NextJS outside of Vercel. I agree their updates are a bit wonky, ergo sometimes they remove important APIs without any explanation, but that's only happened from 12-->13 so far.

[david-mcbacon]

it would be great if "build in" payload into Next.js will work properly with SST open-next deployment. Currently next-payload is not working with SST - not able to login into Payload. Here is the issue #74 and also a discussion on discord

Anyway, I love the idea of moving Payload to Next.js, keep rocking ✌️

[jacobsfletch]

@seripap Don't worry. When vercel decides that you can't host your app easily out of their platform or just decide to update Nextjs - we will have no idea how payload & upstream dependencies will behave.

I agree with @seripap on this one. We've been hosting Next.js apps outside of Vercel for quite some time, including on Payload Cloud. This is how our templates currently work. Sure, there are extra benefits to hosting Next.js on Vercel (because they built it), but self-hosting was never an issue and will always continue to be an option. This will just make it easier to host on Vercel without any additional legwork (plus they have a generous free tier).

[K-Mistele]

Self-hosting Next.js is easier now than ever with things like SST, OpenNext, or just building & deploying a Docker container which is what we currently do with AWS Fargate. Vercel now has updated docs on how to self-host Next.js as well.

[sannajammeh]

Modularize the local API to be a standalone package.
Modularize Admin UI to be a separate component library

These two I am incredibly excited for! Will there be additional decoupling for the server side endpoints? Would it be possible to run Payload's REST and GraphQL endpoints through another http framework via adapters? Like Nitro, Fastify and UWS?

[jmikrut]

Yes, this will be possible in the longer term. Payload itself will just be a local API, and the code to open endpoints above the local API itself is very minimal. So we could open up endpoints for server-side stuff easily.

But, the admin UI itself would need to be built / served as well, and right now, being that our plan is Next.js for the admin UI, you'd need to still serve that from a Next server.

That said, I believe you should be able to deploy Next.js on a Fastify server, etc, pretty easy:

https://stackblitz.com/edit/github-trgadj

[klauss194]

What about the admin panel. Will we be able to Run it as an SPA / Generate an Admin panel build ?

[MoSattler]

If you still wanted to deploy Payload as a traditional Express server, you could, thanks to Next.js custom server capabilities.

So I could still drop payload into any already existing express server, or will it only work with nextJS apps?

[carlokok]

Can you still use payload admin as an spa in this case? Or is a next server process for the admin ui required after this?

[jmikrut]

No, you would not be able to use the Payload admin UI as a SPA with this move. But that is intentional and actually one of the larger reasons for making this move. We need React Server Components to "split out" the code that's safe to run in a browser vs. the code that is meant to be executed server-side only.

Are you currently using the Payload admin UI as a SPA? Served elsewhere from your Express backend?

[carlokok]

I'm currently using the Payload Admin UI as an SPA served from a .NET Core application (Which implements the Payload REST apis). I have no issue with the admin UI being a non SPA application and requiring a NextJS server to run though, what I'm curious of is if I'll still be able to provide my own REST apis to feed the admin api. (Ie my current payload.config.ts looks like:

export default (typeof window === 'object' ?  fetch('/api/config.json').then(b => b.text().then(q => {
  let response = JSON.parse(q);
  response.admin.components.beforeLogin = [BeforeLogin];
  response.admin.components.beforeNavLinks = [NavLinks];
  response.editor = slateEditor({});
  (response.collections)?.forEach(b => (b as any).fields?.forEach(b => {
    if (b.type == 'richText') {
      delete b.editor;
      let rt = richText(b);
      for(let i in rt) {
        b[i] = rt[i];
      }
    }
  }))
  
  return response;
})) : data.then(b => {
  console.log(JSON.stringify(b))
  return b
}))

Which mostly works.

I'm well aware that this isn't/shouldn't be a supported thing, but it would be cool if it would still be possible.

[jmikrut]

Woah, mad scientist!

Yes, this would still function the same exact way @carlokok

[klauss194]

How can we run the Payload Admin as a separate SPA @carlokok , can you detail a bit how you managed that ?

[ForrestDevs]

Integrating payload into Next.js would be amazing. Smaller developers can take advantage of hosting both payload and the website on a serverless platform like vercel. This means less expenses as hosting an always running express server costs.

[klauss194]

Wait until you try to host out of vercel..

[jmikrut]

I've been hosting outside of Vercel for 6 years without any problems. Have you ever struggled with that? I would love to know real-world experience vs. tech twitter drama. Honestly, I want to learn from you if you have had issues before - no sarcasm. We want to make sure that hosting a regular Express server will still work 100% so this is important to us.

[chiragdp]

I kinda agree with @jmikrut, I am also running a similar kind of server for nextjs outside vercel/netlify platform, but still no issue faced till now. only one issue is build time which is i guess not primary problem.

[rasmushjulskov]

Have been deploying with Vercel, Amplify, & SST so far for the last 6 years. Pure SSG or SSR always works but ISR is always what I break my neck on when moving outside of Vercel

[thefrana]

To be honest, I am a bit sceptical about this rewrite. It is known that the NextJS apps are not easy to self host if you are not on Vercel platform. I know there are many NextJS developers which would greatly benefit from this seamless integration. However, it would be much harder for everyone else.

My problem is that if you would want to run Payload in a serverless environment you would end up with just one viable option: NextJS. Or deploy it as an Express app and skip serverless.

Maybe the best option is to release Payload as a set of functions that together with some integration create a proper CMS. I thought something similar happened with current payload-next package. You end up with just some routes that handles Payload's stuff and rest is typical NextJS application.

Why not keep this approach and just create the same "almost native" integration for other frameworks? You can maybe keep current NextJS integration and create another (similar) one as an Vite plugin. That way you would support most frameworks out there. Or create support for each one them individually, if the Vite plugin would not be suitable.

I see similar approach taken in the databases. You had only MongoDB support, but then you created abstraction that allows you to use any database with proper adapter.

What do you think about that?

[itzaks]

I'm also a little bit put off by the general direction of this decision. I really love payload, but I'm a strong believer in public projects adapting more open standards to provide a more agnostic framework. Also all ships steering into the abyss of the big react-monopoly-ocean is not my cup of tea.

However, reading through this thread I feel that the lock-in is not thaaaat big, but it's more the direction that I'm concerned with. But for now it doesn't seem to be an issue to happily keep on using payload in a nuxt stack.

[binajmen]

I intended to express my viewpoint, but I found it challenging to do so without coming across as someone who dislikes NextJS. To clarify, I'm not against it; my perspectives just don't align with Vercel's values. Rather than elaborating myself, I suggest you watch a presentation by Ryan Carniato, which delves shortly into why Vercel may not be the best option for sustained use: https://www.youtube.com/live/RzL4N3ZavxU?si=AHVSjttatB-o2Pze&t=12517

[jmikrut]

Catching up here and there are a lot of interesting discussions and viewpoints happening. Thanks to everyone for chiming in.

I especially find the aspects of @manspaniel's notes interesting.

I reckon we'd all love to see a set of standard adapters for the top frameworks and for them to be seen as equals — embracing the diverse web, and leaving the strong opinions to your end users. Yep, it sounds like a hard place to get to from where you are now. Is it going to be easier or harder after this transition?

This is a VERY good question. Through this move, Payload itself will become reliant on the Web standard Request instead of the Express-style req. It'll be a local-only API that functions just like an ORM, and can be fully portable to any HTTP system.

From Next.js specifically, Payload itself will leverage very little. Mainly the next/link component and exposing all endpoints into the /app folder. But you could expose Payload's REST / GraphQL endpoints from any HTTP layer you want. And you could use the Payload Local API separately, without any Next.js at all. Payload itself will actually not have Next.js as a dependency.

Let me make that clear - I think many of you are anticipating that this is going to lock Payload into Next.js for eternity. It's actually the opposite. Yes, Payload's going to use Next.js out of the box for our HTTP layer and admin UI, but we -need- to use a framework that supports RSCs for that stuff. After this move, you will be able to use the Payload Local API anywhere without even having Next.js or React as a dependency. The NPM package payload itself will be Local API only, fully portable. We'll also have @payloadcms/next which opens up HTTP routes / admin UI in Next.js. We'll then also have @payloadcms/ui which is our React library, that will ship some server components and some client components.

Maybe I'm oversimplifying... but seems to me the ideal minimal requirements for integration with Payload should be any framework/codebase which:

Accepts API requests using native Request/Response on a base route, and supports dynamic imports for code-splitting serverless libs (Works well enough for tRPC and their adapter system), Can render a React component at a particular endpoint as an SPA (Sanity does the SPA admin panel thing well, and I think that's why they're so successful — you can use it with literally everything)

Frankly, what we've done up to this point is basically exactly what you describe. But we've hit the limit with what we've been able to achieve with a SPA admin panel, and that's the big driver for this move. We need React Server Components. And that means we need more than a backend that can render a React component - we need SSR that supports server components.

Take it from me - building a React SSR framework is NOT fun. I've done it and can't imagine how much more complexity is added when thinking about RSCs or server actions.

RE: Sanity's embedded admin UI - Payload gives a LOT more flexibility than Sanity. You have complete control over the backend as well as the admin UI, and it's all done from a central config. Just a different beast in general. Anyone could write up a simple SPA React component and plop it into anywhere that can render HTML - but that's not what we're trying to solve. We need the dynamic aspects of a server.

This is all why Next.js is currently really the only option, at least now, to solve what we're looking to solve. It would be great to build our requirements on a flexible stack, but at the end of the day, we're still React, and that means we're not truly framework-independent anyway. And I don't wanna roll my own SSR framework again.

To cap this note off, my own $0.02 is that this is not a re-architecture for the sake of re-architecture. It is a deliberate move to take advantage of RSCs and promote a great DX. Things are going to get MORE modular and portable as a result. But yes, we're going to use Next.js as our admin / HTTP layer, and I don't think there is any cause for alarm whatsoever there.

[berndb]

I am already looking forward to the separation of payload into different layers and see this as an important step.

Question about the payload ORM package:
Currently the payload field types are a mixture of data types and UI specific types ("Collapsible", "Tabs", etc). Also the field type "Checkbox" would probably be more of a "boolean" field type from an ORM layer's point of view.

Can it be assumed that there is an own payload ORM config that is exclusively data type-oriented?
Are there already thoughts on this?

[K-Mistele]

Self-hosting Next.js is easier now than ever with things like SST, OpenNext, or just building & deploying a Docker container which is what we currently do with AWS Fargate. Vercel now has updated docs on how to self-host Next.js as well. imho most of the people who complain about hard it is to self-host Next.js are parroting tech twitter discourse and haven't actually tried, or don't like Docker, or haven't actually read Vercel's docs on how to self-host next.

[tilman]

Will it be possible to deploy it in vercel using vercel postgres?
https://vercel.com/storage/postgres

Not having to deal with databases for a cms would be a gamechanger

[valerioleo]

Yes, I have done it on a project of mine. Vercel Postgres is just like any other Postgres instance 👍🏻

[jacobsfletch]

^ Yup and it will be possible to deploy Payload on a full Vercel stack.

[mnismi]

Can't wait for this combination
Love it ❤️

[yersultanur]

Hi, when approximately it will be done?

[jacobsfletch]

@yersultanur we're hoping to have a beta package available in Q1 2024 (within a month or so).

[maxsynnott]

Hey @jacobsfletch,

Any more recent update on this?

Thanks

[jacobsfletch]

@maxsynnott we've been actively developing on the feat/next-poc branch if you'd like to follow along. We're optimistic about delivering some beta packages end of month / early next although Q1 is still our overall window.

[maxsynnott]

Thanks for the update 🙂

[marcotas]

Maybe that's too late but, why not Astro instead of Nextjs? I believe (correct if I'm wrong because I'm pretty new to PayloadCMS) astro would provide the same benefits of Nextjs but also it would bring a lot more people from other community other than React. I believe Astro works very well with serverless, file-based routing, ssr, etc but you can choose any frontend framework like Vue, Svelte. Maybe this would be a dream? Not mentioning the possibility to use any of them together and the performance of astro.

Does this all make sense to someone? I love Svelte and would love to be able to deploy Payload with Svelte in serverless or edge functions on Vercel.

[CanRau]

Also think Astro sounds like it could be the perfect solution having all the adapters and build-pipeline but in an open and agnostic way 👍🏼

Was also just thinking about how RakkasJS uses vavite & HatTip for a pretty nice server/client dx

[jmikrut]

Astro was designed for building content-rich websites.

I pulled that line from Astro docs - it's not meant for what we're trying to do, and we specifically are tied to React already anyway and that is not going to change in the foreseeable future. We also need React Server Components. I think Astro looks super cool for websites though and it pairs nicely with Payload for frontends!

[cereallarceny]

I'm about to start working on a new app for a client and I'm considering using Payload for it. Ultimately, I want to build a NextJS app with Payload... should I wait until the beta period? I'm concerned about a length migration down the line if I start building on Payload today. @zubricks and @jmikrut could you maybe speak to what sort of breaking changes or migration path one should expect (at a high-level, not holding you to these decisions)?

[jmikrut]

Hey @cereallarceny — thanks for the question!

The migration will involve a similar amount of work as the migration from 1.0 to 2.0. Maybe even less, depending on how much you've got customized in the admin UI. If you don't have much customized, it could even be like 5 minutes of work to upgrade.

The database is not going to change at all — at least we don't see any reason for it to at this point. Neither will the Payload config. It will function the same as it does now, outside of some properties like middleware being removed (no longer relevant outside of Express).

Biggest things I see changing are:

• Passport / passport strategies will be going away because they are Express middleware. We will have a new auth strategy implementation for you to use. If you don't have anything custom here, then great, don't worry about it
• PayloadRequest - AKA the req will change a bit and not have Express-related functions anymore. It will be the Web standards API Request instead. 9 times out of 10, you won't notice the difference
• React Router will be removed, and we will be using Next.js' routing in the admin UI instead. So if you have any custom components that use functionality from React Router, you'll have to update those

Outside of that, I really don't see much changing except internally.

Whaddya think?

[cereallarceny]

That's fairly reasonable! As I'm understanding @jmikrut, I'd likely be able to avoid most migration issues by doing the following:

• Avoid middleware
• Avoid passport auth and perhaps use next-auth or something similar
• Avoid Express functions (preferring native Request instead)
• Use React Router, but perhaps go ahead and structure route entrypoints using the NextJS directory structure

If I do those things, I set myself up for a really straightforward migration... ideally. 😉

[jmikrut]

Yep - I wouldn't reach for next-auth right away though. You could still use the Payload auth the same way it works now. RE: auth strategies, I really only meant for any -custom- auth strategies that you might build. I would just use the built-in auth stuff and then that will require 0 migration effort.

[cereallarceny]

Ahhh, I got it now. So basically anything fairly standard should work: Google SSO, email/password, and magic links should be considered "safe"?

[koriolis]

@jmikrut Let's assume one has developed a Federated Authentication strategy using PassportJS - namely the azure oauth strategy - replacing the local strategy that PayloadCMS provides, including maintaining the ability of creating API Key only users.
I doubt that this would work "out of the box" (I mean without a major refactor) once ExpressJS is removed in favor of NextJS, would it?

[paper-krane]

I will admit, I am a bit hesitant of the Next.js move but that could easily be because I am far more comfortable in Express.js than Next.js (a pathetic excuse I am sure). But I trust you all that are behind this decision and am excited to see Payload continue to evolve! I do have some questions though.

I saw above the mention of a new auth strategy. Will there be a way to implement our own strategies in Next.js similar to how we could drop in another Passport.js strategy now?

Also, is this still planned to have a beta in early-ish 2024? Would love to really explore more.

[jmikrut]

Hey there - well, keep in mind, you can still run Next.js in Express and stick in the Express ecosystem if you want. We do that for all of our ecommerce and website templates right now. Here's an example of Next.js running on an Express server:

https://github.com/payloadcms/payload/blob/main/templates/website/src/server.ts

You will still be able to do something like this if you want to stick with Express for sure.

Regarding auth strategies, yes, this will be fully extensible and you will continue to be able to implement your own auth strategies. It will actually get much simpler honestly. The work here is already done. Passport is gone though. I think it was always overly complex for what we actually needed in Payload.

The work is slated to be done sometime next month actually. It's coming along at light speed and as planned!

[paper-krane]

This is all exciting news. And honestly, I am definitely up for learning the whole Next.js ecosystem. The comfort zone is a beautiful place but nothing ever grows there.

This is awesome to hear about Auth. I figured Passport.js would disappear and I am definitely not broken up about that. Felt like it just gave you a solid jumping off point for you to Frankenstein your own auth strategies from.

The more I am exploring the Next.js ecosystem, the more I can easily understand the move from Express.js to Next.js. It just makes sense. Can't wait to try the Beta! Thanks again for all of your hard work all!

[sqveeze]

I have a production app running express with payload. Will this continue to work and receive updates? I'm using it currently as an API + the editor functions on the admin, but its not using nextjs. In this case if payload migrates to nextjs this setup will work as well or i will need to remove express and deploy it with a nextjs app to vercel or somewhere else?

[jmikrut]

Yes, absolutely. I commented elsewhere in this discussion regarding how you can continue to use Express:

#4202 (reply in thread)

Take a look at that comment!

[klauss194]

Will we have to manage our own routing ? ( express setup )? and use payload more of an ORM style of implementation ?

[jmikrut]

Payload's routes themselves will all be managed for you if you bring your own Express server, exactly like how it works now. But you would be able to add any other Express routes yourself. Basically it'll all be the same as how it works now.

But, Payload itself can also be used as an ORM-style implementation completely independently of Next.js, where in that case, you could indeed open your own endpoints and do whatever you wanted (manage your own routing, etc.)

Does that make sense? There will be examples coming from us soon about what this looks like in practice but long story short, it won't be any different than it is now really if you want to continue to use Express!

[legezam]

As per my understanding, your specific scenario wont suffer at all unless you have custom passport related things in your app.

…

On Thu, 11 Jan 2024 at 15:22, Márk Pap ***@***.***> wrote: I have a production app running express with payload. Will this continue to work and receive updates? I'm using it currently as an API + the editor functions on the admin, but its not using nextjs. In this case if payload migrates to nextjs this setup will work as well or i will need to remove express and deploy it with a nextjs app to vercel or somewhere else? — Reply to this email directly, view it on GitHub <#4202 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AA6KJV45H5T75ZXNDCQCWGLYN77SFAVCNFSM6AAAAAA7QGYF5SVHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4DAOJXGMYDK> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[cbratschi]

I had a quick look at the POC branch. Is the Next.js implementation still using the pages router and not yet the app router? If yes, why?

[jmikrut]

No, it’s fully app router

[jacobsfletch]

Hey everyone, just wanted to give a quick update on the progress here. We're making significant headway on this. The current state of the app is that its rendering properly in Next.js, you can navigate around the admin panel, and we've officially achieved successful builds. We've since deployed a POC to Vercel to test out cold starts (which appears to be fast). From here, we're continuing to wire up server actions and continuing to migrate all remaining field types to SSR. We still need to wire in GQL (among other things) but the entire HTTP layer is now completely handled in Next. We're still on track to have beta packages available this quarter for everyone to try out.

Here's a brief update on each of the main requirements listed in the original discussion:

• Modularize the local API to be a standalone package: DONE
• Modularize Admin UI to be a separate component library: DONE
• Remove webpack aliases entirely: DONE
• Be able to deploy to serverless out of the box: DONE
• Remove requirement of maintaining webpack and vite bundlers - just differ to nextjs compiler: DONE
• Optimize serverless cold starts: TBD

We will provide a complete breakdown once we get closer to release, along with a migration doc that lists all breaking changes (there's not as many as it might seem). For anyone just jumping in here, this comment from @jmikrut is very informational and worth a quick read.

One of the things I'm most excited for in this work is how Payload will no longer be included in the client-side bundle. This means that any business logic that might have been contained in your conditional logic, validation functions, etc will be completely inaccessible to the client. The Payload config is now dynamically split between client and server components. This also means that Webpack aliasing will be a thing of the past (listed above) and we will longer be maintaining our own bundler pattern (meaning we can focus more on core product). Plus, the Payload Local API will be directly available in your components. This is a huge optimization. RSC ftw.

I'll post another update here in the coming weeks. Stay tuned!

[jmikrut]

@tyteen4a03 yeah, it's just kind of a side-effect. it's not delaying or taking lots of resources to do, but it will be a very good thing for people that DO plan to deploy serverless for sure

[nathanclevenger]

Is optimizing serverless cold starts a significant part of the 3.0 beta 1 release? I'm sure many people (myself included) don't intend to run Payload this way.

I'm also sure that many people WOULD deploy on Vercel if there weren't 3-5 second cold starts ... we would probably embed it into hundreds of NextJS projects that we have already on Vercel - where right now it's much much messier because we have to keep a separate backend deployed and in sync.

[plumduffer]

Super exciting! Looking forward to the beta release

[willviles]

This is going to hit hard, guys. The DX for those of us building Next.js apps w/Typescript and deploying serverlessly to Vercel is going to be game changing.

We'll get an end-to-end typed, fully-functional & extensible CMS & site, deployed serverlessly with a single git push, with crazy quick build-times and staging/preview deployments with no devops drudgery.

Such a good decision to do this, and so exciting. Well done on the progress, team Payload 🚀

[abe123442]

Wow if everything except serverless cold starts are already done, I'm very keen to start with Payload 3.0 on release 👀
Great job Payload team 🚀

[slavakurilyak]

Excited to see Payload 3.0 beta with Next.js while it cooks for a new months

[fpolli]

I am trying to choose a cms and I am attracted to the unopinionated nature of Payload, but this thread concerns me because I do not want to have to learn yet another environment (next) just to use it. Are you talking about just switching the admin panel from react (which I also do not use and do not want to learn) to next? I don't care what the admin panel is written in because I don't intend to screw with it, I just want to not be locked into a framework for deployment and my front end. I was hyped about Payload but now I'm confused. Please remain unopinionated.

[brachypelma]

My understanding is that with version 3, Payload will be integrated into Next.js. However, you should still be able to deploy it as an Express app (in the initial post that got this thread started, they say as much), and you can also always use Payload as a headless CMS, so you can use whatever front end you want if you're not interested in using Next for that. I suspect you won't need to know much about NextJS if you're using Payload as a headless CMS with some other front-end.

[fpolli]

Thank you, that explanation is helpful.

[brachypelma]

You're welcome. Also, v3 is available in alpha already, so you should be able to take it for a test spin today, with all the caveats that come with using software in alpha testing.

[fpolli]

You know, I think I have just decided on Payload. I'm sorry I didn't ask, "What is Next.js anyway" and google it before my post. :) Since I am just starting out, I will go ahead and install the v3 alpha. I might even go ahead and learn Next, although I enjoy writing vanilla JS/TS (just learning TS) and SASS

[revnelson]

With sharp becoming an optional dependency, what does that mean if we want to host with Vercel but still have automatic image size/format generation? I currently generate an AVIF and WEBP version of the image, each with 3 smaller resolutions to populate out a srcset for my frontend so I can tell my editors "just throw the full-resolution image up there".

[fpolli]

v3 is available in alpha already

And that would be the "alpha" branch, I assume. I think I will clone it and give it a shot

[ccssmnn]

There is a demo project https://github.com/payloadcms/payload-3.0-alpha-demo

You can use this one as a starter. The dependencies are available from npm as alpha versions, as you can see in the demo projects package.json.

"@payloadcms/db-mongodb": "3.0.0-alpha.48",
"@payloadcms/db-postgres": "3.0.0-alpha.48",
"@payloadcms/next": "3.0.0-alpha.48",
...

[fpolli]

Thanks!

[jacobsfletch]

Hey all! Here's another progress report. If you were unable to join our Discord community call—WE'RE OFFICIALLY IN ALPHA 🎉. Here's a breakdown of what this means exactly:

You can start playing around with the alpha package now. BUT our tests suites are not 100% passing yet (we're working hard on this) so please don't use this in production just yet (I know some of you will still try anyway). There are some bugs that we are aware of are features that are not yet completed. Once our test suites are fully passing, we will immediately release a beta version. If you like living on the edge, that might be a better time for you to work on a (semi)real project with it. We will officially go to 3.0 stable once beta has had adequate time to cook.

Alpha demo here: https://github.com/payloadcms/payload-3.0-alpha-demo. We're releasing new alpha versions almost daily, so if you're using this demo, please update to latest often. If you experience any issues, feel free to open a new ticket in that repo.

Highlights:

• Payload admin panel is now Next.js-native
• Turbopack works out of the box (this will get faster over time, expect more here)
• The Payload admin UI is built with React Server Components and automatically eliminates server-side code from your admin bundle, completely alleviating the need to use Webpack aliases to remove hooks, access control, etc.
• Payload is now fully-ESM across the board
• GraphQL is now initialized only when you hit the GraphQL endpoint, and does not affect overhead of REST API routes
• All UI components have been abstracted into a separate @payloadcms/ui package, which will be fully documented and exposed for your re-use once we hit stable 3.0 or before. Details here: Roadmap: Reusable React Component Library #293
• You can run your own Next.js site alongside of Payload in the same app
• You can now deploy Payload to Vercel, and there will be official support for Vercel Blob Storage coming soon (so no S3 needed for files)
• Server-side HMR works out of the box, with no need for nodemon or similar. When the Payload config changes, your app will automatically re-initialize Payload seamlessly in the background
• All custom React components can be server components by default, and you can decide if you want them to be server components or client components
• Sharp has been abstracted to be an optional dependency
• Payload now relies on the Web Request / Response APIs rather than the Node Request / Response
• Express can still be used with Next.js' Custom Server functionality
• Payload itself has slimmed down significantly and can now be fully portable, run anywhere. You can leverage the Payload Local API completely outside of Next.js if you want
• The data layer, including the shape of the database Payload used and the API responses in 2.0, has not been affected whatsoever

That's all for now. I'll post more updates as they come in!

[K-Mistele]

Will it be possible to use tailwind in the custom React components, and if so is there any configuration we need to do to make that happen other than adding it to the project?

Fwiw, it would be a great to see a list of known bugs that are causing failing tests so we can watch them get skooshed one-by-one until beta is ready :) Happy to contribute where I can on this!

[jacobsfletch]

You can already uses Tailwind in your custom components, you just need to install it in your app and inject custom classnames wherever needed. Payload itself is not Tailwind native, however, so you'll likely encounter conflicting styles in certain places. I have heard others using it though, just not sure to what success.

We're on track to be fully passing by this week or next—BUT this doesn't mean we're bug-free. We will work toward releasing beta at that point, then continue to increase our testing coverage through to 3.0 stable and beyond. I would have really liked to get an arewenextyet.com website up with a running count of passing/failing tests, but it was deprioritized for obv. reasons.

[fpolli]

When Payload is a next.js app will it be able to run as a static export or SPA, or will it need a server? I think for my use case, a static next.js export with an nginx server would be the best setup - if I can run Payload that way.

I suspect my questions show that I still don't really understand all of this.

[ccssmnn]

The NextJS app that serves the Payload Backend and Admin UI needs to be deployed as a server. Payload interacts with your database, your file storage and sends emails. It serves REST and GraphQL APIs. The Admin UI will take advantage of React Server Components that use Payloads local API.

[sannajammeh]

It can also be deployed serverless :)

[ccssmnn]

Just to be clear, since beginners might get confused by the terminology:

Serverless means you have a server, that essentially gets started to serve a request and then shuts down again. So Serverless does not mean that you don't need a server. It's a server set up in a way that makes it easy to scale up and down. For the benefits in scalability and cost you have a few constrains.

@sannajammeh correctly points out, that Payloads server logic is capable to run in a serverless environment.

[janus-reith]

I really love how this gives us the possibility to simply deploy Payload and the Site or App that consumes its content in one go on serverless environments - If your App that consumes the page is built on nextjs aswell.
I’m wondering how straightforward it would be to do the same with e.g. Astro, where the main page would be based on Astro and some subpath is handled by the payload nextjs app. It’s possible for sure, but I wonder how smooth that would work in environments like Vercel. Maybe it’s just a matter of some simple config changes there instead of using the default nextjs or Astro presets, but I wonder if there’s some roadblocks I might be missing.
Also I wonder if avoiding a separate api route roundtrip with getPayload might work in a similar fashion.
I could see Astro + Payload (+ Vercel) be or become a pretty common stack for website development.

[sannajammeh]

I tried. The problem lies within .env variables. Astro uses Vite which injects into import.meta.env and its not as straight forward getting the local api working well there (had to use rollup define). Pretty sure using unjs/unenv in payload.config.ts will be a good workaround.

If you go the REST/GraphQL route it will be pretty easy.

When it comes to invalidation of data, Astro does not have on-demand revalidation, but it can be implemented using middleware (running in edge mode) + serverless redis, then you can invalidate via a fetch call inside of Payload to your astro deployment. Or use a Vercel deploy hook, that should do the trick. You'd have to do this with any CMS.

[vstraigis]

Hey, stumbled upon this. I have a quick question. Once we can use it without needing express server, but simply in the nextjs app router, how will the authentication look. Why I am asking, I am looking for a simplified solution, for building company pages, i don't need authentication with it, but if I would provide CMS for them, i need to provide authentication also. What i am asking is how easy will it be to do that, will the auth feature will be there out of the box, or Will i have to do that myself with different providers like auth.js and so on. Thanks for your work, love what you are doing here!

[jacobsfletch]

Authentication is built directly into Payload itself and its a one-liner to enable: https://payloadcms.com/blog/simplified-authentication-for-headless-cms-unlocking-reusability-in-one-line. No need to reach for anything else like Auth.js or NextAuth. Here's our official example demonstrating how to do this in both the Pages Router and App Router: https://github.com/payloadcms/payload/tree/main/examples/auth/payload.

[jacobsfletch]

Re-reading your comment and want to clarify that all you need to do here is set auth: true on your users collection. This will enable authentication on the CMS-side (i.e. users can go to /admin/login). If you don't need to wire auth directly into your Next.js site (i.e. a custom login page), there's almost nothing to it.

[ranaharoon3222]

When Next js version launch any ETA?

[jacobsfletch]

Alpha is out! https://github.com/payloadcms/payload-3.0-alpha-demo. And now we're approaching our goal of 100% passing tests. We're on track to have our first beta version out by end of week. Stable 3.0 won't come for some time after that.

[jacobsfletch]

Beta has arrived! 🚀 More here: https://www.youtube.com/watch?v=CZ7a-dx3Glw

[ccssmnn]

From the video: the goal for beta -> stable is within 30 days, a migration guide is in the works.

[neslob]

Confetti 🎊

Awesome work, wish you all the best for the launch.

Is there any way, we can already have a look at beta, version 3 compatible, docs?
installation.mdx has been touched, but not version 3, ready.

❯ git diff main..beta --unified=0 -- docs/getting-started/installation.mdx
diff --git a/docs/getting-started/installation.mdx b/docs/getting-started/installation.mdx
index fa3afc249..c7793b82a 100644
--- a/docs/getting-started/installation.mdx
+++ b/docs/getting-started/installation.mdx
@@ -14 +14 @@ Payload requires the following software:
-- Node.js version 16+
+- Node.js version 18+
@@ -65,3 +65 @@ app.listen(3000, async () => {
-  console.log(
-    "Express is now listening for incoming connections on port 3000."
-  )
+  console.log('Express is now listening for incoming connections on port 3000.')
@@ -89,3 +87 @@ const start = async () => {
-    console.log(
-      "Express is now listening for incoming connections on port 3000."
-    )
+    console.log('Express is now listening for incoming connections on port 3000.')
@@ -107,0 +104 @@ Here is a list of all properties available to pass through `payload.init`:
+
@@ -128,0 +126 @@ An object used to configure SMTP. [Read more](/docs/email/overview).
+

[chrisvanmook]

@jacobsfletch Great work! One question: will the postgres adapter also become stable when 3.0 will be released?

[K-Mistele]

^ as of @payloadcms/db-postgres 3.0.0-beta.9, the postgres adapter is broken if you're using a non-default schema and errors out the ass when you try to run migrations. It doesn't create the non-default schema (it assumes it already exists), and it doesn't properly build the JSON for the migration either.

[DanRibbens]

^ as of @payloadcms/db-postgres 3.0.0-beta.9, the postgres adapter is broken if you're using a non-default schema and errors out the ass when you try to run migrations. It doesn't create the non-default schema (it assumes it already exists), and it doesn't properly build the JSON for the migration either.

We're working with the drizzle team on this one. They have changes coming soon it sounds like, until then, don't use a custom schema. Thanks for reporting!

[adesugbaa]

Great work on 3.0.

I have 2 issues to report

• I am unable to apply HeadingFeature (enabledHeadingSizes does not seem to work - it always returns h1 to h6( and HorizontalRuleFeature (Module '"@payloadcms/richtext-lexical"' has no exported member 'HorizontalRuleFeature') to the lexical editor.
• The SEO plugin is returning a blank page when I click on attach existing media. It seems to work when you select the option to create/upload a new media.

[jloncar]

Created issue here

[adesugbaa]

I have questions about the upload collection - it seems staticURL has been removed from the configuration. If you are uploading images to an external provider, how do you map the backend to the URLs?

It is currently mapping <PAYLOAD_URL>/media/ to the objects even though I have disabled local storage.

[K-Mistele]

I ran into this too - it's not there in the typescript types, but I did find that url property is added to the objects that are stored in MongoDB.

[AugustinMauroy]

I got a question I didn't see on the threat, why not do something like next-auth for api and page:

// app/api/payload/[...payload]/route.ts
import payload from "@payload/api"
 
export { payload as GET, payload as POST };

// app/api/payload/[...payload]/page.ts
import payload from "@payload/page"
 
export default payload

[chrisvanmook]

@jmikrut I've been closely following the development of Payload 3 and I'm really excited about the features it promises to bring. I was wondering if there's an (roughly) estimated timeline for when a stable version of Payload 3 might be released? Also, is there a specific place (like a roadmap with prioritised issues) where I can keep track of its progress and perhaps be able to contribute to make v3 stable? So far I've found this, but unfortunately it doesn't really give me any insights in terms of prioritisation / actual issues.
Thanks for your time and for all the hard work you guys are putting into this project!

[chrisvanmook]

Or @jacobsfletch could you perhaps give me some details on this?

[2Senn]

Any update on the stable release? Would be nice to get an estimate

[rilrom]

It's been said in discord that it won't be released until React 19 and Next.js 15 are released as stable.