@nitrogenbuilder/connector-payload 0.1.10 → 0.1.12

package/README.md

@@ -1,39 +1,39 @@
-# Nitrogen Connector Payload
+# @nitrogenbuilder/connector-payload
 
-A Payload CMS plugin for visual page building with Nitrogen.
+Payload CMS 3.x plugin for visual page building with Nitrogen.
 
-## Setup
-
-This project uses the `nitrogen-connector-payload` plugin for visual page building with Nitrogen. Here's how to install it in a fresh Payload CMS project:
-
-### 1. Install Dependencies
+## Install
 
 ```bash
-pnpm add nitrogen-connector-payload //This is not done yet. It's dev only for now.
-pnpm add @nitrogenbuilder/client-react @nitrogenbuilder/client-core @nitrogenbuilder/types
+pnpm add @nitrogenbuilder/connector-payload
 ```
 
-### 2. Add Plugin to Payload Config
+## Setup
 
-In your `src/plugins/index.ts` (or wherever you configure plugins):
+### 1. Add the plugin to your Payload config
 
 ```ts
-import { nitrogenConnectorPlugin } from "nitrogen-connector-payload"; //This is not done yet. For Dev: "link:../nitrogen-connector-payload"
-
-export const plugins: Plugin[] = [
-  nitrogenConnectorPlugin({
-    collections: ["pages", "posts"], // Collections to enable Nitrogen editing on
-  }),
-  // ... other plugins
-];
+import { nitrogenConnectorPlugin } from '@nitrogenbuilder/connector-payload'
+
+export default buildConfig({
+  plugins: [
+    nitrogenConnectorPlugin({
+      collections: ['pages', 'posts'], // collections to enable Nitrogen editing on
+    }),
+  ],
+})
 ```
 
-### 3. Wrap Your Page Routes
+The plugin automatically:
+- Injects `nitrogenData` and `pageSettings` JSON fields into each collection
+- Adds an "Edit in Nitrogen" button to each document in the Payload admin
+- Registers the `NitrogenTemplates` collection and `NitrogenSettings` global
+- Creates all required API endpoints under `/api/nitrogen/v1/`
 
-In your page route files (e.g., `src/app/(frontend)/[slug]/page.tsx`), wrap your content with `NitrogenWrapper`:
+### 2. Wrap your page routes
 
 ```tsx
-import { NitrogenWrapper } from 'nitrogen-connector-payload/frontend'
+import { NitrogenWrapper } from '@nitrogenbuilder/connector-payload/frontend'
 
 export default async function Page({ params, searchParams }) {
   const page = await queryPage(...)
@@ -41,7 +41,6 @@ export default async function Page({ params, searchParams }) {
 
   return (
     <NitrogenWrapper page={page} searchParams={search} collection="pages">
-      {/* Your regular page content */}
       <RenderHero {...page.hero} />
       <RenderBlocks blocks={page.layout} />
     </NitrogenWrapper>
@@ -49,53 +48,66 @@ export default async function Page({ params, searchParams }) {
 }
 ```
 
-That's it! The `NitrogenWrapper` component automatically:
-
-- Detects when the Nitrogen editor is requesting the page (via `?nitrogen-builder` query param)
-- Checks if the page has Nitrogen data
-- Renders the Nitrogen visual builder when needed, otherwise renders your regular content
+`NitrogenWrapper` detects when the Nitrogen editor is loading the page (via `?nitrogen-builder` query param) and renders the visual builder. Otherwise it renders your normal content.
 
-### Adding Custom Components
+### 3. Register components
 
-To register custom Nitrogen components, create a client component:
+Create a client component that registers your Nitrogen components:
 
 ```tsx
 // src/components/NitrogenComponents.tsx
 "use client";
 
-import { nitrogen } from "nitrogen-connector-payload/frontend";
-import type {
-  ComponentSettings,
-  ComponentSettingsToProps,
-} from "nitrogen-connector-payload/frontend";
-import MyComponent from "./MyComponent";
+import { nitrogen } from '@nitrogenbuilder/connector-payload'
+import type { ComponentSettings, ComponentSettingsToProps } from '@nitrogenbuilder/connector-payload'
+import MyComponent from './MyComponent'
 
 const myComponentSettings = {
   categories: {
     content: {
-      label: "Content",
+      label: 'Content',
       groups: {
         content: {
-          label: "Content",
+          label: 'Content',
           props: {
-            title: { type: "string", default: "Hello" },
+            title: { type: 'string', default: 'Hello' },
           },
         },
       },
     },
   },
-} as const satisfies ComponentSettings;
+} as const satisfies ComponentSettings
 
-// Register on module load
-nitrogen.registerModule("my-component", MyComponent, myComponentSettings);
+nitrogen.registerModule('my-component', MyComponent, myComponentSettings)
 
-export {};
+export {}
 ```
 
 Then import it in your page route:
 
 ```tsx
-import "@/components/NitrogenComponents";
+import '@/components/NitrogenComponents'
 ```
 
