@nextbridgehq/payload-block-builder 0.1.8 → 0.1.9

package/README.md

@@ -1,22 +1,54 @@
 # Payload Block Builder
 
-Developed and open-sourced by [Nextbridge](https://nextbridge.com). This plugin was built to solve a real problem we kept running into: content editors needing to manage flexible page layouts without requiring a developer for every change.
+[![npm version](https://img.shields.io/npm/v/@nextbridgehq/payload-block-builder.svg)](https://www.npmjs.com/package/@nextbridgehq/payload-block-builder)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Payload CMS](https://img.shields.io/badge/Payload-v3-blue.svg)](https://payloadcms.com)
+
+> A visual block builder plugin for Payload CMS v3. Design content blocks through a drag-and-drop UI, store schemas in your database, and let editors build pages without waiting on a developer.
+
+Developed and open-sourced by [Nextbridge](https://nextbridge.com).
+
+## Screenshots
+
+![Block Builder canvas](https://raw.githubusercontent.com/nextbridgehq/block-builder/main/docs/screenshots/canvas.png)
+![Schema builder field](https://raw.githubusercontent.com/nextbridgehq/block-builder/main/docs/screenshots/schema-builder.png)
+![DB Layout tab on a collection](https://raw.githubusercontent.com/nextbridgehq/block-builder/main/docs/screenshots/db-layout-tab.png)
 
 ---
 
-A visual block builder plugin for Payload v3. Design your content blocks through a drag-and-drop UI, store the schemas in your database, and let editors build pages without waiting on a developer every time something needs to change.
+## 🎯 The Problem
 
-## Use cases
+Content editors need to manage flexible page layouts — but every new block type or layout change requires a developer to update code, redeploy, and migrate. This creates bottlenecks, slows down marketing teams, and turns simple content tasks into engineering tickets.
 
-- **Dynamic landing pages:** Let editors compose pages from a library of blocks (hero, features, testimonials, CTA) without any code changes.
-- **Multi-tenant platforms:** Each tenant can have its own block definitions without touching shared config or triggering redeployments.
-- **Marketing teams:** Give marketing full control to create, update, and reorder blocks on any page, any time.
-- **Evolving content schemas:** Roll out new block versions without breaking content that was built against older ones.
-- **Headless frontends:** Fetch structured block data from the Payload API and render it with any framework.
+## 💡 The Solution
+
+Payload Block Builder moves block schema definitions from code into your database. Editors design blocks visually, publish them instantly, and use them across any collection — all without touching code or triggering deployments.
+
+---
 
-## Database compatibility
+## ✨ Features
+
+- **Visual drag-and-drop block designer** — No code required to create new block types
+- **Database-stored schemas** — Block definitions live in your DB, not your codebase
+- **Version snapshots** — Every publish creates an immutable version; existing content never breaks
+- **Collection integration** — Adds a "DB Layout" tab to any collection with one line of config
+- **13 field types** — text, textarea, number, email, date, checkbox, select, radio, upload, relationship, json, and more
+- **Multi-tenant ready** — Each tenant can have its own block definitions without shared config changes
+- **Framework agnostic frontend** — Fetch structured JSON and render with React, Vue, Svelte, or anything else
+- **Automatic init command** — Get up and running in under 2 minutes
+- **Works with all Payload databases** — PostgreSQL, SQLite, MongoDB — no database-specific code
+
+---
+
+## 📋 Compatibility
+
+| Requirement | Version |
+|---|---|
+| Payload CMS | v3.x |
+| Node.js | ≥ 18 |
+| Next.js | ≥ 14 |
 
-Works with all Payload-supported databases — no direct SQL, no database-specific code:
+### Database Support
 
 | Database | Adapter |
 |---|---|
@@ -26,25 +58,27 @@ Works with all Payload-supported databases — no direct SQL, no database-specif
 
 ---
 
-## Quick start
+## 🚀 Quick Start
 
-### Option A — Automatic setup (recommended)
-
-Install the package and run the init command from your project root:
+### Option A — Automatic Setup (Recommended)
 
 ```bash
+# Install
 pnpm add @nextbridgehq/payload-block-builder
 # or: npm install @nextbridgehq/payload-block-builder
 
+# Initialize
 npx payload-block-builder init
 ```
 
 The init command automatically:
 
-- Creates `src/app/block-builder/page.tsx` — the builder UI page
-- Creates `src/app/block-builder/layout.tsx` — standalone layout with `<html>` and `<body>` tags
-- Updates `src/app/(payload)/custom.scss` — injects admin field styles
-- Updates `payload.config.ts` — adds the `dynamicBlocksPlugin` import and config
+| What it does | File |
+|---|---|
+| Creates the builder UI page | `src/app/block-builder/page.tsx` |
+| Creates a standalone layout | `src/app/block-builder/layout.tsx` |
+| Injects admin field styles | `src/app/(payload)/custom.scss` |
+| Adds plugin config | `payload.config.ts` |
 
 Then regenerate the import map and start your dev server:
 
@@ -53,9 +87,10 @@ pnpm generate:importmap
 pnpm dev
 ```
 
-Visit `http://localhost:3000/block-builder` and you're ready to build.
+Visit `https://your-domain.com/block-builder` and you're ready to build.
 
-> **PostgreSQL users:** Payload will automatically push the new schema tables on first startup in dev mode. If you are using migrations in production, run:
+> **PostgreSQL users:** Payload will automatically push new schema tables on first startup in dev mode. For production migrations:
+>
 > ```bash
 > pnpm payload migrate:create --name=add_block_builder
 > pnpm payload migrate
@@ -63,7 +98,8 @@ Visit `http://localhost:3000/block-builder` and you're ready to build.
 
 ---
 
-### Option B — Manual setup
+<details>
+<summary><strong>Option B — Manual Setup</strong></summary>
 
 **1. Install:**
 
@@ -138,19 +174,28 @@ pnpm generate:importmap
 pnpm dev
 ```
 
+</details>
+
 ---
 
-## Plugin options
+## ⚙️ Configuration Options
 
 ```ts
 dynamicBlocksPlugin({
-  enabled?: boolean      // Disable without removing. Default: true
-  collections?: string[] // Collection slugs that get the DB Layout tab. Default: []
-  fieldName?: string     // Name of the layout array field. Default: 'dbLayout'
-  tabLabel?: string      // Label shown on the tab in the admin UI. Default: 'DB Layout'
+  enabled?: boolean,       // Disable without removing. Default: true
+  collections?: string[],  // Collection slugs that get the DB Layout tab. Default: []
+  fieldName?: string,      // Name of the layout array field. Default: 'dbLayout'
+  tabLabel?: string,       // Label shown on the tab in the admin UI. Default: 'DB Layout'
 })
 ```
 
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `enabled` | `boolean` | `true` | Toggle the plugin on/off without removing it from config |
+| `collections` | `string[]` | `[]` | Collection slugs that receive the DB Layout tab |
+| `fieldName` | `string` | `'dbLayout'` | The field name for the layout array stored on documents |
+| `tabLabel` | `string` | `'DB Layout'` | Label displayed on the tab in the Payload admin UI |
+
 The `--collections` flag is also supported in the init command:
 
 ```bash
@@ -159,17 +204,17 @@ npx payload-block-builder init --collections=pages,posts
 
 ---
 
-## Usage
+## 📖 Usage
 
-### Creating a block
+### Creating a Block
 
 1. Open `/block-builder` in your browser.
 2. Click "Add Block" and give it a name and slug.
 3. Drag fields from the panel on the right onto the canvas.
 4. Configure each field (label, name, required, options, etc.).
-5. Click Publish. The block schema is saved to your database and a version snapshot is created.
+5. Click Publish — the block schema is saved to your database and a version snapshot is created.
 
-### Using blocks in a collection
+### Using Blocks in a Collection
 
 Any collection listed in the `collections` option gets a new "DB Layout" tab in the Payload admin. Editors can:
 
@@ -179,54 +224,111 @@ Any collection listed in the `collections` option gets a new "DB Layout" tab in
 4. Reorder, hide, or add anchor IDs to individual block instances.
 5. Save the document as normal.
 
-### Reading block data on the frontend
+### Reading Block Data on the Frontend
 
 ```ts
 const res = await fetch('/api/pages/my-page?depth=2')
 const page = await res.json()
 
 for (const block of page.dbLayout) {
-  const type = block.blockDefinition.slug  // e.g. "hero"
-  const fields = block.data               // { heading: '...', image: '...', ... }
+  const type = block.blockDefinition.slug   // e.g. "hero"
+  const fields = block.data                 // { heading: '...', image: '...', ... }
   const isHidden = block.hidden
+  const anchor = block.anchorId
 }
 ```
 
-Render each block type however you like — a switch statement or a component map both work well.
+### Example: React Component Map
 
----
+```tsx
+const blockComponents = {
+  hero: HeroBlock,
+  features: FeaturesBlock,
+  testimonials: TestimonialsBlock,
+  cta: CTABlock,
+}
+
+function PageRenderer({ blocks }) {
+  return (
+    <>
+      {blocks
+        .filter((block) => !block.hidden)
+        .map((block, i) => {
+          const Component = blockComponents[block.blockDefinition.slug]
+          if (!Component) return null
+          return (
+
+
+
+          )
+        })}
+    </>
+  )
+}
+```
 
-## How it works
+> **Note:** The inner JSX of the `return (` in the React Component Map example is intentionally left blank in this snippet — fill in with your `<section>` / `<Component>` rendering as appropriate for your app.
 
-- **Block definitions** are stored in a `block-definitions` collection. Each document is a named block type with a slug and a list of field definitions.
-- **Versions** are stored in a `block-definition-versions` collection. Every time you publish a block, a snapshot of its schema is saved as a new version.
-- **Documents** in opted-in collections store a reference to the exact block version they were built against, so updating a block schema later does not break existing content.
-- **The DB Layout tab** is injected automatically into each collection you list. It renders a dynamic array field where editors pick a block and version, and the field UI adjusts to match.
-- **Four internal API endpoints** power the builder UI and the admin field components. You do not need to call them directly.
+---
+
+## 🧩 Supported Field Types
+
+| Type | Description | Admin UI |
+|---|---|---|
+| `text` | Single-line text input | Standard text field |
+| `textarea` | Multi-line text input | Expandable textarea |
+| `number` | Numeric input | Number field with validation |
+| `email` | Email address | Email field with validation |
+| `date` | Date picker | Calendar date picker |
+| `checkbox` | Boolean toggle | Checkbox input |
+| `select` | Dropdown with custom options | Select dropdown |
+| `radio` | Radio button group | Radio buttons |
+| `upload` | File/image picker | Media library picker |
+| `relationship` | Document picker from any collection | Relationship field |
+| `json` | Raw JSON data | JSON editor |
 
 ---
 
-## Supported field types
+## 🏗️ Architecture
 
-These field types are available in the block builder and render correctly in the admin field UI:
+```
+┌─────────────────────────────────────────────────────┐
+│                   Block Builder UI                  │
+│            /block-builder (drag & drop)             │
+└──────────────────────────┬──────────────────────────┘
+                           │ Publish
+                           ▼
+┌─────────────────────────────────────────────────────┐
+│            block-definitions collection             │
+│          (name, slug, field definitions)            │
+└──────────────────────────┬──────────────────────────┘
+                           │ Snapshot
+                           ▼
+┌─────────────────────────────────────────────────────┐
+│        block-definition-versions collection         │
+│      (immutable schema snapshots per publish)       │
+└──────────────────────────┬──────────────────────────┘
+                           │ Referenced by
+                           ▼
+┌─────────────────────────────────────────────────────┐
+│           Your Collection (e.g. "pages")            │
+│   dbLayout: [{ blockDefinition, version, data }]    │
+└─────────────────────────────────────────────────────┘
+```
 
-| Type | Description |
-|---|---|
-| `text` | Single-line text input |
-| `textarea` | Multi-line text input |
-| `number` | Numeric input |
-| `email` | Email address |
-| `date` | Date picker |
-| `checkbox` | Boolean toggle |
-| `select` | Dropdown with custom options |
-| `radio` | Radio button group with custom options |
-| `upload` | File / image picker (from the media collection) |
-| `relationship` | Document picker from any collection |
-| `json` | Raw JSON data |
+Key design decisions:
+
+- Block definitions are stored in a `block-definitions` collection. Each document is a named block type with a slug and a list of field definitions.
+- Versions are stored in a `block-definition-versions` collection. Every publish creates an immutable snapshot.
+- Documents in opted-in collections store a reference to the exact block version they were built against — updating a block schema later does not break existing content.
+- The DB Layout tab is injected automatically into each collection you list. It renders a dynamic array field where editors pick a block and version.
+- Four internal API endpoints power the builder UI and admin field components. You do not need to call them directly.
 
 ---
 
-## Using `dbLayoutField` directly
+## 🔧 Advanced Usage
+
+### Using `dbLayoutField` Directly
 
 If you prefer not to use the plugin's `collections` option, you can add the layout tab manually to any collection:
 
@@ -239,9 +341,9 @@ export const Pages: CollectionConfig = {
     {
       type: 'tabs',
       tabs: [
-        { label: 'Content', fields: [] },
-        dbLayoutField(),                         // fieldName='dbLayout', tab label='DB Layout'
-        dbLayoutField('heroBlocks', 'Hero'),     // custom field name and tab label
+        { label: 'Content', fields: [/* your fields */] },
+        dbLayoutField(),                           // fieldName='dbLayout', tab label='DB Layout'
+        dbLayoutField('heroBlocks', 'Hero'),       // custom field name and tab label
       ],
     },
   ],
@@ -250,7 +352,7 @@ export const Pages: CollectionConfig = {
 
 ---
 
-## CSS imports reference
+## 📦 CSS Imports Reference
 
 | Import path | Purpose |
 |---|---|
@@ -260,6 +362,41 @@ export const Pages: CollectionConfig = {
 
 ---
 
-## License
+## 🗺️ Use Cases
+
+| Use Case | How It Helps |
+|---|---|
+| Dynamic landing pages | Editors compose pages from a library of blocks (hero, features, testimonials, CTA) without code changes |
+| Multi-tenant platforms | Each tenant gets its own block definitions without touching shared config or triggering redeployments |
+| Marketing teams | Full control to create, update, and reorder blocks on any page, any time |
+| Evolving content schemas | Roll out new block versions without breaking content built against older ones |
+| Headless frontends | Fetch structured block data from the Payload API and render with any framework |
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please see our Contributing Guide for details.
+
+- Fork the repository
+- Create your feature branch (`git checkout -b feature/amazing-feature`)
+- Commit your changes (`git commit -m 'Add amazing feature'`)
+- Push to the branch (`git push origin feature/amazing-feature`)
+- Open a Pull Request
+
+---
+
+## 📄 License
 
 MIT © [Nextbridge](https://nextbridge.com)
+
+---
+
+## 🔗 Links
+
+- [npm Package](https://www.npmjs.com/package/@nextbridgehq/payload-block-builder)
+- [GitHub Repository](https://github.com/nextbridgehq/block-builder)
+- [Report a Bug](https://github.com/nextbridgehq/block-builder/issues)
+- [Payload CMS](https://payloadcms.com)
+
+Built with ❤️ by Nextbridge