npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@payloadcms/next-payload

v0.1.11

Published

Payload deployed as Vercel functions within a NextJS app

Downloads

888

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:

  1. Clone this repo
  2. cd into the folder you cloned this repo into and run yarn
  3. 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!