Payload V3 beta released: The most important changes

V3 brings significant improvements, most notably that Payload is now a native Next.js app. This change means Payload uses features like the App Router and Next.js route handlers, making it incredibly easy to integrate with any (existing) Next.js frontend.

In this article, we'll guide you through creating a new project using Payload CMS and Next.js, setting up Tailwind CSS, leveraging hot module reloading, and deploying your project on Vercel.

Setting Up a New Project

To begin, let's create a new project powered by Payload CMS and running on a Next.js frontend.

Navigate to Your Desired Directory:

Open your terminal and go to the folder where you want to create your project.

Create a Payload App:

Run the following command to set up a new Payload app. Note that it’s in beta, so we need to specify the beta version.

npx create-payload-app@beta

Configure Your Project:

You'll be prompted to name your project. For this example, let's name it "my-first-blog". Choose the blank template (other templates will be available in the stable release) and select MongoDB as your database. You can use a local or remote MongoDB connection string.

? How should I name this project? my-first-blog
? Choose a template: blank
? Choose your database: MongoDB

Set Up the Frontend:

In the

app

folder, create a root layout by adding a

layout.jsx

layout.tsx

file and start building your frontend with Next.js.

Here's a boilerplate root layout file:

https://nextjs.org/docs/app/building-your-application/upgrading/app-router-migration#step-2-creating-a-root-layout

Integrating Tailwind CSS

Adding Tailwind CSS to your project is now easier than ever.

Install Tailwind CSS:

Follow the Tailwind CSS installation guide for Next.js.

https://tailwindcss.com/docs/guides/nextjs

Set Up Global Styles: Create a

global.css

file in the

app

folder and import your Tailwind styles.

@tailwind base;
@tailwind components;
@tailwind utilities;

Import this file in your root layout:

import './global.css';

Create a Custom Component: Add a custom component styled with Tailwind CSS and include it in your configuration.

// components/TestComponent.jsx
export default function TestComponent() {
  return (
    <div className="bg-green-500 p-4 text-green-100">
      Hey, this is a custom component!
    </div>
  );
}

Hot Module Reloading

One of the standout features in version 3 is hot module reloading. Changes to your configuration now appear instantly without needing to restart the server.

Try it out by making changes to a collection schema, and watching the admin panel update in real time

Leveraging React Server Components

With Payload CMS v3, all custom components are server components by default, allowing direct data fetching from Payload or any third-party API.

Create a Server Component: Fetch data directly within your server component.

import { getPayload } from 'payload';
import config from '@payload/config';

export default async function TestComponent() {
  const payload = await getPayload({ config });
  const users = await payload.find({
    collection: 'users',
  });

  return (
    <div>
      <h3>Users</h3>
      <div className="flex gap-2">
        {users.docs.map((user) => (
          <div key={user.id}>{user.email}</div>
        ))}
      </div>
    </div>
  );
}

Use Client Components When Needed: Convert components to client components when necessary.

'use client';

import { useState } from 'react';

export default function ClientComponent() {
  const [test, setTest] = useState('Test');

  return <div>{test}</div>;
}

Deploying to Vercel

Deploying your project on Vercel is straightforward and ensures your application is live with minimal effort.

Push Your Project to GitHub: Link your local repository to GitHub and push your changes.
Deploy on Vercel: Go to Vercel, create a new project, and import your repository. Configure your environment variables (e.g., database URI, Payload secret).
Launch Your Application: Deploy your project and access it through the provided Vercel URL. The first load might take a few seconds due to cold starts, but subsequent loads will be faster. If you want to learn, how you can get rid of cold starts on Vercel, read this.