Next.js boilerplate with Payload blog

The local API is the only way pages read content

• Server components and route handlers call getPayloadClient() from src/payload/local.ts and then payload.find / findByID / count. That is a function call into a Payload instance in this process, which talks straight to Postgres.
• Never fetch("/cms-api/posts") from a server component. It leaves the process, opens a connection to your own deployment, wakes a second function, serialises the whole document to JSON and parses it again: to reach code that was already loaded. It also drops the request's identity, so access rules see an anonymous caller.
• /cms-api exists for the admin panel's browser bundle and for genuine external consumers. Those are its only two callers.
• Client components never talk to Payload. Fetch in the server component above and pass plain data down as props: the Payload instance holds a database pool and cannot be serialised across that boundary anyway.

The local API bypasses access control by default

This is the single most surprising thing about Payload, and it has bitten every team that uses it:

// returns drafts, unpublished posts and everything else
await payload.find({ collection: "posts" });

overrideAccess defaults to true in the local API, because it is normally used by trusted server code. On a public page that means your carefully written read rule does nothing.

So on any page a visitor can reach:

• filter explicitly (where: { _status: { equals: "published" } }) and treat that filter as security-relevant code, not a convenience; or
• pass overrideAccess: false together with the user you resolved from the request, when you want Payload's own rules applied.

Draft content is read only when draftMode() is enabled, which only an authenticated editor can turn on through /api/blog-preview. A draft page also sets robots: { index: false } so a shared preview link cannot be indexed.

Ask for what you render

• depth: 0 unless a relationship is displayed; each level of depth is another join and another payload of fields nobody reads. depth: 1 resolves an upload or an author; depth: 2 is almost always a mistake.
• Use select to name the fields a list needs. Rich text is the biggest column on a post and an index page never renders it.
• Every list query has a limit and a sort. Unbounded find calls are fine on the ten rows you have today.
• payload.count exists; do not fetch rows to count them.

Route boundaries

• (payload) is Payload's route group and owns /cms and /cms-api, including its own root layout and CSS. Do not move those routes into the site's layout or wrap them in the site's providers.
• (frontend) is your blog. It uses the app's design tokens, not Payload's admin styles.
• Rich text renders through PostBody in src/components/cms/rich-text.tsx, which styles the generated HTML with design tokens only. No raw colours, and no dangerouslySetInnerHTML with content from the editor.

A collection change is not done until the migration is committed

• push is disabled in payload.config.ts. Payload will not quietly alter the database to match the config at boot, in development either. That is deliberate: a schema that drifts on someone's laptop is a schema nobody can reproduce.

• Every field added, renamed or removed needs:

  bun run payload:migrate:create <name>
  bun run payload:migrate
  

  and both the new file in src/payload/migrations/ and the updated index.ts go in the commit.

• Read the generated SQL before you apply it. A rename is emitted as a drop plus an add unless you edit it, which is a silent data loss on a populated table. Turn it into an ALTER TABLE ... RENAME COLUMN by hand when that is what you meant.

• Adding a required field to a collection that already has rows needs a default or a backfill in the same migration, or the migration fails on production data that passed on your empty laptop database.

• Never edit an applied migration. Payload records which ones ran; changing one after the fact means two databases with the same migration list and different schemas. Write a new migration.

• Regenerate types after a schema change so the rest of the repo type-checks against reality:

  bun run payload:types
  

• Adding a custom admin component means regenerating the import map too:

  bun run payload:importmap
  

  It writes src/app/(payload)/cms/importMap.ts: beside the admin route, because routes.admin is /cms, and as TypeScript, because admin.importMap.importMapFile pins the path. Do not let it fall back to a generated .js: the layout and the admin page import that file, and an untyped import is one the compiler cannot check.

Access control is declared, never inherited

• Every collection declares all four operations (create, read, update, delete) using the helpers in src/payload/access.ts. Payload's default when a block is missing is "any authenticated user may do it", which is how an editor ends up able to delete accounts.
• Sensitive fields carry their own access. roles on Users is the example: the collection lets a user update their own record, so without a field-level rule they could promote themselves to admin.
• Prefer returning a query constraint over false when the answer is "some rows". isPublishedOrEditor returns { _status: { equals: "published" } } so anonymous readers get published rows rather than a 403 on the whole collection.
• read: () => true is only ever correct for content that is meant to be public. Write it explicitly with isPublic so the choice is visible in review rather than implied by an absent line.
• After changing an access rule, test it as the least-privileged user that should still work, not as the admin you are logged in as.

Collection shape

• slug fields are unique, indexed, and normalised in a beforeValidate hook. A published slug is a permanent URL: add a redirect rather than renaming it.
• Anything with a public page uses drafts (versions: { drafts: ... }) so the Preview button has something to preview.
• Index every field you filter or sort by. publishedAt and slug are indexed here because every query uses them.
• Uploads declare imageSizes so the site never serves a full-resolution original, and alt is required at the schema level rather than defaulted in a component.