payload-next-starter 1.0.5 → 1.0.7

package/README.md

@@ -1,6 +1,16 @@
 # Payload Next.js Starter
 
-Quickly add PayloadCMS to any existing Next.js project. This package scaffolds PayloadCMS with PostgreSQL support into your Next.js application.
+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
 
@@ -19,31 +29,36 @@ payload-next-starter
 
 ## What it does
 
-This CLI tool will:
+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) to `src/collections/`
-4. Install required dependencies
-5. Update `next.config.ts` with Payload plugin
-6. Create `.env.example` with required variables
-
-## After installation
+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:
    ```bash
-   DATABASE_URI=postgresql://user:password@host:5432/database
+   DATABASE_URL=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:
    ```bash
-   npx payload generate:importmap
+   npm run generate:importmap
    ```
 
 3. Generate TypeScript types:
    ```bash
-   npx payload generate:types
+   npm run generate:types
    ```
 
 4. Start your dev server:
@@ -53,16 +68,61 @@ This CLI tool will:
 
 5. Visit `http://localhost:3000/admin` to create your first admin user
 
+6. Seed sample pages (optional):
+   ```bash
+   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](./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
-
-## Collections included
-
-- **Users** - Authentication-enabled collection with admin access
-- **Media** - Uploads collection with image handling
+- PostgreSQL database (Neon, Supabase, or any managed Postgres)
 
 ## Deploying
 
@@ -73,7 +133,7 @@ npm run build
 ```
 
 Ensure these environment variables are set in production:
-- `DATABASE_URI`
+- `DATABASE_URL`
 - `PAYLOAD_SECRET`
 - `NEXT_PUBLIC_SERVER_URL`
 
@@ -84,7 +144,9 @@ Edit `src/payload.config.ts` to add:
 - Globals
 - Hooks
 - Access control
-- Custom components
+- Custom block types
+
+Edit block components in `src/components/blocks/` to customize styling and behavior.
 
 ## License
 
@@ -92,4 +154,7 @@ MIT
 
 ## Support
 
