# How to Migrate from Payload CMS to BCMS

[Payload CMS](https://www.thebcms.com/compare/payload-alternative.md) is still one of the strongest choices for TypeScript teams that want their CMS, backend, and application code tightly integrated. But after the Payload team joined Figma and new Payload Cloud deployments were paused, teams evaluating Payload for new projects have a different question to answer: Do they want to operate Payload themselves, or move to a [managed headless CMS](https://www.thebcms.com/blog/hosted-saas-headless-cms.md)?

Whether you actually need to leave Payload, and how to move content without breaking production. This guide covers a reproducible TypeScript migration pipeline you can adapt to a real project.

## What changed after Figma acquired Payload?

On June 17, 2025, [Figma announced that the Payload team](https://www.figma.com/blog/payload-joins-figma/) had joined the company. Payload remains open source under the MIT license, the team continues to run the project, and self-hosting remains supported. Figma frames the move as closing the gap between design and production.

This does not mean Payload stopped working. On [Payload's Cloud update page](https://payloadcms.com/login): Deployment of new projects is currently paused, while existing Cloud projects continue running as normal. Existing Cloud customers will eventually migrate to a future replacement product.

## Do you actually need to migrate from Payload CMS?

No, not by default. Stay on Payload if your team wants schema-as-code, self-hosting, direct database ownership, and a CMS embedded in your Next.js application.

Consider migration if you want a managed headless CMS, visual content modeling, framework-independent delivery, or a hosted editorial workflow without operating database and CMS infrastructure yourself.

## Why developers are looking for Payload CMS alternatives

### Code-first content modeling

Payload automatically generates an Admin Panel so that editors can manage content through the UI. The distinction: Developers primarily own schema changes: new collections, fields, and blocks typically go through code, review, and deployment. BCMS Templates, Groups, and Widgets can be configured visually in the dashboard.

### Self-hosting and infrastructure

Payload's open-source core has a $0 license fee. That is not the same as $0 operational cost. Self-hosted Payload can require application hosting, PostgreSQL or MongoDB, object storage, backups, monitoring, upgrades, and incident handling.

### Payload Cloud availability

New Payload Cloud project deployments are paused. If you wanted Payload as a managed service for a new project, self-hosting is currently the supported path.

### Next.js/TypeScript architecture

Payload's Next.js integration is a strength. BCMS fits when content must serve Nuxt, Astro, Svelte, mobile apps, and multiple frontends through an API-first model.

### Content-team autonomy

Marketing and agency teams that need to modify content structures without a code deployment may prefer BCMS Templates over Payload schema changes in TypeScript.

### Maintenance and total cost of ownership

Payload TCO includes engineering time for infrastructure, upgrades, and media storage. BCMS TCO is primarily subscription plus integration work.

### Acquisition and roadmap considerations

Acquisitions cause reasonable strategic questions about roadmap direction and hosted offerings. Treat these as planning inputs, not a mandate to migrate. Payload remains MIT-licensed and actively developed.

## When you should stay with Payload

- You want self-hosting and direct database access

- Your CMS should live inside your Next.js application

- You prefer schema-as-code and PR-reviewed content architecture

- Infrastructure ownership is a requirement

## Payload CMS vs BCMS: architecture at a glance

DimensionPayload CMSBCMSCore modelCode-first CMS + app frameworkManaged headless CMSContent schemaTypeScript configVisual Templates, Groups, WidgetsHosting (new projects)Self-host; Cloud pausedManaged cloudAPIsLocal, REST, GraphQLREST via @thebcms/clientRich textLexical JSONProseMirror-style node treesLocalizationPer-field localizedPer-locale meta + contentAccess controlTypeScript in configBCMS permissions + app layer

## Payload CMS vs BCMS pricing

Payload self-hosted: $0 software license plus infrastructure and engineering. Payload Cloud: new deployments paused; no public pricing for new customers. BCMS: 14-day free trial; Hobby $5/mo ($4/mo annual); Pro $50/mo ($33/mo annual). Compare total cost of ownership, not license fee alone.

## Before migrating: Understand the content model

Payload CMSBCMSNotesCollection[Template](https://www.thebcms.com/docs/inside-bcms/templates.md)Content type definitionDocument[Entry](https://www.thebcms.com/docs/inside-bcms/entries.md) FieldTemplate propertySTRING, MEDIA, DATE, etc.GlobalSingle-entry templatePattern, not 1:1 primitiverelationshipEntry pointer{ entryId, templateId } in SDKupload / mediaMedia libraryrequestUploadToken() + createFile()arrayArray propertyMost property types support arraysblocks[Widget](https://www.thebcms.com/docs/inside-bcms/widgets.md)Manual blockType → widget maprichText (Lexical)Content nodesConversion requiredlocalized fieldsmeta + content per lng versions / _statusEntry statusesMap draft/published per localehooks / access / endpoints—Reimplement in app

Some Payload functionality is application behavior, not content: hooks, custom access-control functions, custom endpoints, authentication logic, custom admin components. These cannot be exported and imported; plan to reimplement them.

## How to migrate from Payload CMS to BCMS

### 1. Audit your Payload CMS project

Inspect collections, globals, fields, relationships, blocks, localization, uploads, drafts, access rules, and hooks. Document which concepts contain content (migratable) vs application behavior (must be reimplemented).

### 2. Create a BCMS project

Sign up at app.thebcms.com, create a project, and add languages (en, de, etc.) if you use localization.

### 3. Recreate your Payload schema in BCMS

Example Payload collections for a blog: Authors, Categories, Posts with relationships, rich text, and blocks.

```TYPESCRIPT

// src/collections/Authors.ts
import type { CollectionConfig } from 'payload'

export const Authors: CollectionConfig = {
  slug: 'authors',
  admin: { useAsTitle: 'name' },
  fields: [
    { name: 'name', type: 'text', required: true },
    { name: 'bio', type: 'textarea' },
    { name: 'avatar', type: 'upload', relationTo: 'media' },
  ],
}

```

```TYPESCRIPT

// src/collections/Categories.ts
import type { CollectionConfig } from 'payload'

export const Categories: CollectionConfig = {
  slug: 'categories',
  fields: [
    { name: 'title', type: 'text', required: true },
    { name: 'slug', type: 'text', required: true, unique: true },
  ],
}

```

```TYPESCRIPT

// src/collections/Posts.ts
import type { CollectionConfig } from 'payload'
import { HeroBlock } from '../blocks/HeroBlock'
import { FaqBlock } from '../blocks/FaqBlock'

export const Posts: CollectionConfig = {
  slug: 'posts',
  versions: { drafts: true },
  fields: [
    { name: 'title', type: 'text', required: true, localized: true },
    { name: 'slug', type: 'text', required: true, unique: true },
    { name: 'author', type: 'relationship', relationTo: 'authors', required: true },
    { name: 'categories', type: 'relationship', relationTo: 'categories', hasMany: true },
    { name: 'coverImage', type: 'upload', relationTo: 'media' },
    { name: 'publishedAt', type: 'date' },
    { name: 'content', type: 'richText', localized: true },
    { name: 'layout', type: 'blocks', blocks: [HeroBlock, FaqBlock] },
  ],
}

```

In BCMS, create templates: author, category, blog-post. Map relationships to entry pointers, uploads to media properties, and Payload blocks to BCMS Widgets (hero, faq, etc.).

### 4. Configure API access

Create a scoped API key with create/update on target templates and media permissions. Never expose write-capable keys in browser bundles.

```BASH

# .env (migration script — server/CI only, never commit)
BCMS_API_KEY=keyId.secret.instanceId
PAYLOAD_BASE_URL=https://your-payload-site.com
PAYLOAD_API_KEY=optional-if-rest-requires-auth

```

```TYPESCRIPT

import { Client } from '@thebcms/client'

export const bcms = new Client({
  injectSvg: true,
  useMemCache: false,
  enableSocket: false,
})
// Reads BCMS_API_KEY from environment by default

```

### 5. Build the migration script

Create a dedicated migration package with TypeScript, pagination, ID maps on disk, and a --dry-run flag.

```TXT

{
  "scripts": {
    "migrate": "tsx src/migrate.ts",
    "migrate:dry": "tsx src/migrate.ts --dry-run"
  },
  "dependencies": {
    "@thebcms/client": "latest",
    "dotenv": "latest"
  },
  "devDependencies": {
    "typescript": "latest",
    "tsx": "latest",
    "@types/node": "latest"
  }
}

```

```TXT

payload-to-bcms/
  src/
    migrate.ts
    payload-client.ts
    bcms-client.ts
    steps/
      migrate-media.ts
      migrate-authors.ts
      migrate-categories.ts
      migrate-posts.ts
    converters/
      lexical-to-bcms.ts
      blocks-to-widgets.ts
    utils/
      id-map.ts
      validate.ts
  migration/
    media-map.json
    authors-map.json
    categories-map.json
    posts-map.json
    migration-errors.json

```

### 6. Export content from Payload

Use the REST API with pagination, or the Local API if the script runs inside your Payload repo.

```TYPESCRIPT

// src/payload-client.ts
type PageResult<T> = {
  docs: T[]
  totalDocs: number
  hasNextPage: boolean
  page: number
}

export async function fetchAllPayloadDocs<T>(
  collection: string,
  query: Record<string, string | number | boolean> = {},
): Promise<T[]> {
  const base = process.env.PAYLOAD_BASE_URL!
  const limit = 100
  let page = 1
  const all: T[] = []

  while (true) {
    const params = new URLSearchParams({
      limit: String(limit),
      page: String(page),
      depth: String(query.depth ?? 1),
      ...Object.fromEntries(Object.entries(query).map(([k, v]) => [k, String(v)])),
    })

    const res = await fetch(`${base}/api/${collection}?${params}`, {
      headers: process.env.PAYLOAD_API_KEY
        ? { Authorization: `Bearer ${process.env.PAYLOAD_API_KEY}` }
        : {},
    })

    if (!res.ok) throw new Error(`Payload fetch failed ${collection} page ${page}: ${res.status}`)

    const data = (await res.json()) as PageResult<T>
    all.push(...data.docs)
    if (!data.hasNextPage) break
    page += 1
  }

  return all
}

```

```TYPESCRIPT

// Alternative: inside your Payload repo, use Local API
import { getPayload } from 'payload'
import config from '@payload-config'

const payload = await getPayload({ config })
const posts = await payload.find({
  collection: 'posts',
  limit: 100,
  page: 1,
  depth: 2,
  locale: 'all',
})

```

### 7. Migrate Payload media to BCMS

Migrate media first. Entries may reference images — store payloadMediaId → bcmsMediaId in migration/media-map.json so failed runs can resume without re-uploading hundreds of files.

```TYPESCRIPT

// src/steps/migrate-media.ts
import path from 'node:path'
import type { Client } from '@thebcms/client'
import { loadMap, saveMap } from '../utils/id-map'
import { fetchAllPayloadDocs } from '../payload-client'

type PayloadMedia = {
  id: string
  filename: string
  mimeType?: string
  url?: string
  alt?: string
}

function mimeFromName(name: string) {
  const ext = path.extname(name).toLowerCase()
  const map: Record<string, string> = {
    '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png',
    '.webp': 'image/webp', '.gif': 'image/gif', '.svg': 'image/svg+xml', '.pdf': 'application/pdf',
  }
  return map[ext] ?? 'application/octet-stream'
}

async function downloadPayloadFile(media: PayloadMedia, baseUrl: string) {
  const url = media.url?.startsWith('http')
    ? media.url
    : `${baseUrl}${media.url ?? `/api/media/file/${media.filename}`}`
  const res = await fetch(url)
  if (!res.ok) throw new Error(`Failed to download ${url}: ${res.status}`)
  return Buffer.from(await res.arrayBuffer())
}

export async function migrateMedia(opts: {
  bcms: Client
  payloadBaseUrl: string
  dryRun?: boolean
}) {
  const map = await loadMap('media-map.json')
  const mediaDocs = await fetchAllPayloadDocs<PayloadMedia>('media', { depth: 0 })

  for (const doc of mediaDocs) {
    if (map[doc.id]) continue
    try {
      if (opts.dryRun) {
        console.log(`[dry-run] media ${doc.id} (${doc.filename})`)
        continue
      }
      const buffer = await downloadPayloadFile(doc, opts.payloadBaseUrl)
      const uploadToken = await opts.bcms.media.requestUploadToken()
      const file = new File([buffer], doc.filename, { type: doc.mimeType ?? mimeFromName(doc.filename) })
      const created = await opts.bcms.media.createFile({ uploadToken, file, name: doc.filename })
      if (doc.alt) await opts.bcms.media.update({ _id: created._id, altText: doc.alt })
      map[doc.id] = created._id
      await saveMap('media-map.json', map)
      console.log(`Media migrated: ${doc.id} → ${created._id}`)
    } catch (err) {
      console.error(`Media failed: ${doc.id}`, err)
    }
  }
  return map
}

```

### 8. Migrate dependency collections

Migration order: Media → Authors → Categories → Posts. Maintain maps: payloadAuthorId → bcmsAuthorEntryId, payloadCategoryId → bcmsCategoryEntryId.

```TYPESCRIPT

// src/steps/migrate-authors.ts
import type { Client } from '@thebcms/client'
import { fetchAllPayloadDocs } from '../payload-client'
import { loadMap, saveMap } from '../utils/id-map'

type PayloadAuthor = {
  id: string
  name: string
  bio?: string
  avatar?: string | { id: string }
}

export async function migrateAuthors(opts: {
  bcms: Client
  mediaMap: Record<string, string>
  dryRun?: boolean
}) {
  const map = await loadMap('authors-map.json')
  const authors = await fetchAllPayloadDocs<PayloadAuthor>('authors', { depth: 1 })

  for (const author of authors) {
    if (map[author.id]) continue
    const avatarId = typeof author.avatar === 'string' ? author.avatar : author.avatar?.id
    const meta = {
      name: author.name,
      bio: author.bio ?? '',
      ...(avatarId && opts.mediaMap[avatarId]
        ? { avatar: { mediaId: opts.mediaMap[avatarId] } }
        : {}),
    }
    if (opts.dryRun) { console.log('[dry-run] author', author.id, meta); continue }
    const entry = await opts.bcms.entry.create('author', {
      statuses: [{ lng: 'en', id: 'published' }],
      meta: [{ lng: 'en', data: meta }],
      content: [{ lng: 'en', nodes: [] }],
    })
    map[author.id] = entry._id
    await saveMap('authors-map.json', map)
  }
  return map
}

```

### 9. Migrate posts and resolve relationships

Create entries with bcms.entry.create(), resolving entry pointers and media IDs from your maps. Preserve slugs and map Payload _status to BCMS entry statuses.

```TYPESCRIPT

// src/steps/migrate-posts.ts (excerpt — see full script in repo)
import type { Client } from '@thebcms/client'
import { fetchAllPayloadDocs } from '../payload-client'
import { loadMap, saveMap } from '../utils/id-map'
import { convertLexicalToBCMS } from '../converters/lexical-to-bcms'
import { convertPayloadBlocksToNodes } from '../converters/blocks-to-widgets'

function toBCMSDate(iso?: string) {
  if (!iso) return undefined
  const d = new Date(iso)
  return { timestamp: d.getTime(), timezoneOffset: d.getTimezoneOffset() }
}

export async function migratePosts(opts: {
  bcms: Client
  mediaMap: Record<string, string>
  authorsMap: Record<string, string>
  categoriesMap: Record<string, string>
  authorTemplateId: string
  categoryTemplateId: string
  dryRun?: boolean
}) {
  const map = await loadMap('posts-map.json')
  const posts = await fetchAllPayloadDocs('posts', { depth: 2, locale: 'all' })

  for (const post of posts) {
    if (map[post.id]) continue
    const authorId = typeof post.author === 'string' ? post.author : post.author.id
    const bcmsAuthorId = opts.authorsMap[authorId]
    if (!bcmsAuthorId) throw new Error(`Missing author map for ${authorId}`)

    const metaEn = {
      title: post.title?.en ?? post.title,
      slug: post.slug,
      author: { entryId: bcmsAuthorId, templateId: opts.authorTemplateId },
      categories: (post.categories ?? []).map((c) => {
        const id = typeof c === 'string' ? c : c.id
        return { entryId: opts.categoriesMap[id], templateId: opts.categoryTemplateId }
      }).filter((c) => c.entryId),
      ...(post.coverImage && opts.mediaMap[post.coverImage.id ?? post.coverImage]
        ? { coverImage: { mediaId: opts.mediaMap[post.coverImage.id ?? post.coverImage] } }
        : {}),
      ...(post.publishedAt ? { publishedAt: toBCMSDate(post.publishedAt) } : {}),
    }

    const contentNodes = [
      ...convertLexicalToBCMS(post.content?.en ?? post.content, opts.mediaMap),
      ...convertPayloadBlocksToNodes(post.layout ?? [], opts.mediaMap),
    ]

    if (opts.dryRun) { console.log('[dry-run] post', post.id); continue }

    const entry = await opts.bcms.entry.create('blog-post', {
      statuses: [{ lng: 'en', id: post._status === 'published' ? 'published' : 'draft' }],
      meta: [{ lng: 'en', data: metaEn }],
      content: [{ lng: 'en', nodes: contentNodes }],
    })
    map[post.id] = entry._id
    await saveMap('posts-map.json', map)
  }
  return map
}

```

### 10. Convert rich text

Payload Lexical rich text is stored as JSON with root.children. BCMS expects a top-level node array. There is no BCMS blockquote node — use paragraphs or headings for callouts.

```TYPESCRIPT

// src/converters/lexical-to-bcms.ts
import type { EntryContentNode } from '@thebcms/types/entry/models/content'

const FORMAT_BOLD = 1
const FORMAT_ITALIC = 2
const FORMAT_UNDERLINE = 8
const FORMAT_STRIKE = 4
const FORMAT_CODE = 16

function lexicalFormatToMarks(format = 0) {
  const marks: EntryContentNode['marks'] = []
  if (format & FORMAT_BOLD) marks.push({ type: 'bold' })
  if (format & FORMAT_ITALIC) marks.push({ type: 'italic' })
  if (format & FORMAT_UNDERLINE) marks.push({ type: 'underline' })
  if (format & FORMAT_STRIKE) marks.push({ type: 'strike' })
  if (format & FORMAT_CODE) marks.push({ type: 'inlineCode' })
  return marks.length ? marks : undefined
}

function convertBlockNode(node: any, mediaMap: Record<string, string>): EntryContentNode[] {
  switch (node.type) {
    case 'paragraph':
      return [{ type: 'paragraph', content: (node.children ?? [])
        .filter((n: any) => n.type === 'text')
        .map((n: any) => ({ type: 'text', text: n.text ?? '', marks: lexicalFormatToMarks(n.format) })) }]
    case 'heading': {
      const level = Number(String(node.tag ?? 'h2').replace('h', '')) || 2
      return [{ type: 'heading', attrs: { level }, content: [{ type: 'text', text: node.children?.[0]?.text ?? '' }] }]
    }
    case 'list': {
      const listType = node.listType === 'number' ? 'orderedList' : 'bulletList'
      const items = (node.children ?? []).map((item: any) => ({
        type: 'listItem', attrs: { list: true },
        content: (item.children ?? []).flatMap((child: any) => convertBlockNode(child, mediaMap)),
      }))
      return [{ type: listType, content: items }]
    }
    case 'upload': {
      const uploadId = typeof node.value === 'string' ? node.value : node.value?.id
      const bcmsMediaId = uploadId ? mediaMap[uploadId] : undefined
      if (!bcmsMediaId) return []
      return [{ type: 'media', attrs: { mediaId: bcmsMediaId, altText: String(node.fields?.alt ?? '') } }]
    }
    default:
      console.warn(`Unhandled Lexical node: ${node.type}`)
      return []
  }
}

export function convertLexicalToBCMS(input: unknown, mediaMap: Record<string, string>) {
  if (!input || typeof input !== 'object') return []
  const children = (input as { root?: { children?: unknown[] } }).root?.children ?? []
  return children.flatMap((node) => convertBlockNode(node, mediaMap))
}

```

Limitations: custom Lexical nodes need custom converters. Internal relationship nodes in rich text may need BCMS pointer link format. Perfect fidelity is not guaranteed — validate rendered output with BCMSContentManager.

### 11. Convert Payload Blocks to BCMS Widgets

Each Payload blockType maps to a BCMS Widget. Load widget schemas via bcms.widget.getById() and map property names to IDs in production scripts.

```TYPESCRIPT

// src/converters/blocks-to-widgets.ts
import type { EntryContentNode } from '@thebcms/types/entry/models/content'

const WIDGET_IDS = { hero: 'YOUR_HERO_WIDGET_ID', faq: 'YOUR_FAQ_WIDGET_ID' } as const

export function mapPayloadBlockToBCMSWidgetProps(
  block: { blockType: string; [key: string]: unknown },
  mediaMap: Record<string, string>,
) {
  switch (block.blockType) {
    case 'hero':
      return {
        heading: String(block.heading ?? ''),
        subheading: String(block.subheading ?? ''),
        image: block.image && mediaMap[block.image as string]
          ? { mediaId: mediaMap[block.image as string] } : undefined,
        ctaLabel: String(block.ctaLabel ?? ''),
        ctaUrl: String(block.ctaUrl ?? ''),
      }
    case 'faq':
      return { items: Array.isArray(block.items) ? block.items : [] }
    default:
      console.warn(`No widget mapping for blockType=${block.blockType}`)
      return null
  }
}

export function convertPayloadBlocksToNodes(
  blocks: Array<{ blockType: string; [key: string]: unknown }>,
  mediaMap: Record<string, string>,
): EntryContentNode[] {
  return blocks.flatMap((block) => {
    const widgetId = WIDGET_IDS[block.blockType as keyof typeof WIDGET_IDS]
    const props = mapPayloadBlockToBCMSWidgetProps(block, mediaMap)
    if (!widgetId || !props) return []
    return [{
      type: 'widget',
      attrs: {
        data: { _id: widgetId, props: Object.entries(props).map(([name, value]) => ({ id: name, data: [value] })) },
        propPath: '',
      },
    }]
  })
}

```

### 12. Preserve localization

Fetch Payload content with locale=all, then populate BCMS meta and content arrays per language.

```TYPESCRIPT

// Preserve Payload locale=all → BCMS per-locale meta/content
await bcms.entry.create('blog-post', {
  statuses: [
    { lng: 'en', id: 'published' },
    { lng: 'de', id: 'published' },
  ],
  meta: [
    { lng: 'en', data: { title: 'Hello', slug: 'hello' } },
    { lng: 'de', data: { title: 'Hallo', slug: 'hallo' } },
  ],
  content: [
    { lng: 'en', nodes: convertLexicalToBCMS(post.content.en, mediaMap) },
    { lng: 'de', nodes: convertLexicalToBCMS(post.content.de, mediaMap) },
  ],
})

```

### 13. Validate the migration

Validate before switching frontend traffic. Compare counts, spot-check relationships, and log failed records.

```TYPESCRIPT

// src/utils/validate.ts
export function printValidationReport(report: {
  media: { payload: number; bcms: number; failed: string[] }
  authors: { payload: number; bcms: number; failed: string[] }
  categories: { payload: number; bcms: number; failed: string[] }
  posts: { payload: number; bcms: number; failed: string[] }
}) {
  console.log('\nMigration complete\n')
  for (const [key, val] of Object.entries(report)) {
    console.log(`${key.padEnd(12)} ${val.bcms} / ${val.payload}`)
    for (const id of val.failed) console.log(`  failed: ${id}`)
  }
}

// Example output:
// media        142 / 142
// authors       18 / 18
// categories    24 / 24
// posts        487 / 489
//   failed: post_123

```

### 14. Run the full migration pipeline

```TYPESCRIPT

// src/migrate.ts
import 'dotenv/config'
import { bcms } from './bcms-client'
import { migrateMedia } from './steps/migrate-media'
import { migrateAuthors } from './steps/migrate-authors'
import { migrateCategories } from './steps/migrate-categories'
import { migratePosts } from './steps/migrate-posts'

const dryRun = process.argv.includes('--dry-run')

async function main() {
  const payloadBaseUrl = process.env.PAYLOAD_BASE_URL!
  const templates = await bcms.template.getAll()
  const authorTpl = templates.find((t) => t.name === 'author')!
  const categoryTpl = templates.find((t) => t.name === 'category')!

  const mediaMap = await migrateMedia({ bcms, payloadBaseUrl, dryRun })
  const authorsMap = await migrateAuthors({ bcms, mediaMap, dryRun })
  const categoriesMap = await migrateCategories({ bcms, dryRun })
  const postsMap = await migratePosts({
    bcms, mediaMap, authorsMap, categoriesMap,
    authorTemplateId: authorTpl._id,
    categoryTemplateId: categoryTpl._id,
    dryRun,
  })

  if (!dryRun) await validateMigration()
  console.log('Done', {
    media: Object.keys(mediaMap).length,
    authors: Object.keys(authorsMap).length,
    categories: Object.keys(categoriesMap).length,
    posts: Object.keys(postsMap).length,
  })
}

main().catch((err) => { console.error(err); process.exit(1) })

```

### 15. Replace Payload queries in your frontend

Install @thebcms/client and @thebcms/components-react. Replace payload.find() with bcms.entry.getBySlug().

```TYPESCRIPT

import { Client } from '@thebcms/client'

export const bcmsPrivate = new Client({ injectSvg: true })

export const bcmsPublic = new Client({
  apiKey: process.env.NEXT_PUBLIC_BCMS_API_KEY,
  injectSvg: true,
})

```

```TSX

// app/blog/[slug]/page.tsx — BEFORE (Payload)
import { getPayload } from 'payload'
import config from '@payload-config'

export default async function Page({ params }: { params: { slug: string } }) {
  const payload = await getPayload({ config })
  const result = await payload.find({
    collection: 'posts',
    where: { slug: { equals: params.slug } },
    depth: 2,
    locale: 'en',
  })
  const post = result.docs[0]
  if (!post) return null
  return <article><h1>{post.title}</h1></article>
}

```

```TSX

// app/blog/[slug]/page.tsx — AFTER (BCMS)
import { bcmsPublic } from '@/lib/bcms'
import { BCMSContentManager, BCMSImage } from '@thebcms/components-react'
import HeroWidget from '@/components/widgets/hero'

export default async function Page({ params }: { params: { slug: string } }) {
  const post = await bcmsPublic.entry.getBySlug(params.slug, 'blog-post')
  return (
    <article>
      <h1>{post.meta.en.title}</h1>
      {post.meta.en.coverImage && (
        <BCMSImage media={post.meta.en.coverImage} clientConfig={bcmsPublic.getConfig()} />
      )}
      <BCMSContentManager
        items={post.content.en}
        clientConfig={bcmsPublic.getConfig()}
        widgetComponents={{ hero: HeroWidget }}
      />
    </article>
  )
}

```

Pull generated TypeScript types in your build scripts:

```TXT

// package.json — pull generated types before build
{
  "scripts": {
    "dev": "bcms --pull types --lng ts && next dev",
    "build": "bcms --pull types --lng ts && next build"
  }
}

```

## Test and cut over to BCMS

- Build BCMS schemas and run test migration on staging

- Validate content counts and relationships

- Update frontend queries in a branch

- Freeze Payload content briefly

- Run final delta migration

- Validate counts and spot-check rich text

- Deploy BCMS-powered frontend

- Keep Payload read-only for rollback window

- Decommission Payload infrastructure only after verification

## Common Payload → BCMS migration problems

ProblemCauseMitigationBroken imagesMedia migrated after entriesMigrate media first; persist media-map.jsonMissing relationshipsWrong migration orderAuthors/categories before postsRich text looks wrongLexical ≠ BCMS nodesPartial converter + manual QABlocks disappearNo widget mappingMap each blockType to BCMS WidgetUpload token expired15-minute single-use tokenRequest fresh token per fileSlug collisionsDuplicate slugsEnsure uniqueness per template

## Payload CMS migration checklist

- Inventory Payload collections, globals, blocks, and locales

- List non-migratable logic (hooks, access, endpoints)

- Create BCMS project + languages

- Recreate templates, groups, and widgets

- Create scoped migration API key

- Implement pagination for Payload export

- Migrate media first; persist media-map.json

- Migrate authors and categories before posts

- Convert Lexical rich text and Payload blocks

- Validate counts, slugs, and relationships

- Swap frontend queries; pull generated types

- Run final delta migration before production cutover

## FAQs about Payload CMS

### Is Payload CMS still open source after the Figma acquisition?

Yes. Payload remains MIT-licensed open source with a public commitment to continued development.

### Is Payload CMS shutting down?

No. Payload continues as self-hostable open source. Existing Payload Cloud projects keep running. New Payload Cloud deployments are currently paused.

### Can I still self-host Payload CMS?

Yes. Self-hosting is unchanged and remains the primary path for new projects that choose Payload.

### Is BCMS a Payload CMS alternative?

BCMS is a managed headless CMS [Payload alternative](https://www.thebcms.com/compare/payload-alternative.md) for teams that prefer hosted infrastructure and visual content modeling. It is not a drop-in replacement for Payload-as-application-framework inside Next.js.

### Can I migrate Payload CMS content automatically?

Most content can be migrated with scripts. Hooks, custom access control, endpoints, and admin customizations must be reimplemented.

### How do Payload Collections map to BCMS?

Collections → Templates. Documents → Entries. Fields → properties. Relationships → entry pointers.

### Can Payload Blocks be migrated to BCMS Widgets?

Yes, with manual mapping per blockType. Blocks become BCMS Widgets embedded as widget nodes in rich text.

### How do I migrate Payload media to BCMS?

Download Payload media files, upload via bcms.media.requestUploadToken() and bcms.media.createFile(). Maintain a payloadId → bcmsMediaId map.

### How much does it cost to migrate from Payload CMS to BCMS?

Migration tooling is your engineering time. BCMS hosting starts at $4/mo (annual Hobby). Payload self-hosted software is free; infrastructure and ops are your cost.

## Final thoughts

Payload CMS remains a strong choice for TypeScript teams that want schema-as-code and database ownership. BCMS fits teams that prefer a managed headless CMS with visual content modeling. If you migrate, treat it as a content and schema project: map concepts carefully, migrate in dependency order, persist ID maps, validate before cutover, and be honest about rich text and block conversion limits.