Migrate Contentful to PayloadCMS with a single prompt

# Migrate my blog from Contentful to PayloadCMS v3

## Context

I have a Next.js (App Router) project with blog content currently in Contentful.
I want to migrate to PayloadCMS v3, self-hosted in the same Next.js app.

My stack:

- Database: [postgres | sqlite | mongodb] (I used PostgreSQL with @payloadcms/db-postgres)
- Storage: [vercel-blob | s3 | local] (I used Vercel Blob with @payloadcms/storage-vercel-blob)
- Package manager: [pnpm | npm | yarn]

---

## Section A: PayloadCMS Setup

### 1. Install Payload v3

Install these packages:

- `payload` (core)
- `@payloadcms/next` (Next.js integration)
- `@payloadcms/richtext-lexical` (Lexical editor)
- `@payloadcms/db-[your-adapter]` (database adapter)
- `@payloadcms/storage-[your-provider]` (file storage — optional if using local disk)
- `sharp` (image processing)
- `lexical` (Lexical type definitions)

### 2. Create `payload.config.ts`

Configure Payload with:

- PostgreSQL adapter (or your chosen DB) using `DATABASE_URL` env var
- Lexical editor as the default editor
- Storage plugin for media uploads using `BLOB_READ_WRITE_TOKEN` env var (if using Vercel Blob)
- `sharp` for image processing
- Collections: Users, Posts, Media (defined below)

### 3. Define collections

[Adapt this prompt together with your agent, give it your contentful models as input!]

[The collections I made based on my contentful schema:]

**Users** (`src/collections/Users.ts`):

- slug: `users`
- auth: true (enables Payload authentication)
- fields: `name` (text)
- Use as admin title: `email`

**Media** (`src/collections/Media.ts`):

- slug: `media`
- read access: public (`() => true`)
- upload config:
  - mimeTypes: `['image/*']`
  - imageSizes: `thumbnail` (400×300), `card` (768×1024), both with `position: 'centre'`
  - focalPoint: true
  - crop: true
- fields: `alt` (text, required)

**Posts** (`src/collections/Posts.ts`):

- slug: `posts`
- read access: public
- versions with drafts enabled
- admin: useAsTitle `title`, default columns: title, slug, publicationDate, _status
- fields:
  - `title` (text, required)
  - `slug` (text, required, unique, indexed, kebab-case validation)
  - `description` (textarea, required, maxLength 150)
  - `publicationDate` (date, required)
  - `featuredImage` (upload, relationTo `media`)
  - `tags` (text, hasMany: true)
  - `canonicalUrl` (text, optional, URL validation)
  - `content` (richText, required, Lexical editor with BlocksFeature containing CodeBlock)

**CodeBlock** (`src/collections/blocks/CodeBlock.ts`):

- slug: `codeBlock`
- fields:
  - `language` (text, required — e.g., typescript, python, mermaid)
  - `code` (code field, required)

### 4. Route groups

Separate the Payload admin panel from your site layout using Next.js route groups:

- Move site pages into `src/app/(site)/`
- Put Payload admin at `src/app/(payload)/admin/`

This prevents the admin panel from inheriting your site's Header, Footer,
i18n providers, and global CSS.

### 5. Next.js config

- Wrap your `next.config.js` with `withPayload` from `@payloadcms/next/withPayload`
- Add your storage provider's domain to `images.remotePatterns`

---

## Section B: Contentful Rich Text → Lexical AST Transformation

This is the hardest part of the migration. Contentful's Rich Text uses its own AST
format. Payload uses Lexical's AST. You need a pure function that transforms one to
the other.

### The transformation function

Create `src/lib/contentful-to-lexical.ts` — a pure, deterministic transformer
with zero side effects. It takes a `warn` callback for unknown node types
instead of using `console.warn` directly (makes it testable).

### Node type mapping table

| Contentful `nodeType`           | Lexical `type`   | Extra fields                                                           |
| ------------------------------- | ---------------- | ---------------------------------------------------------------------- |
| `text`                          | `text`           | `text: node.value ?? ''`, `format: computeFormat(node.marks ?? [])`    |
| `paragraph`                     | `paragraph`      | `children: transformChildren(node.content)`                            |
| `heading-1` through `heading-6` | `heading`        | `tag: 'h1'` through `'h6'`                                            |
| `ordered-list`                  | `list`           | `listType: 'number'`                                                   |
| `unordered-list`                | `list`           | `listType: 'bullet'`                                                   |
| `list-item`                     | `listitem`       | `children: transformChildren(node.content)`                            |
| `blockquote`                    | `quote`          | `children: transformChildren(node.content)`                            |
| `hr`                            | `horizontalrule` | leaf node — only `type` and `version`, no children/direction/format    |
| `hyperlink`                     | `link`           | `fields: { url: node.data.uri }`                                      |
| `entry-hyperlink`               | `link`           | `fields: { url: node.data.uri }`                                      |
| `asset-hyperlink`               | `link`           | `fields: { url: node.data.uri }`                                      |
| `embedded-entry-block`          | resolve from linked entries map — see below                                       |

