npm - @nextbridgehq/payload-block-builder - Versions diffs - 0.1.6 → 0.1.8 - Mend

@nextbridgehq/payload-block-builder 0.1.6 → 0.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md CHANGED Viewed

@@ -1,5 +1,8 @@
 # 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.
+---
 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.
@@ -11,15 +14,64 @@ A visual block builder plugin for Payload v3. Design your content blocks through
 - **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.
+## Database compatibility
+Works with all Payload-supported databases — no direct SQL, no database-specific code:
+| Database | Adapter |
+|---|---|
+| PostgreSQL / Supabase / Neon | `@payloadcms/db-postgres` |
+| SQLite / Turso / LibSQL | `@payloadcms/db-sqlite` |
+| MongoDB | `@payloadcms/db-mongodb` |
+---
 ## Quick start
-1. Install the plugin:
+### Option A — Automatic setup (recommended)
+Install the package and run the init command from your project root:
+```bash
+pnpm add @nextbridgehq/payload-block-builder
+# or: npm install @nextbridgehq/payload-block-builder
+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
+Then regenerate the import map and start your dev server:
 ```bash
-npm install @nextbridgehq/payload-block-builder
+pnpm generate:importmap
+pnpm dev
 ```
-2. Add the plugin to your `payload.config.ts`:
+Visit `http://localhost:3000/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:
+> ```bash
+> pnpm payload migrate:create --name=add_block_builder
+> pnpm payload migrate
+> ```
+---
+### Option B — Manual setup
+**1. Install:**
+```bash
+pnpm add @nextbridgehq/payload-block-builder
+```
+**2. Add the plugin to `payload.config.ts`:**
 ```ts
 import { dynamicBlocksPlugin } from '@nextbridgehq/payload-block-builder'
@@ -27,36 +79,85 @@ import { dynamicBlocksPlugin } from '@nextbridgehq/payload-block-builder'
 export default buildConfig({
   plugins: [
     dynamicBlocksPlugin({
-      collections: ['pages', 'posts'],
+      collections: ['pages'],
     }),
   ],
 })
 ```
-3. Create a page in your Next.js app to host the builder UI:
+**3. Create `src/app/block-builder/layout.tsx`:**
+```tsx
+import React from 'react'
+import { headers } from 'next/headers'
+import { redirect } from 'next/navigation'
+import { getPayload } from 'payload'
+import config from '@payload-config'
+import '@nextbridgehq/payload-block-builder/builder.css'
+export const metadata = { title: 'Block Builder' }
+export default async function BlockBuilderLayout({ children }: { children: React.ReactNode }) {
+  const payload = await getPayload({ config })
+  const { user } = await payload.auth({ headers: await headers() })
+  if (!user) redirect('/admin/login')
+  return (
+    <html lang="en">
+      <body style={{ margin: 0, padding: 0, height: '100vh', overflow: 'hidden' }}>
+        {children}
+      </body>
+    </html>
+  )
+}
+```
+**4. Create `src/app/block-builder/page.tsx`:**
 ```tsx
-// app/block-builder/page.tsx
 'use client'
 import { BuilderShell } from '@nextbridgehq/payload-block-builder/client'
-import '@nextbridgehq/payload-block-builder/builder.css'
 export default function BlockBuilderPage() {
   return <BuilderShell />
 }
 ```
-4. If you're on a SQL database, run the migration:
+**5. Add admin field styles to `src/app/(payload)/custom.scss`:**
+```scss
+@import '@nextbridgehq/payload-block-builder/block-data-field.css';
+@import '@nextbridgehq/payload-block-builder/schema-builder-field.css';
+```
+**6. Regenerate the import map and start the dev server:**
 ```bash
-npx payload migrate:create
-npx payload migrate:run
+pnpm generate:importmap
+pnpm dev
 ```
-MongoDB users can skip this step.
+---
+## Plugin options
-Visit `/block-builder` in your browser and you're in.
+```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'
+})
+```
+The `--collections` flag is also supported in the init command:
+```bash
+npx payload-block-builder init --collections=pages,posts
+```
+---
 ## Usage
@@ -66,16 +167,16 @@ Visit `/block-builder` in your browser and you're in.
 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. Hit Publish. The block 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
