3.0 beta: Install Payload into any Next.js app with one line

Late in 2023, we announced an ambitious goal: building Payload on Next.js.

We're now thrilled to share that Payload 3.0 beta is now available. The big takeaway? You can now install the entirety of Payload in one line into any Next.js app.

Other highlights:

• Turbopack works out of the box
• Payload is now fully-ESM across the board
• You can now deploy Payload to Vercel
• Server-side HMR works out of the box
• All custom React components can be server components by default
• Express can still be used with Next.js' Custom Server functionality

Combining Payload into any Next.js app

I just want to take a second and concentrate on what it looks like to combine Payload with any Next.js app.

We're using the app folder in Next, we're using route handlers and server components and server actions and all that good stuff, and regarding server components specifically, I have seen the light—in short, we deeply needed to be able to separate server and client code.

Now, you don't have to worry about what parts of your Payload config go to the browser and which parts are only for the server—we do that for you automatically now thanks to server components.

Above is a test repo on Github, and you can see there's the app folder for Next.js. Within it, you have your app (in parenthesis), it's got a page, so that you can have a root layout for your app, and then we have Payload. Once you install Payload you get the Payload endpoints and the Payload admin panel directly inside of your app folder.

This happens with a simple one-line command: npx create-payload-app@beta

With that one line, you get everything up and running, you get Payload, you get your front end, you get whatever you need and it's all in one app—so you push code and then your front end and your changes to your Payload schema and your CMS are all in parallel, taking considerable technical complexity out of the equation. It will also guarantee more quality from an engineering standpoint.

This is going to restore some of the connection between the front-end to the back-end.

Throughout this process, Payload has gotten significantly more modular and isolated from even Next.js. We've taken a lot of strides toward isolating different concerns in our code base.

What this ultimately means is that Payload is now very, very small.

There are very few Payload dependencies and you can install this anywhere. If you want to use Payload inside of your SvelteKit app, you can. If you want to use Payload inside of your Nuxt app, go for it. Remix? Doesn't matter. You can import Payload and as long as you have your config, you can hit your database directly.

You don't go through an HTTP layer—the local API in Payload goes straight to your database. That might be obvious to some of our readers, but it’s a big difference. You don't have to go hit an endpoint that then hits your database, rather, you just go straight to the database.

And now you can install Payload anywhere.

Deploy Payload to Vercel

Now, all of this can be deployed to Vercel. Every single part of this can be deployed serverlessly.

I've been talking for a while about getting closer to supporting Cloudflare Workers and the Edge Runtime, and I think we're closer than I thought.

The entire bundle of Payload is 1.6 MBs—solving against the limit for Edge Runtime. Every single route inside of this whole app is less than 2 megabytes, so that's done.

Next up, we have to get Edge function compatibility, which requires figuring out a substitute for Nodemailer, so we can send email. Nodemailer relies on node APIs that are not supported in Cloudflare Workers. If anyone is smart with that, we're looking for input.

Regardless, as of this moment, it's all serverless, so you can deploy to Vercel, and it's just going to work right out of the box.

Get Turbopack out of box

If you've built a Payload app before, you know that we had our own Webpack stuff going on and we released the Vite bundler in 2.0. This was always a bit clunky, but that's completely fixed now because, thanks to server components, we take your config and we completely remove anything server-only from the config and then pass your config as props to the client components.

So you don't have to write Webpack aliases any longer and we don't even have to support bundlers ourselves. Next.js does that for us. And the coolest part is that it works with Turbopack.

We've gotten the initial load down to 8 seconds for the Payload admin panel. After it loads, it'll cache on your file system and become faster. That means the Monaco editor for the JSON and the code fields, date picker, React Select, drag-and-drop, all those React packages that the admin panel uses, we've gotten down to 8 seconds—and then the API side is 1,200 milliseconds.

It's very exciting for us to be able to focus on Payload rather than worrying about our Webpack config. It'll make you faster as an engineer because you don't have to write Webpack aliases—you don't have to worry about what gets to your front-end. We do that for you.

The divide of the server and client boundary is now very clear and transparent.

What's to come

There's many more details, including a brief walkthrough of our 3.0 beta demo, on my video. I encourage you to give it a look.

We are making this available to our community so that we can gather your feedback and test this approach.

There are some things that we are aware of that are not yet completed, but we're going to keep blazing through the remaining items as fast as we can to reach stable 3.0 as quickly and efficiently as possible.

Here's a quick breakdown of what's to come:

• Documentation
• Vercel Blob Storage adapter
• Lots of bugs for sure
• 100% of tests passing
• Compiler speed improvements (turbo is beta still, it is slower than it should be. it will get faster)
• Overall speed improvements
• An install script to be able to install Payload easily into any existing Next.js app
• A full list of breaking changes for 2.0 -> 3.0, including an in-depth migration guide

In the meantime, if you're not already, follow us on Discord and Twitter as we aim to have 3.0 stable released over the next month!