### Text format bitmask

Contentful marks (bold, italic, etc.) map to a Lexical format bitmask:

| Mark            | Bitmask value |
| --------------- | ------------- |
| `bold`          | 1             |
| `italic`        | 2             |
| `strikethrough` | 4             |
| `underline`     | 8             |
| `code`          | 16            |
| `subscript`     | 32            |
| `superscript`   | 64            |

Combine with bitwise OR. A bold+italic node has format `3` (1 | 2).

### Required fields on every Lexical element node

Every element node (paragraph, heading, list, quote, link, etc.) MUST include:

- `type` — the node type string
- `version: 1` — always 1 (except `block` nodes which use version 2)
- `direction: null`
- `format: ''`
- `indent: 0`
- `children` — array of child nodes

**Exceptions:** `text` nodes only need `type`, `version: 1`, `text`, and `format` (the bitmask number). `horizontalrule` is a leaf node — it only needs `type` and `version: 1`.

### Handling embedded entries (code blocks)

Contentful stores embedded entries as references. To resolve them:

1. Build a `LinkedEntriesMap` (Map<string, LinkedEntry>) from the Contentful
   response's `includes.Entry` array
2. When you hit an `embedded-entry-block` node, look up the entry by
   `node.data.target.sys.id` in the map
3. If the linked entry's `contentTypeId` is `codeBlock`, emit a Lexical `block` node:

```typescript
{
  type: 'block',
  fields: {
    id: randomBytes(12).toString('hex'),
    blockName: '',
    blockType: 'codeBlock',
    language: (linkedEntry.fields['programmingLanguage'] as string) ?? '',
    code: (linkedEntry.fields['code'] as string) ?? '',
  },
  children: [],
  direction: null,
  format: '',
  indent: 0,
  version: 2,  // block nodes use version 2, not 1
}
```

4. For unknown content types, call `warn()` and return null

### The root wrapper

The top-level output must be a Lexical `root` node:

```typescript
{
  root: {
    type: 'root',
    children: [...transformed top-level nodes],
    direction: null,
    format: '',
    indent: 0,
    version: 1,
  }
}
```

### Link fallback behavior

If a `hyperlink`/`entry-hyperlink`/`asset-hyperlink` node is missing a `uri`,
warn and return the first child node as plain text if there's exactly one child.
If there are zero or multiple children, return null (drop the node).

---

## Section C: Migration Script

Create an idempotent migration script at `scripts/migrate-contentful-to-payload.ts`.

### Environment variables

- `DATABASE_URL` — PostgreSQL connection string (or your DB)
- `PAYLOAD_SECRET` — Payload secret key
- `CONTENTFUL_SPACE_ID` — your Contentful space ID
- `CONTENTFUL_ACCESS_TOKEN` — Content Delivery API token
- `CONTENTFUL_ENVIRONMENT` — Contentful environment (default: `master`)
- `CONTENTFUL_CONTENT_TYPE` — content type to migrate (default: `blogPost`)
- `CONTENTFUL_USE_PREVIEW` — set to `true` to include drafts
- `CONTENTFUL_PREVIEW_ACCESS_TOKEN` — Preview API token (required when using preview)

### Migration steps

1. **Connect** to both Contentful (via `contentful` SDK) and Payload (via `getPayload`)
2. **Fetch all entries** for the content type with `include: 10` (resolves nested references)
3. **Build the linked entries map** from `response.includes.Entry`
4. **For each post:**
   a. **Idempotency check** — query Payload for existing post with the same slug. Skip if found.
   b. **Upload featured image** — download from Contentful's CDN, upload to Payload's media collection
   c. **Transform rich text** — run the Contentful document through `transformRichText()`
   d. **Create post** in Payload with `draft: true` so you can review before publishing
5. **Print summary** — total, success, skipped, errors

### Important details

- Contentful image URLs may start with `//` — prepend `https:` if so
- Use the image's `description` field as alt text, falling back to `title`
- Handle unresolved Contentful links (missing `.fields`) gracefully — warn and skip
- Set `_status: 'published'` in the post data but pass `draft: true` to `payload.create()`
  so posts are created as reviewable drafts

### Running the script

```bash
DATABASE_URL="..." PAYLOAD_SECRET="..." \
CONTENTFUL_SPACE_ID="..." CONTENTFUL_ACCESS_TOKEN="..." \
npx ts-node scripts/migrate-contentful-to-payload.ts
```

Or build an admin UI page at `/admin/migrate` using Payload's server actions
for a more user-friendly experience.