----
+## Plugin Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `collections` | `string[]` | Slugs of existing Payload collections to enable Nitrogen editing on |
+| `disabled` | `boolean` | Disable the plugin without removing it from config |
+
+## Exports
+
+| Export | Description |
+|--------|-------------|
+| `nitrogenConnectorPlugin` | The Payload plugin |
+| `NitrogenWrapper` | Frontend wrapper component (from `/frontend`) |
+| `NitrogenPageClient` | Low-level client component (from `/frontend`) |
+| `nitrogen` | Re-export of `@nitrogenbuilder/client-core` |
+| `ComponentSettings` | Type for component settings definitions |
+| `ComponentSettingsToProps` | Type helper to derive props from settings |
+| `NitrogenEditButton` | Admin UI button component |
+| `NitrogenViewButton` | Admin UI view button component |
+| `createCollectionEndpoints` | Factory for generating collection API endpoints |
+| `buildDynamicData` | Helper for building dynamic data in page routes |
+| `getNitrogenSettings` | Helper for fetching Nitrogen global settings |

package/dist/collections/NitrogenTemplates.js

@@ -3,6 +3,7 @@ export const NitrogenTemplates = {
     admin: {
         useAsTitle: 'title',
         defaultColumns: ['title', 'associatedCollection', 'updatedAt'],
+        group: 'Nitrogen',
         components: {
             edit: {
                 beforeDocumentControls: [

package/dist/endpoints/collection-picker.d.ts

@@ -0,0 +1,2 @@
+import type { Endpoint } from 'payload';
+export declare const collectionPickerEndpoints: Endpoint[];

package/dist/endpoints/collection-picker.js

@@ -0,0 +1,52 @@
+export const collectionPickerEndpoints = [
+    // GET /api/nitrogen/v1/collection/:slug
+    // Generic read-only endpoint for fetching any collection's documents for use
+    // in the nitrogen editor's CtrlRelationship control.
+    {
+        path: '/nitrogen/v1/collection/:slug',
+        method: 'get',
+        handler: async (req) => {
+            const { payload, routeParams } = req;
+            const collectionSlug = routeParams?.slug;
+            if (!collectionSlug) {
+                return Response.json({ error: 'Collection slug is required' }, { status: 400 });
+            }
+            const url = new URL(req.url || '', 'http://localhost');
+            const search = url.searchParams.get('search') || '';
+            const page = parseInt(url.searchParams.get('page') || '1', 10);
+            const limit = parseInt(url.searchParams.get('limit') || '50', 10);
+            const depth = parseInt(url.searchParams.get('depth') || '1', 10);
+            try {
+                const where = {};
+                if (search) {
+                    where['or'] = [
+                        { title: { contains: search } },
+                        { name: { contains: search } },
+                    ];
+                }
+                const result = await payload.find({
+                    collection: collectionSlug,
+                    where,
+                    page,
+                    limit,
+                    depth,
+                    overrideAccess: false,
+                    req,
+                });
+                return Response.json({
+                    docs: result.docs,
+                    totalDocs: result.totalDocs,
+                    totalPages: result.totalPages,
+                    page: result.page,
+                });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                if (message.includes('not found') || message.includes('Unknown collection')) {
+                    return Response.json({ error: `Collection "${collectionSlug}" not found` }, { status: 404 });
+                }
+                return Response.json({ error: message }, { status: 500 });
+            }
+        },
+    },
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitrogenbuilder/connector-payload",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Nitrogen page builder connector plugin for Payload CMS 3.x",
   "author": "Leonardo Dentzien <leo@torchmedia.ca>",
   "type": "module",
@@ -24,11 +24,6 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "build": "tsc",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "pnpm build"
-  },
   "peerDependencies": {
     "payload": "^3.0.0",
     "next": "^15.0.0",
@@ -45,5 +40,9 @@
     "@nitrogenbuilder/client-react": "link:../monogen/packages/client-react",
     "@nitrogenbuilder/client-core": "link:../monogen/packages/client-core",
     "@nitrogenbuilder/types": "link:../monogen/packages/types"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
   }
-}
+}