# @nitrogenbuilder/connector-payload

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

## Install

```bash
pnpm add @nitrogenbuilder/connector-payload
```

## Setup

### 1. Add the plugin to your Payload config

```ts
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

```tsx
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:

```tsx
// 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:

```tsx
import '@/components/NitrogenComponents'
```

## Plugin Options

| Option | Type | Description |
|--------|------|-------------|
| `collections` | `string[]` | Slugs of existing Payload collections to enable Nitrogen editing on |
| `collectionRoutes` | `Record<string, string>` | Canonical public route patterns used by list and slug responses |
| `editorPreviewRoute` | `string` | Optional private iframe route for collection-by-ID editing; must contain `[collection]` and `[id]` |
| `disabled` | `boolean` | Disable the plugin without removing it from config |

Use an authenticated preview route when drafts and published documents should
share the same editor iframe target:

```ts
nitrogenConnectorPlugin({
  collections: ["pages", "posts"],
  editorPreviewRoute: "/preview/[collection]/[id]",
})
```

This affects collection-by-ID editor responses only. Public list and slug
responses keep their canonical `collectionRoutes` URLs, and Header/Footer
templates continue to preview through `/nitrogen-templates/[slug]`.

## 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 |