Payload Block Thumbnails

Automatically generate block thumbnails for Payload CMS admin panel.

Installation

# Global installation
npm install -g payload-block-thumbnails

# Or use with npx
npx payload-block-thumbnails

Quick Start

# 1. Navigate to your Payload CMS project
cd your-payload-project

# 2. Initialize the thumbnail generator
npx payload-block-thumbnails init

# 3. Scan your blocks and generate mock data template
npx payload-block-thumbnails scan

# 4. Edit the mock data file
# src/app/(frontend)/block-preview/[slug]/mockData.ts

# 5. Add your block components to the preview page
# src/app/(frontend)/block-preview/[slug]/page.tsx

# 6. Install Playwright browsers (if not already installed)
npx playwright install chromium

# 7. Start your dev server
npm run dev

# 8. Generate thumbnails
npm run generate:thumbnails

# 9. Add imageURL to your block configs
npx payload-block-thumbnails add-urls

Commands

init

Initialize thumbnail generation in your project. Creates necessary files and directories.

npx payload-block-thumbnails init
npx payload-block-thumbnails init --force  # Overwrite existing files

scan

Scan your project for blocks and auto-generate mock data + page.tsx with component imports.

npx payload-block-thumbnails scan
npx payload-block-thumbnails scan --output ./custom/path/mockData.ts
npx payload-block-thumbnails scan --no-auto  # Disable mock data auto-generation
npx payload-block-thumbnails scan --no-page  # Skip page.tsx generation

The scan command:

1. Finds all blocks in src/blocks/*/config.ts
2. Detects component exports from Component.tsx
3. Auto-generates mockData.ts with appropriate mock data
4. Auto-generates page.tsx with all component imports and mappings

Auto-generated mock data:

| Field Type | Generated Mock Data | |------------|---------------------| | text | Context-aware text (title, name, email, etc.) | | textarea | Lorem ipsum paragraph | | richText | Formatted Lexical content | | number | Context-aware number (year, price, etc.) | | upload | Placeholder image object | | select/radio | First option value | | checkbox | true | | array | 2 example items | | group | Nested object with fields |

add-urls

Add imageURL property to all block configs that don't have it.

npx payload-block-thumbnails add-urls
npx payload-block-thumbnails add-urls --dry-run  # Preview changes

How It Works

1. Block Preview Route: Creates a Next.js route at /block-preview/[slug] that renders each block in isolation

2. Mock Data: You provide mock data for each block so they can render without database access

3. Screenshot Generation: Uses Playwright to visit each preview page and take screenshots

4. Thumbnails: Saves thumbnails to public/thumbnails/[slug].png

5. Block Config: Adds imageURL to your block configs so Payload CMS displays them in the admin

Configuration

Environment Variables

• BASE_URL - Dev server URL (default: http://localhost:3000)

Screenshot Settings

Edit scripts/generate-thumbnails.ts to customize:

const VIEWPORT = { width: 1400, height: 900 }
const SCREENSHOT_WIDTH = 1400
const SCREENSHOT_HEIGHT = 800

Requirements

• Node.js >= 18
• Payload CMS 2.x or 3.x
• Next.js 13+ (App Router)
• Playwright (for screenshot generation)

# Install Playwright package and Chromium browser
npm install -D playwright
npx playwright install chromium

License

MIT

Author

KREATIKA Maximilian A. Grimm Email: [email protected]

Copyright (c) 2025 KREATIKA Maximilian A. Grimm