@nitrogenbuilder/connector-payload

Payload CMS 3.x plugin for visual page building with Nitrogen.

Install

pnpm add @nitrogenbuilder/connector-payload

Setup

1. Add the plugin to your Payload config

import { nitrogenConnectorPlugin } from '@nitrogenbuilder/connector-payload'

export default buildConfig({
  plugins: [
    nitrogenConnectorPlugin({
      collections: ['pages', 'posts'], // collections to enable Nitrogen editing on
    }),
  ],
})

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/

2. Wrap your page routes

import { NitrogenWrapper } from '@nitrogenbuilder/connector-payload/frontend'

export default async function Page({ params, searchParams }) {
  const page = await queryPage(...)
  const search = await searchParams

  return (
    <NitrogenWrapper page={page} searchParams={search} collection="pages">
      <RenderHero {...page.hero} />
      <RenderBlocks blocks={page.layout} />
    </NitrogenWrapper>
  )
}

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.

3. Register components

Create a client component that registers your Nitrogen components:

// src/components/NitrogenComponents.tsx
"use client";

import { nitrogen } from '@nitrogenbuilder/connector-payload'
import type { ComponentSettings, ComponentSettingsToProps } from '@nitrogenbuilder/connector-payload'
import MyComponent from './MyComponent'

const myComponentSettings = {
  categories: {
    content: {
      label: 'Content',
      groups: {
        content: {
          label: 'Content',
          props: {
            title: { type: 'string', default: 'Hello' },
          },
        },
      },
    },
  },
} as const satisfies ComponentSettings

nitrogen.registerModule('my-component', MyComponent, myComponentSettings)

export {}

Then import it in your page route:

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 |