Payload CMS development, where the content model is the deliverable.

A global is a single document: no list view, no per-document access control, and on the Postgres adapter its own table. Right for the things there will only ever be one of, like navigation or site-wide SEO defaults. Teams reach past that line because the sidebar looks tidier, then find the Homepage global can’t be duplicated for a campaign variant, can’t carry the draft workflow the rest of the site uses, and can’t be versioned per market once localisation lands. Converting it afterwards is a data migration.

The opposite mistake is a collection holding one row forever, which makes editors hunt a list view for the only document in it and hands them a delete button for the site configuration. The rule we use: if the business could plausibly want two, it’s a collection. If two would be a bug, it’s a global.

The blocks field is what sells Payload to a marketing team and what wrecks the schema eighteen months later. Every block type is another entry in the editor’s picker and, on Postgres, another table joined on read. Forty block types is not a page builder, it’s an undocumented design system with three near-identical hero variants, because adding the second was faster than reconciling it with the first.

The test is whether the editor is choosing content or choosing layout. Content belongs in blocks. Layout belongs in the front end, as a variant select on one block rather than three blocks. Where a page is genuinely fixed, flat named fields win outright: the editor gets a form instead of a canvas, and the front end gets a type rather than a union it has to defend against.

Adding localization to the config and localized: true to a field looks like flipping a switch. What it does is change where the data lives. On Postgres, localised fields move out of the parent table into locale tables, and localised arrays and blocks cascade that structure down every nested level. Retrofit it after a year of content and you’re running a migration that lifts existing column values into the default locale for every affected field, including the ones buried inside blocks.

Fallback is the second call, and it’s not a default to accept unread. It renders the English title wherever the German one is missing, which is right for a catalogue and wrong for a legal page. Then decide whether slugs localise at all. Localised slugs buy you per-locale URLs and a routing layer to match; unlocalised slugs buy you one URL per document.

A Payload access function can return a boolean or a Where query, and that difference matters more than anything else on this page. A read function returning a constraint, tenant equals the current user’s tenant, gets pushed down into the database query, so the list view stays a single indexed lookup whether the collection holds two hundred documents or two hundred thousand. One that fetches something and returns true or false is evaluated per document, and a page of twenty-five rows becomes twenty-five extra round trips.

Field-level access is worse: it can only return a boolean, and it runs per field, per document. Ten restricted fields across twenty-five rows is 250 evaluations on every page of the list view, and any database call inside them is an N+1 you built yourself. Keep field access synchronous and derived from req.user alone.

The related trap is the Local API. payload.find runs with overrideAccess true by default, which is correct for seed scripts and catastrophic in a server component that forgot to pass the current user and overrideAccess false. That’s documented behaviour rather than a bug, and it’s the most common way a Payload app serves one tenant another tenant’s rows.

This is the version-defining change and the real reason to pick Payload over a hosted CMS. Payload 3 installs into a route group inside your App Router project rather than alongside it. The admin panel is React Server Components rather than a separate single-page app pointed at an API. getPayload gives you the Local API in-process, so a server component queries the database directly: no HTTP hop, no API token, no network latency between the CMS and the page rendering its content.

The tradeoff is that sentence read backwards. CMS and front end share a deployment, a build and a cold start. For a marketing site that’s close to ideal. It turns into a liability the moment the two want different scaling profiles: an editorial team hammering a write-heavy admin while the public site is almost entirely cached, or Sharp resizing a 40-megapixel upload on the same function meant to render pages. That’s when we split the admin onto its own instance against the same database.

Payload is MIT-licensed, so the cost moved rather than disappeared. The Postgres adapter builds a real relational schema through Drizzle, so schema changes need real migrations: generated with the CLI, committed, reviewed in a pull request, run in CI before the deploy that depends on them. Mongo removes that step and hands you the flexibility bill later, when four years of documents have three shapes and nothing ever stopped them.

Two costs accumulate quietly. Drafts with autosave write a version row per interval per document, and versions tables grow without limit unless somebody sets a max. Uploads run Sharp in the process that renders your pages, so every imageSizes entry costs CPU and memory at upload time, and a large original on a serverless function doesn’t throw a helpful error. It hits the timeout.