How to Install and Use Payload: A Comprehensive Guide 🚀

Saturday, Dec 14, 2024 | 4 minute read

GitHub Trend

This innovative solution empowers developers with flexibility, efficiency, and seamless integration specifically for Next.js. Enjoy enhanced productivity, real-time preview, and customizable styles, all while breaking free from traditional CMS limitations! 🎉✨

Introduction to Payload 🔍

“In the digital age, the choice of a content management system determines the future of a business.” 🚀
Today, we’re excited to introduce a cutting-edge headless content management system—Payload! As traditional content management systems struggle to meet the demands for flexibility and efficiency from developers and businesses, Payload emerges as an exceptional solution to this challenge. With its robust features and flexible architecture, Payload breaks the bounds of conventional CMS, empowering developers to tackle complex project requirements with ease.🔍
Payload is the first headless CMS designed specifically for Next.js, offering seamless integration with the existing /app folder, greatly simplifying the development process! 🤓 Say goodbye to cumbersome legacy systems—Payload allows developers to quickly get up to speed in a familiar environment, reducing the learning curve and boosting productivity!

Installing Payload CMS 📦

Ensure Your Environment is Ready ✅

Before you dive into installing Payload CMS, confirm that your development environment meets these basic requirements:

• JavaScript Package Manager: It’s recommended to use pnpm, as it is faster than other package managers!
• Node.js: Ensure your version is 20.9.0 or higher! You can check this with the command node -v.
• Database: Payload supports multiple databases including MongoDB, Postgres, and SQLite. Make sure everything is set before proceeding with the installation!

Creating a New Payload App 🆕

Want to quickly create a new Payload app? It’s super easy! Just run the following command in your terminal:

pnpx create-payload-app@latest

If you’re a beginner, it’s strongly recommended to use one of the website templates provided by the system:

pnpx create-payload-app@latest -t website

This command will generate a starter application including:

• Custom Rich Text Blocks: Easily edit your content!
• On-Demand Revalidation: Enhance user security!
• Real-Time Preview: Conveniently view your content as you edit!
• Frontend Built with TailwindCSS: Quickly customize your styles!

Everything will be neatly stored in the /app folder.

Adding Payload to an Existing Project 🌟

Assuming you already have a Next.js application, let’s add Payload to your project. If you haven’t created your Next.js application yet, don’t worry—simply run the following command to get started:

npx create-next-app

1. Install Required Packages 📦

Add the necessary Payload packages to your project by running the following command:

pnpm i payload @payloadcms/next @payloadcms/richtext-lexical sharp graphql

Installation Breakdown:

• payload: The core library that helps you build your CMS.
• @payloadcms/next: Ensures flawless integration of Payload within Next.js.
• @payloadcms/richtext-lexical: Provides rich text editor capabilities to help you edit effortlessly.
• sharp: A high-performance image processing library that instantly enhances your image quality.
• graphql: A powerful and flexible data query library that makes your application more efficient.

If you are using npm, you can run the following command to address possible compatibility issues:

npm i --legacy-peer-deps

Install the corresponding adapter based on your chosen database, it’s quick and straightforward!

• For MongoDB:

pnpm i @payloadcms/db-mongodb

• For Postgres:

pnpm i @payloadcms/db-postgres

2. Copy Payload Files 🔄

Next, copy the files from the blank GitHub template into your /app folder, ensuring your project structure looks like this:

app/
├─ (payload)/
└─ (my-app)/

The (payload) directory contains the copied Payload framework files, while the (my-app) directory is where your Next.js application resides.

3. Add Payload Plugin to Next.js Configuration ⚙️

Open your next.config.js file and sprinkle some “magic” for Payload by adding the plugin configuration:

import { withPayload } from '@payloadcms/next/withPayload'

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    reactCompiler: false // You can choose to disable the react compiler when using certain experimental features.
  }
}

// Wrap your config with `withPayload`
export default withPayload(nextConfig) 

Important Note: Ensure that you are using ESM modularity in your next.config.js, and don’t forget to add "type": "module" to your package.json, or rename the file with the .mjs extension!

4. Create and Configure Payload Configuration File 🔧

Next, we need to create a payload.config.ts file and insert the following content:

import sharp from 'sharp'
import { lexicalEditor } from '@payloadcms/richtext-lexical'
import { mongooseAdapter } from '@payloadcms/db-mongodb'
import { buildConfig } from 'payload'

export default buildConfig({
  editor: lexicalEditor(), // Enable the Lexical editor
  collections: [], // You can define your collections (data models) here
  secret: process.env.PAYLOAD_SECRET || '', // Get the secret from environment variables
  db: mongooseAdapter({
    url: process.env.DATABASE_URI || '', // Fill in your database connection URI
  }),
  sharp, // Import sharp for image processing
})

We also need to update the tsconfig.json file to add alias configurations, making it easier to access payload.config.ts:

{
  "compilerOptions": {
    "paths": {
      "@payload-config": [
        "./payload.config.ts" // Pointing to Payload configuration path
      ]
    }
  }
}

5. Start Your Application 🚀

In your application folder, run the following command to easily start your project:

pnpm dev

Once the application starts successfully, you can create your first Payload user by visiting http://localhost:3000/admin. ✨ With these simple steps, you can quickly master this powerful and flexible content management system—give it a try today!