-[GitHub Issues](https://github.com/sentayhu19/test-payload/issues)
+- [GitHub Issues](https://github.com/sentayhu19/test-payload/issues)
+- [Consumer Guide](./CONSUMER_GUIDE.md) — For using in other Next.js apps
+- [Payload Docs](https://payloadcms.com/docs)
+

package/bin/setup.js

@@ -36,6 +36,11 @@ try {
   mkdirSync(join(targetDir, 'src/app/(payload)'), { recursive: true })
   mkdirSync(join(targetDir, 'src/app/api/[...payload]'), { recursive: true })
   mkdirSync(join(targetDir, 'src/collections'), { recursive: true })
+  mkdirSync(join(targetDir, 'src/components'), { recursive: true })
+  mkdirSync(join(targetDir, 'src/components/blocks'), { recursive: true })
+  mkdirSync(join(targetDir, 'src/lib'), { recursive: true })
+  mkdirSync(join(targetDir, 'src/scripts'), { recursive: true })
+  mkdirSync(join(targetDir, 'src/app/next/preview'), { recursive: true })
 } catch (e) {
   // Directories might already exist
 }
@@ -71,7 +76,16 @@ if (existsSync(join(templatesDir, 'app/(frontend)'))) {
     recursive: true,
     force: true,
   })
-  console.log('  ✓ Frontend pages (about-us, contact-us, share)/')
+  console.log('  ✓ Frontend pages (about-us, contact-us, share, [slug])/')
+}
+
+// Copy components
+if (existsSync(join(templatesDir, 'components'))) {
+  cpSync(join(templatesDir, 'components'), join(targetDir, 'src/components'), {
+    recursive: true,
+    force: true,
+  })
+  console.log('  ✓ components/ (blocks, BlockRenderer, RichTextContent)/')
 }
 
 if (existsSync(join(templatesDir, 'app/api/[...payload]'))) {
@@ -82,6 +96,25 @@ if (existsSync(join(templatesDir, 'app/api/[...payload]'))) {
   console.log('  ✓ app/api/[...payload]/')
 }
 
+// Copy preview route
+if (existsSync(join(templatesDir, 'app/next/preview'))) {
+  mkdirSync(join(targetDir, 'src/app/next/preview'), { recursive: true })
+  cpSync(join(templatesDir, 'app/next/preview'), join(targetDir, 'src/app/next/preview'), {
+    recursive: true,
+    force: true,
+  })
+  console.log('  ✓ app/next/preview/ (draft mode)')
+}
+
+// Copy seed script
+if (existsSync(join(templatesDir, 'scripts'))) {
+  cpSync(join(templatesDir, 'scripts'), join(targetDir, 'src/scripts'), {
+    recursive: true,
+    force: true,
+  })
+  console.log('  ✓ scripts/seedPages.ts')
+}
+
 console.log('\n📦 Installing dependencies...')
 
 const deps = [
@@ -105,12 +138,38 @@ try {
     cwd: targetDir,
     stdio: 'inherit',
   })
+
+  // Install dev deps for seed script
+  execSync(`${pkgManager} add -D tsx cross-env`, {
+    cwd: targetDir,
+    stdio: 'inherit',
+  })
+
   console.log('✓ Dependencies installed\n')
 } catch (e) {
   console.error('❌ Failed to install dependencies:', e.message)
   process.exit(1)
 }
 
+// Add seed script to package.json
+console.log('📝 Adding scripts to package.json...')
+try {
+  const targetPkg = JSON.parse(readFileSync(join(targetDir, 'package.json'), 'utf8'))
+  if (!targetPkg.scripts) targetPkg.scripts = {}
+  if (!targetPkg.scripts['seed:pages']) {
+    targetPkg.scripts['seed:pages'] =
+      'cross-env NODE_OPTIONS=--no-deprecation tsx src/scripts/seedPages.ts'
+    targetPkg.scripts['generate:types'] =
+      'cross-env NODE_OPTIONS=--no-deprecation payload generate:types'
+    targetPkg.scripts['generate:importmap'] =
+      'cross-env NODE_OPTIONS=--no-deprecation payload generate:importmap'
+    writeFileSync(join(targetDir, 'package.json'), JSON.stringify(targetPkg, null, 2) + '\n')
+    console.log('  ✓ Added seed:pages, generate:types, generate:importmap scripts')
+  }
+} catch (e) {
+  console.log('  ⚠ Could not update scripts in package.json')
+}
+
 // Update next.config
 console.log('⚙️  Updating next.config...')
 const nextConfigPath = existsSync(join(targetDir, 'next.config.ts'))
@@ -168,4 +227,9 @@ console.log('  1. Copy .env.example to .env and fill in your values')
 console.log('  2. Run: npx payload generate:importmap')
 console.log('  3. Run: npx payload generate:types')
 console.log('  4. Start your dev server: npm run dev')
-console.log('\nAdmin panel will be at: http://localhost:3000/admin')
+console.log('  5. Seed sample pages: npm run seed:pages')
+console.log("     (This only creates pages that don't already exist in the DB)")
+console.log('\nAdmin panel: http://localhost:3000/admin')
+console.log(
+  'Pages:       http://localhost:3000/home, /about-us, /contact-us, /services, /pricing, /faq, /share',
+)

package/package.json

@@ -1,13 +1,22 @@
 {
   "name": "payload-next-starter",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "PayloadCMS starter for Next.js - install into any Next.js app",
   "license": "MIT",
   "type": "module",
   "bin": "./bin/setup.js",
+  "exports": {
+    "./blocks": "./src/components/blocks/index.ts",
+    "./BlockRenderer": "./src/components/BlockRenderer.tsx",
+    "./RichTextContent": "./src/components/RichTextContent.tsx"
+  },
   "files": [
     "bin/",
     "templates/",
+    "src/components/",
+    "src/collections/",
+    "src/scripts/",
+    "src/lib/",
     "README.md"
   ],
   "keywords": [

package/src/collections/Media.ts

@@ -0,0 +1,16 @@
+import type { CollectionConfig } from 'payload'
+
+export const Media: CollectionConfig = {
+  slug: 'media',
+  access: {
+    read: () => true,
+  },
+  fields: [
+    {
+      name: 'alt',
+      type: 'text',
+      required: true,
+    },
+  ],
+  upload: true,
+}

package/src/collections/Pages.ts

@@ -0,0 +1,358 @@
+import type { CollectionConfig, Block } from 'payload'
+
+const getPreviewPath = (slug?: string) => {
+  const baseURL = process.env.NEXT_PUBLIC_SERVER_URL || 'http://localhost:3000'
+  const path = slug === 'home' || !slug ? '/' : `/${slug}`
+  const previewSecret = process.env.PAYLOAD_SECRET || ''
+
+  return `${baseURL}/next/preview?secret=${encodeURIComponent(previewSecret)}&slug=${encodeURIComponent(path)}`
+}
+
+const HeroBlock: Block = {
+  slug: 'hero',
+  labels: {
+    singular: 'Hero Section',
+    plural: 'Hero Sections',
+  },
+  fields: [
+    { name: 'title', type: 'text', required: true },
+    { name: 'subtitle', type: 'textarea' },
+    { name: 'backgroundImage', type: 'upload', relationTo: 'media' },
+    { name: 'ctaText', type: 'text', admin: { description: 'Call to action button text' } },
+    { name: 'ctaLink', type: 'text', admin: { description: 'Call to action button link' } },
+    {
+      name: 'alignment',
+      type: 'select',
+      defaultValue: 'center',
+      options: [
+        { label: 'Left', value: 'left' },
+        { label: 'Center', value: 'center' },
+        { label: 'Right', value: 'right' },
+      ],
+    },
+  ],
+}
+
+const ContentBlock: Block = {
+  slug: 'content',
+  labels: {
+    singular: 'Content Section',
+    plural: 'Content Sections',
+  },
+  fields: [
+    { name: 'heading', type: 'text' },
+    { name: 'body', type: 'richText', required: true },
+  ],
+}
+
+const ContactFormBlock: Block = {
+  slug: 'contactForm',
+  labels: {
+    singular: 'Contact Form',
+    plural: 'Contact Forms',
+  },
+  fields: [
+    { name: 'heading', type: 'text', defaultValue: 'Get In Touch' },
+    { name: 'description', type: 'textarea' },
+    { name: 'email', type: 'text', required: true },
+    { name: 'phone', type: 'text' },
+    { name: 'address', type: 'textarea' },
+    {
+      name: 'formFields',
+      type: 'select',
+      hasMany: true,
+      defaultValue: ['name', 'email', 'message'],
+      options: [
+        { label: 'Name', value: 'name' },
+        { label: 'Email', value: 'email' },
+        { label: 'Phone', value: 'phone' },
+        { label: 'Subject', value: 'subject' },
+        { label: 'Message', value: 'message' },
+      ],
+    },
+  ],
+}
+
+const FeaturesBlock: Block = {
+  slug: 'features',
+  labels: {
+    singular: 'Features Section',
+    plural: 'Features Sections',
+  },
+  fields: [
+    { name: 'heading', type: 'text' },
+    { name: 'subheading', type: 'textarea' },
+    {
+      name: 'items',
+      type: 'array',
+      minRows: 1,
+      fields: [
+        { name: 'icon', type: 'text', admin: { description: 'Emoji or icon name' } },
+        { name: 'title', type: 'text', required: true },
+        { name: 'description', type: 'textarea' },
+      ],
+    },
+    {
+      name: 'columns',
+      type: 'select',
+      defaultValue: '3',
+      options: [
+        { label: '2 Columns', value: '2' },
+        { label: '3 Columns', value: '3' },
+        { label: '4 Columns', value: '4' },
+      ],
+    },
+  ],
+}
+
+const ImageGalleryBlock: Block = {
+  slug: 'imageGallery',
+  labels: {
+    singular: 'Image Gallery',
+    plural: 'Image Galleries',
+  },
+  fields: [
+    { name: 'heading', type: 'text' },
+    {
+      name: 'images',
+      type: 'array',
+      minRows: 1,
+      fields: [
+        { name: 'image', type: 'upload', relationTo: 'media', required: true },
+        { name: 'caption', type: 'text' },
+      ],
+    },
+    {
+      name: 'columns',
+      type: 'select',
+      defaultValue: '3',
+      options: [
+        { label: '2 Columns', value: '2' },
+        { label: '3 Columns', value: '3' },
+        { label: '4 Columns', value: '4' },
+      ],
+    },
+  ],
+}
+
+const PricingBlock: Block = {
+  slug: 'pricing',
+  labels: {
+    singular: 'Pricing Section',
+    plural: 'Pricing Sections',
+  },
+  fields: [
+    { name: 'heading', type: 'text', defaultValue: 'Pricing Plans' },
+    { name: 'subheading', type: 'textarea' },
+    {
+      name: 'plans',
+      type: 'array',
+      minRows: 1,
+      fields: [
+        { name: 'name', type: 'text', required: true },
+        { name: 'price', type: 'text', required: true },
+        { name: 'period', type: 'text', defaultValue: '/month' },
+        { name: 'description', type: 'textarea' },
+        {
+          name: 'features',
+          type: 'array',
+          fields: [{ name: 'feature', type: 'text', required: true }],
+        },
+        { name: 'ctaText', type: 'text', defaultValue: 'Get Started' },
+        { name: 'ctaLink', type: 'text' },
+        { name: 'highlighted', type: 'checkbox', defaultValue: false },
+      ],
+    },
+  ],
+}
+
+const TestimonialsBlock: Block = {
+  slug: 'testimonials',
+  labels: {
+    singular: 'Testimonials Section',
+    plural: 'Testimonials Sections',
+  },
+  fields: [
+    { name: 'heading', type: 'text', defaultValue: 'What Our Customers Say' },
+    {
+      name: 'testimonials',
+      type: 'array',
+      minRows: 1,
+      fields: [
+        { name: 'name', type: 'text', required: true },
+        { name: 'role', type: 'text' },
+        { name: 'company', type: 'text' },
+        { name: 'quote', type: 'textarea', required: true },
+        { name: 'avatar', type: 'upload', relationTo: 'media' },
+        {
+          name: 'rating',
+          type: 'select',
+          options: [
+            { label: '5 Stars', value: '5' },
+            { label: '4 Stars', value: '4' },
+            { label: '3 Stars', value: '3' },
+          ],
+        },
+      ],
+    },
+  ],
+}
+
+const CTABlock: Block = {
+  slug: 'cta',
+  labels: {
+    singular: 'Call to Action',
+    plural: 'Call to Actions',
+  },
+  fields: [
+    { name: 'heading', type: 'text', required: true },
+    { name: 'description', type: 'textarea' },
+    { name: 'buttonText', type: 'text', required: true },
+    { name: 'buttonLink', type: 'text', required: true },
+    { name: 'secondaryButtonText', type: 'text' },
+    { name: 'secondaryButtonLink', type: 'text' },
+    {
+      name: 'style',
+      type: 'select',
+      defaultValue: 'primary',
+      options: [
+        { label: 'Primary (Blue)', value: 'primary' },
+        { label: 'Secondary (Gray)', value: 'secondary' },
+        { label: 'Accent (Gradient)', value: 'accent' },
+      ],
+    },
+  ],
+}
+
+const TeamBlock: Block = {
+  slug: 'team',
+  labels: {
+    singular: 'Team Section',
+    plural: 'Team Sections',
+  },
+  fields: [
+    { name: 'heading', type: 'text', defaultValue: 'Meet Our Team' },
+    { name: 'subheading', type: 'textarea' },
+    {
+      name: 'members',
+      type: 'array',
+      minRows: 1,
+      fields: [
+        { name: 'name', type: 'text', required: true },
+        { name: 'role', type: 'text', required: true },
+        { name: 'bio', type: 'textarea' },
+        { name: 'photo', type: 'upload', relationTo: 'media' },
+        { name: 'linkedin', type: 'text' },
+        { name: 'twitter', type: 'text' },
+      ],
+    },
+  ],
+}
+
+const FAQBlock: Block = {
+  slug: 'faq',
+  labels: {
+    singular: 'FAQ Section',
+    plural: 'FAQ Sections',
+  },
+  fields: [
+    { name: 'heading', type: 'text', defaultValue: 'Frequently Asked Questions' },
+    {
+      name: 'questions',
+      type: 'array',
+      minRows: 1,
+      fields: [
+        { name: 'question', type: 'text', required: true },
+        { name: 'answer', type: 'textarea', required: true },
+      ],
+    },
+  ],
+}
+
+export const Pages: CollectionConfig = {
+  slug: 'pages',
+  admin: {
+    useAsTitle: 'title',
+    defaultColumns: ['title', 'slug', '_status', 'updatedAt'],
+    livePreview: {
+      url: ({ data }) => {
+        const pageData = data as { slug?: string } | undefined
+        return getPreviewPath(pageData?.slug)
+      },
+    },
+    preview: ({ data }) => {
+      const pageData = data as { slug?: string } | undefined
+      return getPreviewPath(pageData?.slug)
+    },
+  },
+  versions: {
+    drafts: {
+      autosave: {
+        interval: 300,
+      },
+      schedulePublish: true,
+    },
+  },
+  fields: [
+    {
+      type: 'tabs',
+      tabs: [
+        {
+          label: 'Content',
+          fields: [
+            {
+              name: 'title',
+              type: 'text',
+              required: true,
+            },
+            {
+              name: 'slug',
+              type: 'text',
+              required: true,
+              unique: true,
+              index: true,
+              admin: {
+                description: 'URL path (e.g., "contact-us", "about", "pricing")',
+              },
+            },
+            {
+              name: 'layout',
+              type: 'blocks',
+              blocks: [
+                HeroBlock,
+                ContentBlock,
+                ContactFormBlock,
+                FeaturesBlock,
+                ImageGalleryBlock,
+                PricingBlock,
+                TestimonialsBlock,
+                CTABlock,
+                TeamBlock,
+                FAQBlock,
+              ],
+            },
+          ],
+        },
+        {
+          label: 'SEO',
+          fields: [
+            {
+              name: 'seo',
+              type: 'group',
+              fields: [
+                {
+                  name: 'metaTitle',
+                  type: 'text',
+                  admin: { description: 'Defaults to page title if empty' },
+                },
+                { name: 'metaDescription', type: 'textarea' },
+                { name: 'metaImage', type: 'upload', relationTo: 'media' },
+                { name: 'noIndex', type: 'checkbox', defaultValue: false },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ],
+}

package/src/collections/Users.ts

@@ -0,0 +1,13 @@
+import type { CollectionConfig } from 'payload'
+
+export const Users: CollectionConfig = {
+  slug: 'users',
+  admin: {
+    useAsTitle: 'email',
+  },
+  auth: true,
+  fields: [
+    // Email added by default
+    // Add more fields as needed
+  ],
+}