Payload Next.js Starter

A block-based page builder powered by PayloadCMS for Next.js. Install this package into any Next.js project to add a full CMS with dynamic page content that can be shared across multiple applications.

Features

• Block-Based Page Builder — Hero, Content, Contact Form, Features, Pricing, Testimonials, CTA, Team, FAQ, Image Gallery
• Multi-App Support — Share one PostgreSQL database across multiple Next.js apps
• Admin Panel — Visual editor for managing pages and content
• Dynamic Routes — Automatic page rendering at /[slug]
• SEO Fields — Meta titles, descriptions, images per page
• Draft Mode — Preview changes before publishing
• TypeScript — Full type safety with generated types

Installation

Run the setup command in your Next.js project:

npx payload-next-starter

Or install globally:

npm install -g payload-next-starter
payload-next-starter

What it does

The setup script will:

1. Copy Payload admin routes to src/app/(payload)/
2. Copy API routes to src/app/api/[...payload]/
3. Copy collections (Users, Media, Pages) to src/collections/
4. Copy block components to src/components/blocks/
5. Copy BlockRenderer and RichTextContent components
6. Copy dynamic [slug] page renderer to src/app/(frontend)/[slug]/
7. Copy seed script to src/scripts/seedPages.ts
8. Install required dependencies
9. Update next.config.ts with Payload plugin
10. Add scripts to package.json
11. Create .env.example with required variables

After Installation

1. Copy .env.example to .env and fill in your values:

   DATABASE_URL_TEST=postgresql://user:password@host:5432/database?sslmode=require
   PAYLOAD_SECRET=your-secret-key-min-16-chars
   NEXT_PUBLIC_SERVER_URL=http://localhost:3000

2. Generate Payload import maps:

   npm run generate:importmap

3. Generate TypeScript types:

   npm run generate:types

4. Start your dev server:

   npm run dev

5. Visit http://localhost:3000/admin to create your first admin user

6. Seed sample pages (optional):

   npm run seed:pages

Using in Another Next.js App

This package is designed to be installed in multiple Next.js apps that share the same database. See CONSUMER_GUIDE.md for detailed instructions on:

• Installing the package in a consumer app
• Configuring the shared database connection
• Rendering dynamic pages with BlockRenderer
• Using individual block components
• Managing content across multiple apps

Collections Included

• Users — Authentication-enabled collection with admin access
• Media — Uploads collection with image handling
• Pages — Block-based page builder with SEO fields

Available Blocks

| Block | Description | |-------|-------------| | HeroBlock | Hero section with title, subtitle, CTA | | ContentBlock | Rich text content with heading | | ContactFormBlock | Contact form with info display | | FeaturesBlock | Feature grid with icons | | PricingBlock | Pricing plans table | | TestimonialsBlock | Customer testimonials | | CTABlock | Call-to-action banner | | TeamBlock | Team member cards | | FAQBlock | Accordion FAQ section | | ImageGalleryBlock | Image grid gallery |

Sample Pages

After running npm run seed:pages, the following sample pages are created:

| Route | Content | |-------|---------| | /home | Hero → Features → Testimonials → CTA | | /about-us | Hero → Story → Values → Team → CTA | | /contact-us | Hero → Contact Form → FAQ | | /services | Hero → Services → How We Work → CTA | | /pricing | Hero → Pricing → FAQ → CTA | | /faq | Hero → General FAQ → Technical FAQ → CTA | | /share | Hero → Share Ways → Referral → Testimonials → CTA |

Requirements

• Next.js 13+ with App Router
• Node.js 18.20+ or 20.9+
• PostgreSQL database (Neon, Supabase, or any managed Postgres)

Deploying

Deploy to Vercel, Railway, or any platform supporting Next.js:

npm run build

Ensure these environment variables are set in production:

• DATABASE_URL_TEST
• PAYLOAD_SECRET
• NEXT_PUBLIC_SERVER_URL

Customization

Edit src/payload.config.ts to add:

• More collections
• Globals
• Hooks
• Access control
• Custom block types

Edit block components in src/components/blocks/ to customize styling and behavior.

License

MIT

Support

• GitHub Issues
• Consumer Guide — For using in other Next.js apps
• Payload Docs