@payloadcms/next-payload
v0.1.11
Published
Payload deployed as Vercel functions within a NextJS app
Downloads
968
Maintainers
Keywords
Readme
[!IMPORTANT] This package only works with Next.js 13. The Payload team has attempted to troubleshoot why this package doesn't work with Next.js 14, but can't resolve the issues. Instead of continuing to focus on this package's compatibility with Next.js 14, we are going to prioritize work on moving Payload fully to Next.js—at which point, this package will no longer be relevant and everything will just work out of the box. If you would like to use this package in the meantime as we work to launching Payload + Next.js native support, you can do so as long as you are running Next.js 13.
Next + Payload Serverless
This package contains a set of utilities to allow Payload to be deployed seamlessly, serverless, within an existing NextJS project. It adds the Payload admin UI into the NextJS /app
folder and adds all Payload endpoints into the pages/api
folder.
To do so, this package exposes a few different helpers. To get started, follow the steps below:
1. Add this package and Payload to your project
npm install @payloadcms/next-payload payload @payloadcms/bundler-webpack @payloadcms/db-mongodb @payloadcms/richtext-slate
# or
yarn add @payloadcms/next-payload payload @payloadcms/bundler-webpack @payloadcms/db-mongodb @payloadcms/richtext-slate
2. Run the command to extend your Next app with Payload
npx next-payload install
# or
yarn next-payload install
3. Your .env
should include:
# mongo connection string
MONGODB_URI=mongodb://127.0.0.1/next-payload-demo
# payload secret
PAYLOAD_SECRET=SOME_SECRET
# path to your payload.config file
PAYLOAD_CONFIG_PATH=payload/payload.config.ts
4. Add withPayload
to your next.config
Payload needs to inject some requirements into your Next config in order to function properly. To install withPayload
, you need to import it into your next.config.js
file. Here's an example:
// next.config.js
const path = require("path");
const { withPayload } = require("@payloadcms/next-payload");
module.exports = withPayload(
{
// your Next config here
},
{
// The second argument to `withPayload`
// allows you to specify paths to your Payload dependencies
// and configure the admin route to your Payload CMS.
// Point to your Payload config (required)
configPath: path.resolve(__dirname, "./payload/payload.config.ts"),
// Point to custom Payload CSS (optional)
cssPath: path.resolve(__dirname, "./css/my-custom-payload-styles.css"),
// Point to your exported, initialized Payload instance (optional, default shown below`)
payloadPath: path.resolve(process.cwd(), "./payload/payloadClient.ts"),
// Set a custom Payload admin route (optional, default is `/admin`)
// NOTE: Read the "Set a custom admin route" section in the payload/next-payload README.
adminRoute: "/admin",
}
);
And then you're done. Have fun!
Using the local API
The payload/payloadClient.ts
file will be added for you after running yarn next-payload install
(step 2). You can import getPayloadClient
from that file from within server components to leverage the Payloads Local API. The Local API does not use REST or GraphQL, and runs directly on your server talking directly to your database, which saves massively on HTTP-induced latency.
Here is an example:
// app/[slug]/page.tsx
import React from "react";
import { notFound } from "next/navigation";
import { getPayloadClient } from "../../payload/payloadClient";
const Page = async ({ params: { slug } }) => {
const payload = await getPayloadClient();
const pages = await payload.find({
collection: "pages",
where: {
slug: {
equals: slug || "home",
},
},
});
const page = pages.docs[0];
if (!page) return notFound();
return <h1>Hello, this is the "{page.slug}" page!</h1>;
};
export async function generateStaticParams() {
const payload = await getPayloadClient();
const pages = await payload.find({
collection: "pages",
limit: 0,
});
return pages.docs.map(({ slug }) => ({ slug }));
}
export default Page;
Set a custom admin route
Payload makes it simple to set a custom admin
route. However, since we are using next-payload
and relying on Next.js to handle all routing, we need to also tell Next.js to rewrite all admin related routes to Payload.
This is handled automatically by wrapping the Next.js configuration in withPayload
, which by default sets the admin route to /admin
. If you wish to change this default behavior, we need to do a couple of things.
In the following example, we are changing the admin route to /dashboard
.
1. Configure the admin
route in payload/payload.config.ts
as per the Payload documentation.
export default buildConfig({
// ... Payload config goes here
routes: {
admin: "/dashboard",
},
});
2. Rename the admin
directory under /app
to dashboard
.
3. Set adminRoute: "/dashboard",
in the next.config.js
file the withPayload config options as per the documentation above.
Known gotchas
Cold start delays
With the nature of serverless functions, you are bound to encounter "cold start" delays when your serverless functions spin up for the first time. Once they're "warm", the problem will go away for a few minutes until the functions become dormant again. But there's little that this package can do about that issue, unfortunately.
If you'd like to avoid cold starts with your Payload API, you can deploy on a server-based platform like Payload Cloud instead.
Need to sign up for additional vendors
To deploy Payload on Vercel, you'll need to configure additional vendors for the following:
- Database (MongoDB Atlas)
- File storage (AWS S3 or similar) with Payload's Cloud Storage Plugin
- Email service (Resend, Sendgrid)
If you don't want to go out and sign up for a separate file hosting service, you can just use Payload Cloud, which gives you file storage, a MongoDB Atlas database, email service by Resend, and lots more.
Developing this plugin
Using yarn pack
to develop this plugin locally is currently the best way to implement new features or debug existing behavior. Here are the steps to get setup:
Setting up the plugin for dev:
- Clone this repo
cd
into the folder you cloned this repo into and runyarn
- In the same folder, run
./scripts/pack-next-payload.sh ../path/to/your/project
in your terminal (it will run this script)
At this point your Next.js project will be using a locally built version of this plugin. You can make changes to the plugin and see them reflected in your project by re-running the command above. Note that this will change your package.json
file to point to the local version of the plugin, so you'll need to revert that change before committing your code.
If you run into any issues while developing, please open an issue in this repo so we can get it resolved. Thank you for contributing!