@payloadcms/next-payload

[!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 run yarn
• 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!