-Any collection you listed in `collections` gets a new "DB Layout" tab in the Payload admin. Editors can:
+Any collection listed in the `collections` option gets a new "DB Layout" tab in the Payload admin. Editors can:
-1. Click "Add Row" to add a block.
+1. Click "Add Row" to add a block instance.
 2. Select a block definition and the version of its schema to use.
-3. Fill in the fields. They render dynamically based on the selected schema.
-4. Reorder, hide, or add anchor IDs to individual blocks.
+3. Fill in the fields — they render dynamically based on the selected schema.
+4. Reorder, hide, or add anchor IDs to individual block instances.
 5. Save the document as normal.
 ### Reading block data on the frontend
@@ -91,29 +192,74 @@ for (const block of page.dbLayout) {
 }
 ```
-From there it's just a switch or a component map. Render each block type however you like.
+Render each block type however you like — a switch statement or a component map both work well.
+---
+## How it works
+- **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
+These field types are available in the block builder and render correctly in the admin field UI:
+| 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 |
+---
+## Using `dbLayoutField` directly
-## Options
+If you prefer not to use the plugin's `collections` option, you can add the layout tab manually to any collection:
 ```ts
-dynamicBlocksPlugin({
-  enabled?: boolean      // disable without removing. Default: true
-  collections?: string[] // which collection slugs 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. Default: 'DB Layout'
-})
+import { dbLayoutField } from '@nextbridgehq/payload-block-builder'
+export const Pages: CollectionConfig = {
+  slug: 'pages',
+  fields: [
+    {
+      type: 'tabs',
+      tabs: [
+        { label: 'Content', fields: [] },
+        dbLayoutField(),                         // fieldName='dbLayout', tab label='DB Layout'
+        dbLayoutField('heroBlocks', 'Hero'),     // custom field name and tab label
+      ],
+    },
+  ],
+}
 ```
-## How it works
+---
+## CSS imports reference
+| Import path | Purpose |
+|---|---|
+| `@nextbridgehq/payload-block-builder/builder.css` | Block Builder UI page styles |
+| `@nextbridgehq/payload-block-builder/block-data-field.css` | DB Layout field styles in admin |
+| `@nextbridgehq/payload-block-builder/schema-builder-field.css` | Schema Builder field styles in admin |
-- **Block definitions** are stored in a `block-definitions` collection. Each document is a named block type with a slug, labels, and a list of field definitions.
-- **Versions** are stored in a `block-definition-versions` collection. Every time you publish a block in the builder, a snapshot of its current schema is saved as a new version.
-- **Documents** in your opted-in collections store a reference to the exact block version they were built against, so updating a block's schema later won't break existing content.
-- **The DB Layout tab** is injected automatically on each collection you list. It renders a dynamic array field where editors pick a block and version, and the field data UI adjusts to match the selected schema.
-- **Four internal API endpoints** power the builder UI and the `BlockDataField` admin component. You don't need to call them yourself.
+---
-## Requirements
+## License
-- Payload v3
-- Next.js 14+
-- Any Payload-supported database (PostgreSQL, MongoDB, SQLite)
+MIT © [Nextbridge](https://nextbridge.com)

package/dist/bin/init.js CHANGED Viewed

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-#!/usr/bin/env node
 // src/bin/init.ts
 import fs from "fs";
@@ -13,13 +12,21 @@ export default function BlockBuilderPage() {
 }
 `;
 var LAYOUT_CONTENT = `import React from 'react'
+import { headers } from 'next/headers'
+import { redirect } from 'next/navigation'
+import { getPayload } from 'payload'
+import config from '@payload-config'
 import '@nextbridgehq/payload-block-builder/builder.css'
 export const metadata = {
   title: 'Block Builder',
 }
-export default function BlockBuilderLayout({ children }: { children: React.ReactNode }) {
+export default async function BlockBuilderLayout({ children }: { children: React.ReactNode }) {
+  const payload = await getPayload({ config })
+  const { user } = await payload.auth({ headers: await headers() })
+  if (!user) redirect('/admin/login')
   return (
     <html lang="en">
       <body style={{ margin: 0, padding: 0, height: '100vh', overflow: 'hidden' }}>
@@ -76,7 +83,7 @@ function addImport(content) {
   while ((m = lastFromRegex.exec(content)) !== null) lastMatch = m;
   if (!lastMatch) return newImport + "\n" + content;
   const insertPos = lastMatch.index + lastMatch[0].length;
-  return content.slice(0, insertPos) + "\n" + newImport + content.slice(insertPos);
+  return content.slice(0, insertPos) + "\n" + newImport + "\n" + content.slice(insertPos);
 }
 function insertIntoPluginsArray(content, collectionsArg) {
   const pluginsMatch = /\bplugins\s*:\s*\[/.exec(content);
@@ -84,13 +91,19 @@ function insertIntoPluginsArray(content, collectionsArg) {
   const openPos = content.indexOf("[", pluginsMatch.index);
   const closePos = findClosingBracket(content, openPos);
   if (closePos === -1) return null;
+  const beforePlugins = content.slice(0, pluginsMatch.index);
+  const pluginsLineStart = beforePlugins.lastIndexOf("\n") + 1;
+  const outerIndent = content.slice(pluginsLineStart, pluginsMatch.index).match(/^([ \t]*)/)?.[1] ?? "  ";
+  const entryIndent = outerIndent + "  ";
   const beforeClose = content.slice(0, closePos);
   const prevNL = beforeClose.lastIndexOf("\n");
-  const closingIndent = beforeClose.slice(prevNL + 1).match(/^([ \t]*)/)?.[1] ?? "  ";
-  const entryIndent = closingIndent + "  ";
-  const newLine = `${entryIndent}dynamicBlocksPlugin({ collections: [${collectionsArg}] }),
-`;
-  return content.slice(0, prevNL + 1) + newLine + content.slice(prevNL + 1);
+  const isSingleLine = prevNL < openPos;
+  const newEntry = `${entryIndent}dynamicBlocksPlugin({ collections: [${collectionsArg}] }),`;
+  if (isSingleLine) {
+    return content.slice(0, openPos + 1) + "\n" + newEntry + "\n" + outerIndent + content.slice(closePos);
+  } else {
+    return content.slice(0, prevNL + 1) + newEntry + "\n" + content.slice(prevNL + 1);
+  }
 }
 function injectPluginsBlock(content, collectionsArg) {
   const collMatch = /\bcollections\s*:\s*\[/.exec(content);
@@ -110,7 +123,13 @@ ${outerIndent}],`;
   return content.slice(0, afterCollLine) + "\n" + pluginsBlock + content.slice(afterCollLine);
 }
 function modifyPayloadConfig(configPath, collectionsArg) {
-  let content = fs.readFileSync(configPath, "utf8");
+  let content;
+  try {
+    content = fs.readFileSync(configPath, "utf8");
+  } catch (err) {
+    console.error(`Error: Could not read ${configPath}: ${err.message}`);
+    process.exit(1);
+  }
   if (content.includes("dynamicBlocksPlugin")) {
     console.log(`Skipped: dynamicBlocksPlugin already present in ${configPath}`);
     return;
@@ -119,8 +138,16 @@ function modifyPayloadConfig(configPath, collectionsArg) {
   const noComments = content.replace(/\/\/[^\n]*/g, "");
   const hasPluginsArray = /\bplugins\s*:\s*\[/.test(noComments);
   const hasPluginsShorthand = /^\s*plugins\s*,/m.test(noComments);
+  function writeConfig(data) {
+    try {
+      fs.writeFileSync(configPath, data, "utf8");
+    } catch (err) {
+      console.error(`Error: Could not write ${configPath}: ${err.message}`);
+      process.exit(1);
+    }
+  }
   if (hasPluginsShorthand && !hasPluginsArray) {
-    fs.writeFileSync(configPath, content, "utf8");
+    writeConfig(content);
     console.log(`Updated: ${configPath} (added import)`);
     console.log(`  Note: 'plugins' is imported from another file.`);
     console.log(`  Add dynamicBlocksPlugin({ collections: ['pages'] }) to that file manually.`);
@@ -133,13 +160,13 @@ function modifyPayloadConfig(configPath, collectionsArg) {
     result = injectPluginsBlock(content, collectionsArg);
   }
   if (result === null) {
-    fs.writeFileSync(configPath, content, "utf8");
+    writeConfig(content);
     console.log(`Updated: ${configPath} (added import only)`);
     console.log(`  Could not auto-detect plugins array. Add manually:`);
     console.log(`  plugins: [ dynamicBlocksPlugin({ collections: [${collectionsArg}] }) ]`);
     return;
   }
-  fs.writeFileSync(configPath, result, "utf8");
+  writeConfig(result);
   console.log(`Updated: ${configPath} (added dynamicBlocksPlugin)`);
 }
 function printNextSteps(dbAdapter) {
@@ -165,7 +192,14 @@ function printNextSteps(dbAdapter) {
 function main() {
   const args = process.argv.slice(2);
   const collectionsFlag = args.find((a) => a.startsWith("--collections="));
-  const collectionsValue = collectionsFlag ? collectionsFlag.replace("--collections=", "").split(",").map((s) => s.trim()) : ["pages"];
+  const rawCollections = collectionsFlag ? collectionsFlag.replace("--collections=", "").split(",").map((s) => s.trim()) : ["pages"];
+  const invalidSlugs = rawCollections.filter((c) => !/^[a-z0-9_-]+$/i.test(c));
+  if (invalidSlugs.length > 0) {
+    console.error(`Error: Invalid collection slug(s): ${invalidSlugs.join(", ")}`);
+    console.error("Collection slugs may only contain letters, numbers, hyphens, and underscores.");
+    process.exit(1);
+  }
+  const collectionsValue = rawCollections;
   const collectionsArg = collectionsValue.map((c) => `'${c}'`).join(", ");
   const appDir = findAppDir();
   if (!appDir) {
@@ -173,32 +207,52 @@ function main() {
     process.exit(1);
   }
   const builderDir = path.join(appDir, "block-builder");
-  if (!fs.existsSync(builderDir)) {
-    fs.mkdirSync(builderDir, { recursive: true });
+  try {
+    if (!fs.existsSync(builderDir)) {
+      fs.mkdirSync(builderDir, { recursive: true });
+    }
+  } catch (err) {
+    console.error(`Error: Could not create directory ${builderDir}: ${err.message}`);
+    process.exit(1);
   }
   const pagePath = path.join(builderDir, "page.tsx");
   const layoutPath = path.join(builderDir, "layout.tsx");
   if (fs.existsSync(pagePath)) {
     console.log(`Skipped: ${pagePath} already exists`);
   } else {
-    fs.writeFileSync(pagePath, PAGE_CONTENT);
-    console.log(`Created: ${pagePath}`);
+    try {
+      fs.writeFileSync(pagePath, PAGE_CONTENT);
+      console.log(`Created: ${pagePath}`);
+    } catch (err) {
+      console.error(`Error: Could not write ${pagePath}: ${err.message}`);
+      process.exit(1);
+    }
   }
   if (fs.existsSync(layoutPath)) {
     console.log(`Skipped: ${layoutPath} already exists`);
   } else {
-    fs.writeFileSync(layoutPath, LAYOUT_CONTENT);
-    console.log(`Created: ${layoutPath}`);
+    try {
+      fs.writeFileSync(layoutPath, LAYOUT_CONTENT);
+      console.log(`Created: ${layoutPath}`);
+    } catch (err) {
+      console.error(`Error: Could not write ${layoutPath}: ${err.message}`);
+      process.exit(1);
+    }
   }
   const payloadRouteDir = path.join(appDir, "(payload)");
   const customScssPath = path.join(payloadRouteDir, "custom.scss");
   if (fs.existsSync(customScssPath)) {
-    const existing = fs.readFileSync(customScssPath, "utf8");
-    if (!existing.includes("@nextbridgehq/payload-block-builder")) {
-      fs.appendFileSync(customScssPath, "\n" + CUSTOM_SCSS_IMPORTS);
-      console.log(`Updated: ${customScssPath} (added admin field styles)`);
-    } else {
-      console.log(`Skipped: ${customScssPath} already has block-builder imports`);
+    try {
+      const existing = fs.readFileSync(customScssPath, "utf8");
+      if (!existing.includes("@nextbridgehq/payload-block-builder")) {
+        fs.appendFileSync(customScssPath, "\n" + CUSTOM_SCSS_IMPORTS);
+        console.log(`Updated: ${customScssPath} (added admin field styles)`);
+      } else {
+        console.log(`Skipped: ${customScssPath} already has block-builder imports`);
+      }
+    } catch (err) {
+      console.error(`Error: Could not update ${customScssPath}: ${err.message}`);
+      process.exit(1);
     }
   }
   const configPath = findPayloadConfig();